Developpement de module : Etape 4

Retour à l'index

4ème étape : L'anatomie profonde d'un module Moodle

Une fois tous ces préparatifs effectués et une bonne idée de son application, il est temps d'observer l'anatomie d'un module Moodle. Quels sont les fichiers "classiques", ceux que la plate-forme voit, quels rôles ont ils dans la plate-forme, comment Moodle les exploite ?

Le fichier "version.php"

Indispensable et pas très compliqué. Il informe Moodle de deux ou trois choses :

• Quelle est la version déclarée du module (date + sous-index à deux chiffres)
• Quelle est la version minimale requise de Moodle pour faire tourner le module.
• Enfin, toutes les combien de secondes le cron (tâche régulière) doit venir activer la fonction spéciale "cron" de ce module.

Le fichier "index.html"

Indispensable : c'est lui qui permet d'atteindre (et d'afficher) la liste des instances de ce type d'objet pédagogique dans un cours. (liste des ressources, liste des tests, etc.).

Sa structure est simple : on vérifie le login, on récupère l'ensemble des instances d'un certain type dans le cours courant, et on construit une table avec trois quatre informations clefs qui intéressent l'utilisateur.

Ce fichier est à retoucher, car copié d'un autre module, les informations à afficher pour l'extrait ne proviennent pas nécessairement des mêmes champs.

Le fichier "mod.html"

super-indispensable : Le fichier "mod.html" permet à Moodle d'atteindre l'écran de modification de l'instance. Un module étant constitué d'un enregistrement principal pour enregistrer toutes les instances utilisées sur la plate-forme, chaque instance dispose d'un certain nombre de paramètres de configuration particuliers qui sont des champs additionnels de cette table. Le fichier mod.html contient le formulaire qui permet, pour une instance donnée, d'en modifier tous les paramètres.

"mod.html" est constitué de deux grandes parties :

• La première est une initialisation des valeurs par défaut de certains paramètres. Ceci peut être important pour :

• • définir des valeur effectives pour certains paramètres qui restent NULL dans la base de données si on ne les a jamais définis.
  • fixer une valeur utilisable pour des paramètres booléen pilotés par des cases à cocher (on rappelle qu'une case à cocher non cochée ne renvoie STRICTEMENT RIEN au serveur)
• La deuxième est un formulaire HTML complet qui met en scène les divers widgets de contrôle de chacun des paramètres d'instance. On peut rajouter autant de lignes (... que l'on veut pour ajouter des entrées de valeurs à soi. Quelques unes sont "typiques" (voir la discussion précédente sur le modèle de données).

Le formulaire travaille en ETROITE COLLABORATION avec deux fonctions (callbacks) de la librairie principale (librairie d'API de module, celle qui rassemble les fonctions OBLIGATOIRES qu'un module DOIT fournir à Moodle). On doit trouver ces fonctions dans le fichier "lib.php" du module.

Ces deux fonctions clefs qui fonctionnent avec le formulaire "mod.html" sont :

• <module>_add_instance($instance)
• <module>_update_instance($instance)

$instance est un objet complètement initialisé par les données récupérées du formulaire. Une entrée de formulaire non reportée comme champ dans la base et l'insertion ou la mise à jour d'enregistrement échoue.

mod.html, ces deux fonctions, et le modèle de données (table principale du module) doivent donc toujours être modifiés de façon synchronisée.

Depuis la version 1.8 et la mise en œuvre d'une API de formulaires de fichier mod.html est remplacé par un fichier mod_form.php qui "programme" le formulaire de paramétrage.

Le fichier "icon.gif"

Ça parait idiot mais on pourrait l'oublier comme ressource "standard". C'est l'icône qui apparaîtra dans le cours pour symboliser l'activité.

Le fichier "lib.php"

C'est LA librairie des fonctions où Moodle va chercher les divers callbacks qui lui apportent des informations "standard" sur le module.

• <module>_add_instance($instance)
• <module>_update_instance($instance)
• <module>_delete_instance($id)

Ces trois fonctions indispensables permettent d'exécuter les trois opérations de gestion typique (CRUDE). Nous détaillerons leur structure et les précautions de développement dans une prochaine discussion.

• <module>_cron()

est le callback appelé par le script général cron.php de Moodle, lorsque l'horloge interne détermine qu'il faut exécuter cette action automatisée sur le module (c.f. plus haut).

• <module>_grades($cmid)

est un callback qui renvoie le carnet de notes de l'instance à Moodle, afin que la plate-forme l'intègre dans son carnet de notes global pour l'étudiant. Cette fonction DOIT retourner un combiné de deux tableau associatif : { 'grades' => { userId => array of double }, 'maxgrades' => { userId = > array of double }}.

Le premier tableau renvoie les notes obtenues, le deuxième renvoie les notes maximales (ex : je renvoie pour l'utilisateur 23 les notes 7/20 et 13/15 :

{ 'grades' => { 23 => (7, 13)}, 'maxgrades' => { 23 => (20, 15)}}

Un module peut donc renvoyer une série de notes pour chaque étudiant.

ATTENTION : Le module "carnet de notes", développé par Nicolas Connault et disponible à partir de Moodle 1.9 risque de proposer une nouvelle stratégie.

• <module>_print_recent_activity(&$logs, $isteacher=false)
• <module>_get_participants($newmoduleid)
• <module>_scale_used($cmid, $scaleid)

Ces fonctions sont des fonctions d'information qui permettent à Moodle d'afficher quelques données relatives au module dans certains contextes.

La première permet de demander au module de lui fournir la liste des activités récentes. Elle admet aussi une autre forme <module>_print_recent_activity($course, $isteacher, $timestart) et il faudra que je vérifie la version qui fonctionne désormais. Son travail consiste de façon typique, à examiner les "logs" généraux de Moodle en filtrant sur les clefs d'actions spécifiques au module. (tiens, je sens qu'il faudra une discussion à part pour les stratégies de "journalisation" ).

La deuxième rend à Moodle la liste des participants. Je n'ai pas encore trouvé où Moodle l'exploite (Valery Fremaux 27 jun 2007 à 16:06 (CDT)).

La troisième renvoie à Moodle une indication sur l'usage des barèmes. Elle n'est utile que si votre module utilise les barèmes (encore une discussion à venir sur l'implantation d'un système d'évaluation dans votre module). Sinon, elle doit retourner false. Elle permet, lors de l'édition des barèmes dans un cours, de compter le nombre de fois où ce barème est utilisé.

<module>_user_outline($course, $user, $mod, $project)

est une fonction utilisée par la génération de rapports sur les activités au niveau plate-forme.

<module>_user_complete($course, $user, $mod, $project)

idem mais pour les rapports détaillés.

Les fonctions très spécifiques et internes au module sont en général rassemblées dans une librairie annexe, appelée "locallib.php".

Les librairies très spécifiques, rassemblant une API particulière à un sous-composant pourront faire l'objet de librairies complémentaires, nommées selon le schéma <component>lib.php (ex. treelib.php, filesystemlib.php). Certaines de ces librairies pourraient à terme être candidates à remonter dans les librairies du cœur si elles s'avèrent collectivement utiles.

Le fichier "view.php"

Le fichier "view.php" EST LE FICHIER qui réalise TOUS les écrans de votre module.

La structure de ce fichier ne doit pas être trop complexe. Elle doit essentiellement demeurer un "aiguilleur" en fonction de macro-situations du module. Ces macros situations sont calculées entrée de page et donnent en général lieu à une donnée $action.

Les différents cas à traiter sont soit des cas issus de la segmentation des utilisateurs : on ne voit pas les mêmes choses en tant qu'enseignant, en tant qu'élève, et pour certains modules récents, selon l'adhésion à certains "rôles" qu'il faudra donc penser à définir (c'est une bonne idée que de glisser les requêtes de création des rôles nécessaires au module dans le script d'installation du module), soit il s'agit de grandes phases d'action (l'activité n'est pas encore commencée, l'activité est close, etc).