Documentation d’un module toolbar en PHP objet

Publié dans Projets | Marqué avec , , , , , ,
Share

Je parle ici d’une toolbar, ou BBcodeBar, permettant d’utiliser facilement du BBcode (du BNcode pour être précis) lorsque l’on écrit un article ou que l’on poste sur un forum, un commentaire… (que sais-je encore !) Bref, quelque chose qui ressemble à ça :
Exemple de toolbar
Voilà déjà pas mal de temps que j’utilise la même toolbar sur mes sites Internet. C’est une toolbar que j’ai créé et qui est basé sur une mod conçue à l’origine pour le système de forum FluxBB (ex-PunBB) par Vin100. A chaque fois, je la modifie et je galère pour l’intégrer correctement au site du momenet, et surtout je me retape tout le travail dès que je dois modifier quelque chose. Voilà pourquoi depuis quelques jours, quand l’envie me prend, je développe une version PHP objet de cette toolbar de façon à la rendre plus portable, plus paramétrable et aussi plus performante. J’approche désormais de la fin, et donc de la première publication d’une version 1. Voici donc un premier jet de documentation, entre autre, pour vérifier que rien n’a été oublié.

But

  • Créer une toolbar permettant d’utiliser facilement du BBcode (user friendly)
  • Créer un système de gestion de toolbars complet et paramètrable : génération de plusieurs toolbars, paramétrage du contenu des toolbars, désactivable ou désinstalable en 1 clic (surtout coder friendly)
  • Mettre en pratique mes connaissances en PHP objet, et améliorer celles en Javascript

Côté programmeur

Le module toolbar est constitué d’une classe tout simplement nommée Toolbar. Une fois instanciée, cette classe contient toutes les attributs et méthodes nécessaire pour créer et utiliser des toolbars.

Certaines méthodes permettent une utilisation basique et simple de ce module :

  • traitement_administration() : permet d’afficher le module d’administration.
  • afficher_administration(option d’affichage encore à préciser) : permet d’effectuer les traitements du module d’administration. (à placer après la connexion à la BDD et avant tout affichage)
  • afficher_toolbar(‘nom_toolbar’) : permet d’afficher la toolbar ayant pour nom ‘nom_toolbar’. (le fichier correspondant sera tlb_nom_toolbar.php dans le dossier de cache) Mais il existe d’autres méthodes pour effectuer des actions plus fines :
  • generer_cache_toolbar(nom_toolbar, id_textarea, chemin_img_bouton, chemin_img_smilie, nb_smilie, chemin_fichier_js) : permet de générer une toolbar.
  • generer_cache_smilie() : permet de générer un fichier de cache des smilies.
  • set_chemin_cache, get_chemin_cache : pour modifier et afficher la valeur de l’attribut cheminCache. (chemin vers le dossier de cache contenant le fichier de configuration, les toolbars générés, et les fichiers pour les pop up) Certains paramètres sont modifiables via la partie d’administration mais tous les paramètres systèmes (nom des tables, chemin vers le dossier de cache, …) ne sont modifiables qu’à l’aide de méthodes (set_table_bouton, set_table_smilie, set_fichier_config, set_chemin_cache, …) ou directement en modifiant la valeur des attributs concernés dans la classe Toolbar.

Côté administrateur

Installation

Une fois les fichiers du module copié au bon endroit sur un serveur, l’installation se fait facilement via la partie d’administration. Elle se résumé en la création de 2 tables MySQL tlbr_bouton, tlbr_smilie, et d’un fichier de configuration tlbr_param.php (dans le dossier de cache) contenant les configurations par défaut. Le noms des tables, du fichier de configuration, ainsi que des configurations par défaut, peuvent être modifiés en changeant la valeur d’attributs de la classe Toolbar. !!Désinstallation La désinstallation se fait très facilement via la partie administration. Il suffit de supprimer les 2 tables MySQL tlbr_bouton, tlbr_smilie, ainsi que le fichier de configuration tlbr_param.php (dans le dossier de cache). !!Gestion des paramètres par défaut Les paramètres par défaut sont : état du module toolbar (si le module est désactivé, toutes les toolbars seront désactivés), chemin vers le dossier où se trouvent les images des boutons, chemin vers le dossier où se trouvent les images des smilies, nombre de smilies à afficher sur la toolbar avant de mettre un lien « Plus d’infos » (si besoin), chemin vers le fichier javascript servant à afficher la toolbar.

