Eléments de cours : concevoir des nouveaux types d'éléments

Un type d'élément est un "sous-plugin" qui réside dans le répertoire "type" de la distribution du module Customlabels (/mod/customlabel/type).

Il repose sur une classe de base customlabel_type. Un nouveau type doit être une extension de cette classe.

Un type est un composant qui définit un micro-modèle de données. Cette description sera automatiquement utilisée par le formulaire de "nouvelle instance" d'Elément de Cours pour compléter le formulaire avec les champs appropriés du sous-type. Ce micro-modèle définit des variables qui seront alors disponibles pour alimenter un "template" (ou modèle de contenu), défini dans les fichiers de langue. Chaque type peut donc fournir une traduction multilingue de sa représentation, et le contenu des variables texte du modèle peuvent contenir des balises de contenu multilingue.

Le template peut contenir n'importe quelle séquence de HTML avec des "emplacements" pour le données.

Par exemple :

  $string['template'] = '
      <table><tr><th><%%title%%></th></tr><tr><td><%%value%%></td></tr></table>
  ';

est un template élémentaire qui produit une table avec un titre et une cellule unique, introduisant deux variables 'title' et 'value' issues de la définition du micro-modèle.

Des templates plus riches permettent de jouer avec du HTML, du Javascript et des définitions de style pour un contenu au comportement plus complexe.

Constitution du plugin

Le répertoire contenant le nouveau type doit contenir :

• Un fichier customlabel.class.php, définissant une classe :

  class customlabel_type_NEWTYPE extends customlbel_type {
  }

• Un fichier de style customlabel.css pour le formatage graphique "par défaut" du type
• Un fichier de version aux normes des plugins de Moodle :

  $plugin = new SdClass();
  $plugin->version = 'xxxxxxxxxxx';
  $plugin->component = 'customlabeltype_NEWTYPE';

• Un répertoire de langue (obligatoirement la langue anglaise en 'en', puis la langue française dans un sous-répertoire 'fr'
• Un répertoire "db" et un fichier access.php pour la déclaration des deux capacités principales ('view' et 'addinstance') pour le type.

Construction du micro-modèle de données

La construction du micro-modèle de données se fait dans le constructeur de la classe du type, qui doit définir deux membre 'standard" d'un sous-type d'élément de cours :

  $this->type = 'NEWTYPE';
  $this->fields = array();

Le micro-modèle consiste à ajouter à la définition des champs des descripteurs des données à gérer dans le template. La définition d'un champ élémentaire ressemble au modèle suivant :

  $field = new StdClass();
  $field->name = 'NEWFIELD';
  $field->type = 'FIELD_TYPE';
  $field->attr1 = ATTR_VALUE;
  ...
  $this->fields['NEWFIELD'] = $field;

Les attributs (attr1, attr2) et leurs valeurs possibles dépendent en général du type de données. POur tout nouveau champ, il faudra veiller à ajouter la clef NEWFIELD et sa traduction dans les fichiers de langue.

Types de champs

Champ texte simple (textfield)

La donnée est éditable comme en champ de texte simple. Elle produit une valeur de type texte.

• Attributs:
  • size : Définit l'attribut SIZE du champ de texte (INPUT).
  • maxlength : Définit l'attribut MAXLENGTH du champ de texte (INPUT).

Champ texte html (editor)

La donnée est éditable comme un editeur de texte wysiwyg. Elle produit une valeur de type HTML.

• Attributs: (pas d'attributs)

Choix binaire (choiceyesno)

La donnée est éditable sous forme d'une liste déroulante à deux valeur "oui/non". Elle produit une variable à valeur 1 ou 0;

• Attributs : (pas d'attributs)

Liste directe de valeurs (list)

La donnée définit une liste fermée de valeurs possibles, les traductions affichables des choix sont définies de manière définitive dans le fichier de langue du type d'élément de cours, ou éventuellement directement dans la classe du type (sans traduction).

• Attributs :
  • straightoptions : Si true, alors l'affichage des options ne cherche pas à traduire les options par la fonction get_string(), mais utilise les valeurs d'option désignées.
  • options : un tableau associatif d'options (clef->valeur).
  • multiple: Si true, permettra un choix multiple

Source indirecte de données (datasource)

La donnée et choisie dans une liste obtenue indirectement par une source de données externes.

• Attributs :
  • source : Définit le type de source de données. Cet attribut peut prendre trois valeurs : 'dbfieldkeyed', 'dbfieldkey', et 'function', des attributs optionnels dépendent de la valeur de la source.
  • multiple: Si true, permettra un choix multiple

Source de données : Donnée indexée en base de données (dbfieldkeyed)

Les données sont directement extraites d'une table de la base de données Moodle à travers une requête SQL sélective. Cette requête est construite à partir des attributs supplémentaires ajoutés à la définition :

• Attributs spécifiques :
  • table : Pointe la table Moodle où les données sont stockées
  • key : Pointe le champ de la table où la clef sur les données est stockée
  • field : Pointe le champ de la table où les données sont stockées
  • select : Fournit le contenu de la clause WHERE pour discriminer les données retenues
  • ordering : Fournit le contenu de la clause ORDER BY pour ordonner la liste générée.

Note : la requête SQL construite avec ces paramètres indexera systématiquement les valeurs sélectionnées sur le champ id de la table utilisée si l'attribut key n'est pas défini.

Source de données : Clef indexée en base de données (dbfieldkey)

Similaire au précédent, mais seules les clefs sont lues dans la base de données. Les traductions 'affichables' à l'usage doivent être définies dans un fichier de langue dans un domaine à choisir par la configuration du champ :

• Attributs spécifiques :
  • table : Pointe la table Moodle où les clefs sont stockées
  • field : Pointe le champ de la table où les clefs sont stockées
  • select : Fournit le contenu de la clause WHERE pour discriminer les clefs retenues
  • ordering : Fournit le contenu de la clause ORDER BY pour ordonner la liste générée.
  • domain : Le domaine de traduction (le nom d'un composant dont les fichiers de langue détiennent les traduction des clefs récupérées).

Source de données : Fonction (function)

Les données de la liste sont obtenues à travers une fonction qui doit retourner un tableau associatif clefs => valeurs.

• Attributs spécifiques :
  • file : Définit le fichier où est définie la fonction
  • function : désigne la fonction. Cette fonction doit renvoyer un tableau associatif.

Clefs minimales de langue

Les fichiers de langue doivent avoir au minimum les clefs suivantes :

  $string['NEWTYPE:view'] = 'Can view the NEWTYPE';
  $string['NEWTYPE:addinstance'] = 'Can add an instance of NEWTYPE';
  $string['pluginname'] = 'New Type';
  $string['typename'] = 'New type name';
  $string['configtypename'] = 'Explanations of type';
  $string['template'] = 'HMTL CONTENT WITH PLACEHOLDERS';

Les autres chaines dépendent de la structure interne du micro-modèle de données.