par Mark West
Developer PostNuke
Original document can be found at Author's website or directly HERE
Traduction : Chestnut ! pnConcept.com - PostNuke-France.org

$Revision: 1.3 $

Copyright © 2004 Mark West

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation, with no Invariant Sections, no Front-Cover Texts and no Back-Cover Texts.
A copy of the license can be obtained from the Free Software foundation.


Historique
Revision 0.1 07 Janvier 2004 Initial Version
Revision 0.2 07 Janvier 2004
Section 2 ajoutée - Fonctionalités additionnelles du module Example.
Corrections des fautes et d'une valeur manquante dans le formulaire de modification.

Sujet
Ce document contient une série de notes sur la portabilité du code d'un module pnHTML vers un code pour le pnRender.

Audience visée
Developpeurs

---

• 1. Convertir un module pnHTML en module pour le pnRender
  • 1.1. Commencer avec le panneau d'administration.
  • 1.2. Créer le template du menu admin
  • 1.3. Enlever les fonction admin et les appels de fonction du fichier pnadmin.php
  • 1.4. Enlever les utilisation du pnHTML des message d'erreur
  • 1.5. Transférer l'objet de création de sortie
  • 1.6. Mise en cache du panneau admin
  • 1.7. Transférer les en-têtes
  • 1.8. Travailler systématiquement toutes les fonctions de sortie
  • 1.9. Modifier la sortie retournée
  • 1.10. Assigner les données au template
  • 1.11. Ajouter les données retournées au template
  • 1.12. Le reste......
• 2. Fonctionnalités additionnelles du module Example
  • 2.1. En-têtes de table
  • 2.2. Conformités HTML
  • 2.3. Hooks
  • 2.4. Le future de PN .8
    • 2.4.1. Tags et attributs désuets
    • 2.4.2. Accessibilité
    • 2.4.3. Commentaires du PHPDoc

Intro

Ce document n'a pas pour mission d'être un tutoriel définitif ou pour les débutants sur la conversion de modules pnHTML en module pour le pnRender, il a seulement pour but d'offrir des conseils, astuces et un guide que le développeur pourra suivre lors du transfert d'une méthodologie à une autre. Il est adressé aux personnes étant familières avec le code à modifier, le pnHTML et l'architecture du pnRender.

Ces astuces sont basées sur des mois de travail sur le pnRender lors de la conversion des modules Core pour la version de PostNuke 0.8.

Le module Example est fourni aux développeurs en démonstration d'une écriture adaptée à l'API de postnuke et ses modules avec pour méthodologie de sortie, le pnRender. Puisque cette méthodologie est en constante évolution, il est bon de regarder le CVS pour ce module afin d'avoir la dernière version du code et les derniers templates utilisés qui n'auraient pas été encore distribué. La version CVS du module Example est accessible à  cette adresse :
http://cvs.postnuke.com/viewcvs.cgi/PostNuke/Modules/Miscellaneous/Example/.

Maintenant, tout préambules étant mis sur table, regardons le trasfert d'un peu de code pnHTML pour le pnRender.

1. Convertir un module pnHTML en module pour le pnRender

1.1. Commencer avec le panneau d'administration.

Comme celui-ci est une simple inclusion d'un template dans un autre, c'est un bon début. Prenez une copie du module Example et modifiez-le en remplaçant les noms de fonctions et les constantes de langue pour les vôtres.

1.2. Créer le template du menu admin

Comme celui-ci est une simple inclusion d'un template dans un autre, c'est un bon début. Prenez une copie du module Example et modifiez-le en remplaçant les noms de fonctions et les constantes de langue pour les vôtres.

1.3. Enlever les fonctions admin et les appels de fonction du fichier pnadmin.php

Maintenant, enlevez toute trace de la fonction du menu admin du code php. Il y aura 2 sections ici; la première, la fonction example_adminmenu et tous les appels de cette fonction dans le reste du code.

1.4. Enlever les utilisations du pnHTML des messages d'erreur.

Nous enlevons le pnHTML utilisé dans tous les messages d'erreur. Cela permet la simplification du module. Le code suivant :

devient

1.5. Transférer l'objet de création de sortie

Nous changeons l'objet pnHTML en objet pour le pnRender, le code suivant :

// Création de l'objet de sortie - Cet objet contiendra tout le rendu qui sera
// retourné au besoin.
$output = new pnHTML();
becomes