Ce sont les paramètres utilisés par défaut lorsque l’on essait de générer une toolbar. Ils sont aussi utilisés lorsque l’on gère les boutons ou les smilies. !!Gestion des boutons et des smilies Les gestionnaires de boutons et de smilies permettent de créer une banque de données de boutons et smilies utilisable dans une toolbar et qui apparaitront dans une toolbar s’ils sont activés lors de sa génération. !Gestion des boutons Pour ajouter un bouton il faut :

  • Préciser son nom. Ce nom sera utilisé pour la balise BBcode (par exemple : [nom][/nom]), et pour le fichier image correspondant (par exemple : nom.png). Vous pouvez préciser ce nom, ou uploader directement une image, le nom de l’image sera alors utilisé. Mais vous pouvez aussi uploader une image et préciser un nom (ne vous souciez pas de l’extension du fichier), l’image sera alors renommée.
  • Préciser son état. (activé ou non)
  • Préciser son type : bouton standard (ajoute simplement [nom]texte[/nom]), bouton Javascript (avec 1 ou 2 fenêtes Javascript possible dont le texte est paramétrable. Utile par exemple pour [nom=texte]texte[/nom]), bouton PopUp (ouvre le pop up nom.php du dossier include/. Un color picker est pré-intégré pour les valeurs color, et bgcolor. Un système d’upload est en cours de conception pour la valeur upload), bouton barre (affiche une barre supplémentaire d’icône lorsque l’on clique sur le bouton. Une barre de smilies est déjà configurée pour la valeur smilie. De même qu’une qu’une barre math pour la valeur math, si latex est installé) bouton séparateur (espace de 10px permettant de mettre en page sa toolbar)
  • Préciser un message d’aide. Il est possible de préciser plusieurs phrases d’aide en les séparant par des pipes (ctrl+alt+6 donne un pipe | ). La première phrase d’aide apparaitra au survol du bouton (par exemple : Mettre en gras : [b]texte[/b]), la deuxième phrase d’aide apparaitra dans le première fenêtre Javascript (si bouton de type Javascript), la troisième phrase apparaîtra dans la deuxième fenêtre Javascript (si bouton de type Javascript). Les phrases d’aides peuvent aussi être utilisées dans les boutons de type PopUp.
  • Préciser l’ordre dans la toolbar. L’ordre est calculé automatiquement s’il n’est pas précisé. Les boutons créés sont modifiables et supprimables à la volet. (/!\ la suppression d’un bouton n’entraine pas la suppression de l’image correspondante)

Gestion des smilies

Pour ajouter un smilie il faut :

  • Préciser son nom. Ce nom sera utilisé pour le fichier image correspondant (par exemple : nom.png). Vous pouvez préciser ce nom, ou uploader directement une image, le nom de l’image sera alors utilisé. Mais vous pouvez aussi uploader une image et préciser un nom, l’image sera alors renommée. Dans tous les cas, ne vous souciez pas de l’extension du fichier.
  • Préciser son symbôle. C’est-à-dire les caractères qu’il faut écrire (l’émoticône) pour ajouter un smilie à un message. Il est possible de préciser plusieurs symbôles en les séparant par des pipes (ctrl+alt+6 donne |). En effet, un fichier de cache des smilies est généré lors de la génération d’une toolbar et permet donc de créer automatiquement un programme de transformation d’émoticônes en smilies. (système encore non implémenté)
  • Préciser son état. (activé ou non)
  • Préciser l’ordre dans la toolbar. L’ordre est calculé automatiquement s’il n’est pas précisé. Les smilies créés sont modifiables et supprimables à la volet. (/!\ la suppression d’un smilie n’entraine pas la suppression de l’image correspondante)

Générer une ou plusieurs toolbars

Lors de la génération d’une toolbar (ce qui va générer en réalité un fichier tlbr_nom_toolbar.php dans le dossier de cache), il est possible de préciser des paramètres (qui sont pré-remplis avec les valeurs par défaut) :

  • chemin vers le dossier où se trouvent les images des boutons
  • chemin vers le dossier où se trouvent les images des smilies
  • nombre de smilies à afficher sur la toolbar avant de mettre un lien « Plus d’infos » (si besoin)
  • chemin vers le fichier javascript servant à afficher la toolbar. La toolbar générée va donc contenir tous les boutons et smilies activés au moment de sa génération, et utiliser le chemin vers les dossiers où se trouvent les images des boutons et des smilies, et le fichier Javascript, précisé au moment de sa génération.

Côté utilisateur

L’utilisateur simplement une toolbar au dessus des champs textes dans lesquels il peut écrire. Lorsqu’il passe sa souris sur les boutons un message d’aide s’affiche et s’il clique dessus, l’action demandée s’exécute. Si l’utilisateur n’a pas activé Javascript, un message le prévient qu’il pourrait écrire plus facilement s’il l’activait.

Divers

A la lecture de cette documentation, on voit que ce module fonctionne très bien tout seul et a été conçu pour s’implanter de manière transparente dans n’importe quel site Web. Cela dit, ce module ne se charge pas du parsage du BBcode. (ou similaire) On peut aussi remarquer que dans ce module, j’ai prévu la base pour pouvoir ajouter un système de parsage BBcode généré automatiquement. A vrai dire, j’ai un projet de BNcode (langage similaire au BBcode) déjà bien avancé, donc un couplage de ces 2 projets est tout à fait envisageable?

A faire

  • Passer les valeurs par défaut du fichier de conf dans les attributs.
  • Ajouter un champ d’upload lorsqu’on modifie les smilies et les boutons
  • Etat désactivé du module
  • setCheminCache….
  • Erreur bouton espace
  • Cleaner appellation fichier config
  • afficher_administration(option d’affichage encore à préciser)
  • generer_cache_toolbar(‘tlbr_nom_toolbar.php’, ) -> refaire le nom si besoin
  • cleaner la documentation et la procédure d’installation (en éparpillant moins les fichiers peut-être)

Laisser un commentaire

Votre adresse e-mail ne sera pas publiée. Les champs obligatoires sont indiqués avec *