Initiation à la création de modules


Cette documentation concerne principalement la future version 0.8 de PostNuke

Cette page à pour but de vous donner les bases concernant la création de modules. Il est nécessaire d'avoir quelques bases d'informatique concernant l'utilisation des tables mysql, des notions de php, des notions générales de programation (fonctions, classes) et d'algorithmie.

Afin d'avoir un exemple concret, le module que nous allons faire va demander à l'utilisateur son année de naissance, va la sauvegarder puis en tirer des statistiques.

Un module blank existe dans votre dossier /modules. C'est à partir de celui-ci que vous aller créer votre premier module. Voyons tout d'abord comment est constitué ce module:

|-modules
...|-pndocs (1)
......|-changelog.txt
......|-credits.txt
......|-help.txt
......|-licence.txt
...|-pnlang (2)
......|-eng
.........|-admin.php (3)
.........|-user.php (4)
.........|-version.php (5)
...|-pnstyle (6)
.........|-blank.css
...|-pntemplates (7)
......|-blank_admin_main.tpl
......|-blank_admin_menu.tpl
......|-blank_user_main.tpl
...|-pnadmin.php (8)
...|-pnadminapi.php (9)
...|-pnuser.php
...|-pnuserapi.php
...|-pninit.php (10)
...|-pnversion.php (11)

1. pndocs : Ca pourrais parraître la partie la plus facile à remplir de votre module, mais non. La documentation est vitale dans un module. mettez des pages html, des exemples des permissions nécessaires, une procédure d'installation et tout ce qui pourra aider les utilisateurs. Une documentation bien faite soulage les forums.

2. Le dossier pnlang contient lui même des dossiers nommé aux noms des langages

3. Fichier contenant toutes les constantes de langue pour la partie administration

4. Fichier contenant toutes les constantes de langue pour la partie utilisateur

5. Fichier contenant toutes les constantes de langue concernant les paramètres du module (son nom courant et "technique", sa description)

6. Dossier contenant tout les fichiers de styles du module.

7. Les templates sont des fichiers contenant du code HTML exclusivement. Ils permettent l'interfacage avec le code php.

8. Fichier appelé lors de la génération d'une page. Il fait l'interface entre les templates et l'accès à la base de donnée ou plus généralement, il fait l'interfacage entre l'affichage et la gestion des données. Il fonctionne de manière symétrique avec le pnuser.php

9. Fichier gérant les données. Ce fichier est appelé exclusivement par pnadmin.php

10. Fichier appelé lors de l'initialisation du module. Il va mettre les variables dans leur premier état. Ce fichier est aussi appelé lors de la suppression du module

11. Fichier contenant la version, le nom de l'auteur et toutes les information concernant la création du module.

On peut voir que l'on a deux types prédéfinis : 'user' et 'admin' mais rien ne vous empêche d'en créer d'autres. ex : clients, revendeur, ... Ces types se retrouvent dans les fichiers pn---.php, pn---api.php, /pnlang/XXX/---.php et dans tous les templates.

appel des fonctions d'un module


index.php?module=<module>&type=<type>&func=<func>
  • module représente le nom du module
  • type représente le type d'appel : user ou admin (défaut: user)
  • func représente le nom de la fonction appelée (défaut: main)

Renommage du module


Nous allons maintenant procéder au renommage du module. Il faut tout d'abord dupliquer le module "Blank" et le renommer en "statsage" (statistiques age) puis ouvrir tous les fichiers à l'aide d'un éditeur favoris (voir ici).

L'opération à faire est un "chercher et remplacer" en respectant la casse :
  1. Chercher "blank" et remplacer par "statsage" avec "respect de la casse" coché
  2. Chercher "Blank" et remplacer par "statsage" avec "respect de la casse" coché ("b" majuscule)
  3. Chercher "BLANK" et remplacer par "STATSAGE" avec "respect de la casse" coché
  4. Renommer les fichiers
    • /pnstyle/blank.css en /pnstyle/statsage.css
    • blank_admin_main.tpl en statsage_admin_main.tpl
    • blank_admin_menu.tpl en statsage_admin_menu.tpl
    • blank_user_main.tpl en statsage_user_main.tpl

Activer le module


Maintenant que le module est entièrement renommé, vous povez aller dans le panneau d'administration, modules, régénérer la liste, initialiser le module statsage et activer le module statsage.

Vous pouvez accéder au panneau d'administration de ce module via le lien index.php?module=statsage&type=admin (func est par défaut "main") et accéder à la page utilisateur via le lien index.php?module=statsage (func est par défaut "main" et type est par défaut "user")

Personnalisation du module en fonction des besoins


Création et suppression de la base de donnée


Il faut créer un fichier pntables.php à la racine du module. Nous l'écrirons de cette manière:

<?php
function statsage_pntables()
{
    $pntable = array();
    $pntable['statsage_listepersonnes'] = 
       pnDBGetTablePrefix('statsage')  . '_statsage_listepersonnes';
     // correspond au nom de la table dans la base de donnée (nomdumodule_table)
    $pntable['statsage_listepersonnes_column'] = // (nomdumodule_table_column)
                                array ( 'uid' => 'pn_uid',
                                        'age' => 'pn_age',
                                        );
    //autres tables pour le module au cas ou !
    return $pntable;
}
?>


  • uid correspond à l'identifiant de l'utilisateur (user id).
  • age correspond à l'age enregistré par la personne dans la base de donnée.