// Création de l'objet de sortie - Cet objet contiendra tout le rendu qui sera
// retourné au besoin.
$pnRender =& new pnRender();
L'utilisation du & est importante car elle réduit considérablement la mémoire utilisé pour l'application. L'ancienne méthode du style HTML créait un duplicata de la classe du pnHTML pour notre module. Le & indique que c'est une référence à la classe du pnRender qui est créée et non pas un copie de la classe au complet dans la mémoire.

1.6. Mise en cache du panneau admin

Pour le menu admin, il est vraisemblable de ne pas vouloir le mettre en cache alors nous désactivons la mise en cache :

1.7. Transférer les en-têtes

Toutes les pages admin ont une série d'en-têtes alors nous commencerons le transfert par celles-ci.

Nous avons déjà enlevé le code du menu admin à l'étape 1.3 alors nous ajoutons d'abord le menu au template.

Code:

Toutes les pages devraient avoir un titre affichant l'action que l'utilisateur est en train de faire dans le module.

Code:

devient

Template:

Toute page contenant un formulaire doivent avoir une en-tête de formulaire. Cette en-tête contient l'adresse de destination.

Code:

devient

Template:

Toutes les pages contenant un formulaire doivent avoir un ID identifiant d'autorisation.

Code:

devient

Template:

Note: Nous avons ajouté le nom du module - La fonction pnSenGenAuthKey prend un paramêtre (optionnel) du nom du module et les développeurs devraient activement l'utiliser.

Finalement, nous avons le tag de fermeture du formulaire.

Code:


devient

Template:

1.8. Travailler systématiquement toutes les fonctions de sortie.

J'ai trouvé avantageux de commenter tout le pnHTML d'une fonction pour ensuite le travailler par "morceau" d'une sortie à la fois jusqu'à ce que chaque "morceau" soit transformé. Par "morceau", j'entend des segments de comme celui-ci :

Enlever la mise en commentaire d'un morceau. Premièrement, réduire le "segment" à sa forme la plus simple en enlevant le pnHTML d'état pour que le code devienne :

Maintenant, dans le template, ajoutez la mise en forme correspondante. e.g.

Template:

<tr>
<td></td>
<td></td>
</tr>
Ajoutez ensuite la constante de langue en utilisant le plugin pnml dans le template et retirez cette constante du php. e.g.

Code:

Template:

Et finalement, ajouter le champs de formulaire et retirez-le du php.

Template:

Répétez l'opération pour chaque segment de pnHTML dans la fonction courante.

1.9. Modifier la sortie retournée

Plutôt que de retourner le contenu d'un objet pnHTML, nous retournons le contenu d'un objet pnRender. L'évocation de la sortie :

// Retourne le rendu généré par cette fonction
return $output->GetOutput();
devient

// Retourne le rendu généré par cette fonction
return $pnRender->fetch(<nom_du_template_incluant_son_extension>);

1.10. Assigner les données au template

Pour les formulaires contenant des données (modifier, configuration, etc.), nous devons donner au template ces données. Habituellement, une fonction API récupère les données dans la base de données. i.e@:

// Une fonction API user est appelée. Elle prend l'identifiant de l'item
// que nous avons obtenu et récupère les informations appropriées pour cet item.
// Si l'item n'éxiste pas, un message d'erreur approprié est retourné.
$item = pnModAPIFunc('Example', 'user', 'get', array('tid' => $tid));
Maintenant que nous avons l'item, nous l'assignons simplement au template i.e.

// Assigne le tableau de l'item au template
$pnRender->assign('item', $item);
Similairement, nous assignons au template les variables de module de la même façon i.e.

// Gras
$pnRender->assign('bold', pnModGetVar('Example', 'bold'));

1.11. Ajouter les données retournées au template

Nous avons une structure de template et nous avons assigné des données à ce templates. L'étape finale est d'ajouter les données dans le template selon les besoin de la fonction (modifer, afficher, configuration, etc.).

Utilisant les exemples de formulaire de l'étape 1.8 et l'assignation des données de l'étape 1.10

deviendrait alors

Note: Si vos valeurs contiennent du HTML, alors changez le modificateur pnvarprepfordisplay pour pnvarprephtmldisplay.

1.12. Le reste......

