Turorial de Création d'un Composant pour Mambo 4.5

VO de Joseph Lawrence LeBlanc ( http://www.jlleblanc.com/comtutor/ )

 traduit en francais par blandou

e-mail:  Cet e-mail est protégé contre les robots collecteurs de mails, votre navigateur doit accepter le Javascript pour le voir design: © 2002-2004 by Joseph Lawrence LeBlanc

Ce guide devrait vous aider à construire un composant fonctionnel, avec une interface complète. Après avoir lu cette aide, vous devriez comprendre comment certaines des classes de Mambo fonctionnent et les employer au mieux pour construire votre propre composant. Une version finie, entièrement instable de Daily Message est disponible en cliquant ici. Le tutorial est valable pou Mambo 4.5 1.0.7.

Tous les gens vont comprendre le fonctionnement d’un composant de Mambo de manière différente. Les développeurs avec une expérience significative du PHP souhaiterait peut-être commencer avec dailymessage.php (le fichier qui génère la page principale) et admin.dailymessage.php (qui génère l’interface). D’autres vont vouloir commencer avec le document XML qui fournit les sorties de chaque code source, image, et requête SQL.

toolbar.dailymessage.html.php

Ce fichier définit la classe menuDailyMessage qui a trois fonctions pour les trois différents menus utilisés.

Bien sûr, le code devrait seulement  être exécuter à partir de Mambo.

Pour beaucoup de ces fonctions, le premier paramètre à soumettre est la  variable ‘task’. Pour la fonction deleteList(), la première variable est un message alternatif optionnel pour l’alerte "are you sure you want to delete this" (êtes vous sûr de vouloir effacer ceci). La deuxième variable est ‘task’  et la dernière fournit la propriété de l’image ‘alt’ à afficher. Cette fonction est disponible pour les autre boutons aussi. Les fonctions startTable() et endTable() fournissent les bons débuts et fin du code de la table. La fonction divider() affiche une barre verticale qui sépare visuellement les icones.

La fonction back() affiche simplement l’icône ‘cancel’(annuler) avec le texte ‘back’(retour). Lorsqu’on clique dessus, on retourne à la page précédente.

La fonction spacer() fournit quelques espaces en plus entre les icônes.

toolbar.dailymessage.php

Pour tous les composants, Mambo charge le code à partir de l’interface d’admin. La création de ce code vraiment simple puisque le fonctionnement est très bien défini. Le code de ce fichier est essentiellement une partie de choix de chemin qui charge la bonne barre d’outils basée sur les variables ‘task’ et ‘act’.

D’abord, vérifez que le code est bon  en dehors de Mambo et chargez le fichier  toolbar.dailymessage.html.php, qui va prendre la sortie HTML pour le menu.

Notez que les deux tâches ‘new’(nouveau) et ‘edit’(affiche) partage le même menu. Cela ne doit pas causer de conflit car le menu lance simplements des tâches et n’est pas fonctionnellement dépendant de la tâche courante. La tâche courante et ‘act’ déterminent simplement quelles options vont être affichées. L’intégralité des menus sont appelés au travers des fonctions contenues dans menuDailyMessage class du fichier toolbar.dailymessage.html.php.

Encore une fois ce code ne devrait pas être appelé en dehors de Mambo

Cette classe étend la classe mosDBTable, qui fournit beaucoup de fonctions utiles qui rendent plus facile le transfert de données – vers et de – la base de données.

Premièrement, les variables identiques à celles trouvées dans la base de données sont déclarées. Ce faisant, les autres pièces du code peuvent créer les objets joeDailyMessage, les charger avec les variables désirées puis les envoient à la base de données.

Ce constructeur prend un objet de la base de données passé par référence et le passe le long du constructeur hérité mosBDTable, avec le nom de table [ # _ nomtable pour ‘mos’] nous souhaitons mettre la référence et le nom du champ contenant la clef

primaire.

La classe joeDailyMessageConf marche exactement de la même manière que la classe joeDailyMessage, en contenant les variables trouvées dans la table mos_joe_dailymessage_conf et en référençant ‘configid’ comme la clé primaire.

admin.dailymessage.html.php

Cette ligne est là pour s’assurer que le code va être appelé de Mambo et non par quelque visiteur parasite

class HTML_joeDailyMessage{

Cette classe est appelée en premier à partir du fichier admin.dailymessage.php et prend en compte la majorité des sorties HTML pour l’interface d’administrateur.

function edit( $option, &$row ) {

Cette fonction prend le nom du composant (com_dailymessage) et une ligne de base de données chargée à partir du code admin.dailymessage.php et affiche un écran où l’administrateur peut éditer un message journalier.

Si une ligne de la base de données a été fournie, les champs du formulaire seront remplis. Notez que l’élément ‘published’(publier) est pris en compte par la classe mosHTML et fonction yesnoSelectList.

La classe mosHTML est déclarée dans le répertoire classes/mambo.php et est disponible dans tout Mambo. Cette fonction génère une liste avec les valeurs ‘no’ et ‘yes’. Si la valeur de la variable $row -> published est 0, ‘no’ va être sélectionné, sinon si la valeur est 1, ‘yes’ va être sélectionné. Cela peut être très utile pour créer des interfaces d’administration et est pris en compte plus gracieusement qu’une case à cocher.

Finalement, les variables cachées contenant l’id du message du jour, le nom du composant et les tâches sont placés dans le formulaire et dans les renvois des fins. La variable ‘task’ est initialisée à null de sorte que le Javascript de la bare d’outils puisse le remplir plus tard selon quel bouton est activé.

Cette fonction est appelée pour afficher le panneau de configuration où l’administrateur peut mettre en forme l’affichage des messages journaliers.

Ce formulaire est rempli avec les données venant de la première ligne de la table mos_joe_dailymessage_conf  (Il ne devrait y avoir qu’une seule ligne). La fonction yesnoSelectList() rend plus facile de s’assurer que les valeurs représentées dans le formulaire sont correctes.

Finalement, les variables ‘option’, ‘task’, ‘configid’, et ‘act’ sont cachées dans le formulaire. La variable ‘configid’ rassure quant à la mise à jour de la configuration enregistrée, de toute manière il ne devrait y en avoir qu’une.

La variable ‘act’ dit au code de admin.dailymessage.php de sauver ou annuler la configuration de l’écran et non pas le message de l’écran. Cela est pris en compte par le système de ‘switch’ dont on a parlé au débue de ce document.

Cette fonction renvoie l’écran par défaut que l’admin voit quand il clique sur ‘edit messages’ dans le menu principal.

Cette en-tête de table étiquette toutes les colonnes et fournit une case à cocher principale qui sélectionnera chaque message du formulaire quand elle sera cochée.

Ceci débute une boucle qui va boucler à travers toutes les lignes de la base de données dans le tableau des $rows.

<tr class="<?php echo "row$k"; ?>">

Ceci prend le style pour la ligne dans la feuille de style selon que c’est une ligne 0 ou 1. On commence par la ligne 0 et on la change par la ligne 1,  dans les deux sens, pour créer un effet alternatif qui rend la table plus lisible.

<td><input type="checkbox" id="cb<?php echo $i;?>" name="cid[]" value="<?php echo $row->id; ?>" onclick="isChecked(this.checked);" /></td>

Ceci affiche une case à cocher et fournit une voie d’identification pour plus tard quand le formulaire sera soumis. Chaque identifiant de case à cocher est enregistré comme cbX, où X est la position numérique dans la liste à laquelle la case à cocher appartient. Le nom est spécifié comme un tableau et la valeur est affectée de celle de l’identifiant trouvé dans la base de données.

<td><a href="http://www.joomlafrance.org/Les_Dossiers/Les_Composants/Mambo_4.5.x_-_Tuto_-_Creation_de_Composant.html#edit" onclick="return listItemTask('cb<?php echo $i;?>','edit')"><?php echo $row->message; ?></a></td>

Ceci crée des liens contenant le text du message. Lorsqu’on clique dessus, le lien va automatiquement cocher la case au début de la ligne et dire au Javascript de soumettre les formulaire avec la tâche ‘edit’.

Ceci renvoie la date du message, affichée en accord avec le format local par la fonction mosFormatDate qui est déclarée dans le répertoire class/mambo.php

Ceci affiche à la fois les icônes ‘published’ et ‘unpublished’, selon les paramètres du message. Si l’icône est activée, le formulaire est soumis avec le statut opposé comme tâche.

<?php $k = 1 - $k; ?>

Ceci change la variable qui détermine la couleur de fond de la ligne. Les 1 deviennent des 0 et les 0 deviennent des 1.

Ceci cache les variables ‘option’, ‘task’ et ‘boxchecked’ à la fin du formulaire. A la fois ‘boxchecked’ et ‘task’ sont modifiés plus tard par le Javascript. ‘boxchecked’ est utilisé pour s’assurer que les items sont cochés avec qu’une tâche ne soit exécutée.

admin.dailymessage.php

Ce fichier contrôle l’écran que l’administrateur voit en configurant les composants. Beaucoup de l’HTML réel est généré a travers HTML_joeDailyMessage (il y a qqchose qui pourrait ressembler à du narcissisme J) trouvé dans le fichier admin.dailymessage.html.php.

Ceci produit une vérification pour s’assurer que l’utilisateur est bien l’admin.

Ces deux lignes incluent les fichiers admin.dailymessage.html.php et dailymessage.class.php. La fonction getPath() retourne les chemins entiers appropriés et les noms des fichiers.

L’écran principal a un formulaire avec une liste de cases à cocher portant le nom de ‘cid’. La fonction mosGetParam() recherche ce tableau et l’enregistre dans $id. Si le tableau n’est pas présent (comme quand la première page est chargée), $id est reconnu comme un tableau vide afin de prémunir contre les erreurs futures.

Maintenant c’est le bon moment pour parler des différences entre $task et $act. Quand l’admin clique sur un bouton comme ‘publish’ or ‘save’, la sélection doit être communiquée au composant. Ceci est réalisé grâce à la variable $task. Ces boutons sont utilisés pour beaucoup de formulaires différents et il devient nécessaire pour le composant de savoir quel formulaire est en train de transmettre à ce moment précis. C’est là où la variable $act arrive. Dans le menu principal des composants, la sélection de Daily Message a deux options de sous menu : Edit Message et Configure. Ces options sont référées par $act par respectivement ‘all’ et ‘configure’.

Le composant daily message utilise l’état du switch pour déterminer la conduite à tenir. L’état de sortie du switch es basé sur la variable $act, comme ‘all’ et ‘configure’ utilise des noms de tâches de recouvrements. Donc la valeur de $act est déterminée en premier, puis vient $task.

Maintenant la définition des fonctions pour prendre en compte le début des différentes tâches. La première va mettre à jour la BD avec de nouvelles variables quand quelqu’un clique sur le bouton ‘save’ de la page de configuration. Premièrement, la variable $option est passée à la fonction et devrait être initialisée à com_dailymessage par l ‘environnement de Mambo. Cela va permettre au code d'expédier de nouveau plus tard l'utilisateur au panneau d'administration pour ce composant. Après, l’objet $database est tiré de la fonction. Alors on déclare un objet $row de type joeDailyMessageConf [définit dans dailymessage.class.php], qui est une extension de mosDBTable. Les objets basés sur mosDBTable ont beaucoup de fonctions simplifiant l’enregistrement dans la base de données.

Ce code tente d’utiliser le code hérité de la fonction bind() de mosDBTable pour récupérer la forme des variables à partir du POST et les copie dans l’objet $row.  Si la tentative est un échec, une erreur Javascript est affichée est le code est stoppé. L’erreur Javascript est affichée comme une alerte pop up avec un bouton qui retourne à la page précédente.

Cette partie de code tente de stocker les informations dans l’objet $row dans la base de données. La prise en compte des erreurs est similaire à celle de la section ci dessus.

Si tout est un succès, l’utilisateur est redirigé vers la page de configuration et les message "Configuration Saved"  est affiché dans le haut de l’écran dans de jolis caractères oranges. La variable $option , passée à la fonction du formulaire avant contient la chaîne de caractère 'com_dailymessage' et dit a Mambo de tirer le panneau d’administration du composant Daily Message.

Notez que l’URL possède la variable ‘act’ initialisée à ‘configure’. Si cela n’est pas  fait , l’utilisateur va être redirigé vers la page d’administration par défaut de Daily Message : message editing.

Cette fonction charge la configuration courante à partir de la base de données et l’affiche  sur un formulaire où les variables peuvent être éditées pour suivre les désirs de l’admin. La requête appropriée est appelée et le résultat est chargé dans l’objet $rows comme une liste d’objets.

S’il y avait une erreur en cours de requête, ce code va afficher une erreur et stopper la fonction, autorisant encore Mambo de finir de charger la page sans les données de configuration.

Ceci appelle la fonction listConfiguration à partir de l’objet HTML_joeDailyMessage du fichier the dailymessage.class.php , en passant le nom du composant et l’objet avec son information de configuration.

Quand l’admin veut publier un message, cette fonction initialise le drapeau ‘publish’ de ce message à 1. En prmeier, on determine si oui ou non l’admin a choisi un item à publier. Si non, une erreur doit être affichée en référence à la page précédente. La ligne où $action est initialisée est une version sténo d’un if. La variable est initialisée à ‘publish’ si c’est vraique $publish = 1, sinon, la variable est initialisée a ‘unpublish’. Une alerte Javascriptest affichée renvoyant l’utilisateur en arrière.

Si on a un item à publier, on initialise la chaîne de caractères $ids comme une liste de toutes les variables dans le tableau $id et sépare les variables avec des “,”. Ceci va simplifier l’insertion dans le SQL.

Une requête est envoyée à la base de données et toutes les erreurs sont affichées au travers du javascript.

L’admin est redirigé à la page principale de l’interface d’admin  de Daily Message.

Cette fonction, est a peu près identique a saveConfiguration(), seulement elle déclarerow comme étant de type joeDailyMessage et redirige à la page par defaut avec le message ‘saved’.

Une liste de messages journaliers à effacer est passée à cette fonction. S’il n’y a pas d’items dans le tableau $cid un message d’erreur approprié est affiché et l’admin est renvoyé à la page précédente.

Si les messages à effacer ont été sélectionnés, une requête les efface de la base.

La requête de délétion est exécutée et l’admin est renvoyé à l’écran par défaut.

Quand l’admin sélectionne un message a éditer, cette fonction charge un message approprié de la base vers l’objet $row. Un admin ne peut éditer qu’un message à la fois, le premier id du tableau $uid est choisit.

La fonction edit() est appelée de la classe HTML_joeDailyMessage qui génère la sortie HTML appropriée pour l’écran. La ligne de la base et le nom du composant courant sont passés donc le code approprié peut être généré.

Cette fonction finale est appelée pour afficher l’écran par défaut. Si aucune tâche n’a été choisie, cette fonction va lister tous les messages donc l’admin peut effacer, éditer, publier ou  non ses messages.

La requête est faite pour rechercher le contenu entier de la table. Ils sont ordonées par id comme ce champs est un auto_increment. Alors une clé unique peut être générée et les messages vont être listés par ordre de création.

La requête est exécutée et s’il y a des erreurs, elles sont simplement écrites dans la page de résultat. La fonction listMessage() dans la classe HTML_joeDailyMessage est alors appelée pour générer l’HTML nécessaire à la liste de l’écran.

Dailymessage.php

Ce fichier affiche ce que le visiteur va voir lorsque le composant est chargé. Ce code est simple, c’est tout ce qu’il y a besoin pour générer l’HTML nécessaire à l’installation de Mambo. C’est le seul fichier copié dans le dossier components/com_dailymessage.

Cette ligne s’assure que le code est bien appelé par Mambo.

global $database;

L’objet $database est déclaré autre part dans Mambo. ‘global’ le rend disponible ici.

Envoyer une requête SQL dans Mambo est un processus à deux temps. En premier, on utilise la fonction setQuery() pour entrer le SQL. Ensuite on utilise une fonction comme loadObjectList() pour rechercher les résultats. La ligne $row=$rows[0] enregistre les variables à partir du premier objet de la liste dans le tableau $row. Dans ce cas, on recherche l’information de configuration dans la base qui devrait être un seul enregistrement.

Dans les requêtes mySql a travers Mambo, #_  est remplacé par le préfixe des noms de tables.  Cela rend possible pour des applis faites pour Mambo de partager la mêm base de données. Cette fonctionnalité peut être très utile si l’hébergeur n’autorise qu’une seule base.

Après avoir chargé les résultats dans un tableau, nous sommes capables de rechercher les valeurs individuelles à partir des résultats de la requête ds des variables qu’on pourra utiliser plus tard.

Ces choses construisent les fins et débuts des chaînes de carctères basées sur les settings de la base de données. Ces chaînes de caractères vont être utilisées après pour formater le message.

En utilisant le même objet $database que précédemment, on envoie la requête pour tirer de la table contenant les messages tous les objets dans $row .

Maintenant on commence le code HTML. Le ?> permet de fermer le php temporairement pour de l’HTML jusqu’à ce qu’on atteigne un nouveau < ?. Cela produit le même résultat que la balise echo.

cette boucle passe par les différents objets de $rows et charge leur contenu dans $row. Alors nous sommes capables de prendre les informations et de construire des chaînes de caractères qui vont renvoyer un vrai format HTML.

?></table>

Fermeture du tableau.

Dailymessage.xml

<?xml version="1.0" ?>

Cette balise définit la version de XML utilisée dans ce document. Beaucoup de fichiers XML en circulation sont écrits en version 1.0. Voilà un lien pour en apprendre plus sur XML ici.

La balise mosinstall dit a Mambo quelle extension préparer. Ce code installe un composant en opposition à un module ou un template.

Ces balises identifient le composant avec un nom, une date de création, un auteur, un copyright, un e_mail de l’auteur  et son site et un nombre de version. Cette info est affichée plus tard dans la section d’administration du composant.

Les balises <files> entourent une liste de fichiers pour la page principale qui sont eux même entourés par de balises <filename>.

Dans ce cas, une seul fichier est utilisé.

Les requêtes d’installation qui initialisent les tables utilisées par le composant sont encadrées par des balises <query>, qui sont toutes entourées par des balises <install>.

2 tables sont crées : une pour les messages et une pour la configuration du composant. En plus des valeurs initiales sont insérées dans la table de config.

<uninstall> entoure les requêtes nécessaires à la suppression des tables utilisées par le composant. Ces requêtes ne sont exécutées que quand l’admin le désire.

Ces fichiers sont copiés dans le dossier administrator/com_dailymessage.

<administration> entoure tout ce qui est demandé par l’interface d’administration <menu>entoure le titre qui apparaît sur le menu d’administration des composants de Mambo.

<submenu> entoure les items de menu qui apparaitront quand daily message sera sélectionné.

La propriété ‘act’ est utilisée par le backend pour déterminer quel écran d’admin est à afficher.

Ces fichiers seront copiés dans le dossier administration/com_dailymessage