Ensuite aller dans le fichier pninit.php et modifier la fonction statsimage_init() et statsimage_delete()

function statsage_init()
{
    $sql = "pn_uid I AUTO PRIMARY,
            pn_age I NOTNULL DEFAULT '0'";

    if (!DBUtil::createTable('statsage_listepersonnes', $sql)) {
        pnSessionSetVar('errormsg', _CREATETABLEFAILED);
        return false;
    }
    return true;
}



function statsimage_delete()
{
    $dbconn  = pnDBGetConn(true);
    $pntable = pnDBGetTables();

    $listepersonnestable  = $pntable['statsage_listepersonnes'];

    $dict = NewDataDictionary($dbconn);

    // crée le script SQL la table
    $sqlarray = $dict->DropTableSQL($listepersonnestable);

    // execute la requête SQL ou génère un message de session qui sera affiché juste après.
    if ($dict->ExecuteSQLArray($sqlarray) != 2) {
        pnSessionSetVar('errormsg', _EXAMPLEDBDROPTABLEFAILED);
        // Renvoie false en cas d'erreur
        return false;
    }
   
    return true;

}


Appel du formulaire


Nous voulons que ce formulaire soit appelé par défaut quand on appel le module. Nous allons donc appeler ce module dans la fonction main.
Dans le fichier pnuser.php, on va modifier la fonction statsage_user_main()

function statsage_user_main()
{
    // Vérifie si l'utilisateur a le droit en lecture
    if (!SecurityUtil::checkPermission('statsage::', '::', ACCESS_READ)) {
        return pnVarPrepHTMLDisplay(_MODULENOAUTH);
    }

    $pnRender = new pnRender('statsage'); // crée une nouvelle instance de pnRender afin d'appeler le template
    $pnRender->assign('moyenne',pnModAPIFunc('statsage', 'user', 'moyenne')); //assigne à la variable 'moyenne' la valeur de retour de la fonction de calcul de la moyenne.

    return $pnRender->fetch('statsage_user_main.tpl'); //appel du template

}


Nous allons maintenant modifier le template statsage_user_main.tpl

<!--[* commentaire *]-->
<h2><!--[pnml name='_STATSAGEMOD_TITLE']--></h2>
<p style="text-align:center;"><!--[pnml name='_STATSAGEMOD_MOYENNEACTUELLE']--> <!--[$moyenne]--></p>
<form action="<!--[pnmodurl modname=statsage type=user func=validateage]-->" method="post" enctype="application/x-www-form-urlencoded">
<p style="text-align:center;"><!--[pnml name='_STATSAGEMOD_ENTREZAGE']--> <input type="text" id="age" /></p>
</form>


<!--[pnmodurl modname=statsage type=user func=validateage]-->


La fonction smarty pnmodurl permet la transformation en url (cet exemple renvoi index.php?module=statsage&type=user&func=validateage )

Il faut modifier le fichier pnuserapi.php afin de gérer l'appel à pnModAPIFunc('statsage', 'user', 'moyenne')

function statsage_userapi_moyenne()
{
// utilisation de la classe DBUtil (/includes/pnobjlib/DBUtil.class.php )
     $tableau_age = DBUtil::selectFieldArray ('statsage_listepersonnes','age');

     $nb_elems = array_count_values($tableau_age);
     $somme_age = array_sum($tableau_age);

    return $somme_age / $nb_elems;
}


et enfin gérer la réception du formulaire par le fichier pnuser.php et pnuserapi.php

function statsage_user_validateage()
{
  $object = array(
  'age' => FormUtil::getPassedValue('age'),
  'uid' => pnUserGetVar('uid')
  );
 
  pnModAPIFunc('statsage', 'user', 'setage', $object);
  return true;
}


ajoutez dans le fichier pnuserapi.php

function statsage_userapi_setage($args)
{

    if(DBUtil::selectField('statsage_listepersonnes','age','uid='.$args['uid']))
    {
        DBUtil::updateObject($args, 'statsage_listepersonnes');
    }
    else
    {
        DBUtil::insertObject($args, 'statsage_listepersonnes');
    }
    return true;
}


Ménage


Un petit peu de ménage ne peut faire que du bien maintenant à votre module. Comme il n'y a pas de partie administration à notre module, on peut supprimer le template blank_admin_main.tpl et blank_admin_menu.tpl les fichiers pnadmin.php, pnadminapi.php


Conclusion


Cette initiation à l'écriture de modules vous a permis de vous lancer. Tous les autres modules disponibles dans la version 0.800 de PostNuke peuvent servir d'exemple. Ils sont tous écris de la même manière, fonctionnent avec des templates. La sécurité est un point primordial dans votre site. vérifier les droits utilisateurs à chaque appel de fonction est nécessaire. Si vous avez des questions, des commentaires, n'hésitez pas à les faire dans le forum.
A faire: vérifier le module, tester le code...


Développement?
XML Revisions of $tag
Page history :: Last Editor : Chestnut :: Owner : Gilles ::
Valid XHTML∞ :: Valid CSS∞ :: Powered by pnWikka 1.0∞ (A wiki fork from WikkaWiki∞)
 

Commentaires

Seuls les utilisateurs enregistrés peuvent ajouter un commentaire. S'enregister/S'identifier