Les étapes 1.7-1.11 doivent être répétées pour chaque fonction de l'administration qui retourne un objet de rendu. Pour le module Example, les fonctions sont example_admin_new, example_admin_modify, example_admin_view and example_admin_modifyconfig. A ce stade, vous devriez avoir passé à travers l'administration. Alors Testez !, Testez !, Testez !.

La partie utilisateur contient moins de formulaire alors vous aurez besoin de prendre chaque module comme ils viennent mais les étapes précédentes donnent une idée du processus qui fonctionne pour moi. Du travail supplémentaire doit être fait pour trouver une stratégie de mise en cache pour l'interface utilisateur. Voyez le module Example pour avoir un exemple fonctionnel de mise en cache de contenu.

En espérant que ces notes serviront à au moins une personne ;). Comme indiqué dans l'intro, ces notes suggèrent une procédure qui a fonctionné pour moi - rien de plus, rien de moins. Chaque développeur aura sans aucun doute ses propres chemins et ses propres méthodes. Tout commentaire, suggestion, ajouts, écrivez-moi à markwest at postnuke dot com. Toute plainte et insultes, écrivez à b dot gates at Microsoft dot com.......

2. Fonctionalitées Additionnelles du module Example

Cette section couvre quelques fonctionalitées additionnelles pouvant être trouvées dans le module Example. Certaines peuvent se retrouver uniquement dans le CVS selon la version distribuée du code du module Example.

2.1. En-Têtes de tables

Beaucoup de modules pnHTML formattent les tables en appelant directement les méthodes Row et Column de la classe pnHTML. L'inconvénient est que les tables dans ces modules n'utilisent pas les en-têtes de table (th). Faites toutes les tables contenant des en-têtes avec le tag d'en-tête TH. Comme par exemple dans la fonction admin view du module Example

2.2. Conformité HTML

Toujours prendre en compte la conformité HTML. De la version de PN 0.726, le noyau était à 95% conforme au HTML 4.01 transitionel. Il est important de vérifier votre code à travers un validateur de HTML avant sa distribution. Le W3C Validator peut se trouver à cette adresse : http://validator.w3.org.

2.3. Hooks

Toujours s'assurer que votre module supporte les hooks de transformation et d'affichage quand cela est approprié. Pour tester un hook de transformation, utilisez le module autolink. Pour le hook d'affichage, celui du module Rating.

2.4. Le futur de PN .8

Au niveau de la mise en template, il y a diverses opérations que vous pouvez faire avec votre module pour vous assurer qu'il est conforme aux standards établis par PN .8. Ces opérations sont en constante évolution donc lorsque vous développez, surveillez toujours le CVS.

2.4.1. Tags et attributs désuets

Bien que strict au niveau HTML, bien des tags et attributs sont désuets et ne sont pas recommandés. Assurez-vous que vos templates n'utilisent pas ces tags et attributs. Quelques exemples :

Tag Font e.g. <font class="pn-normal"> - remplacez ceci par un span ou un div e.g.<span class="pn-normal">. Les polices devraient être contrôlées par la feuille de style.

Attribut align du tag div e.g. <div align="center">- La feuille de style du thème devrait contrôler la composition du div. Pour passer outre l'attribut par défaut du thème, utilisez un style interne. e.g. <div style="text-align:center;">

2.4.2. Accessibilité

Assurez-vous que vos templates produisent un code 'accessible'. C'est important pour diversifier l'audience de PN et de votre module. Autant PN .7x ne prenait pas d'engagement en ce sens, PN .8 est actuellement testé à travers de nombreux vérificateur d'accessibilité et l'équipe de développement prend de l'expérience à produire du code accessible.

e.g. Tous les éléments d'un formulaire devraient avoir un libellé et ce libellé devrait être associé avec l'élément du formulaire correspondant avec l'utilisation de l'attribut 'for' sur le libellé et l'attribut 'id' pour l'élément du formulaire. Un élément du formulaire de l'étape 1.11

devient

2.4.3. Commentaires du PHPDoc

PHPDoc est utilisé pour générer des commentaires automatiquement sur des parties du code. Le module Example est documenté avec phpdoc. Lors de votre transfert et création, considérez l'utilisation de phpDoc pour commenter votre code. Tous les détails sur phpDoc à cette adresse : http://phpdocu.sourceforge.net.