Blocs (développeur)

Remarque : la traduction de cet article n'est pas terminée. N'hésitez pas à traduire tout ou partie de cette page ou à la compléter. Vous pouvez aussi utiliser la page de discussion pour vos recommandations et suggestions d'améliorations.

Un guide pas à pas pour créer des blocs

Le présent document est un guide qui s'adresse aux développeurs désireux de créer leur propres blocs dans Moodle. Il s'applique seulement à la version 1.5 de Moodle (et plus récentes), étant donné que le sous-système de blocs a été réécrit et étendu à la sortie de la 1.5. Toutefois, vous pouvez aussi le trouver utile si vous voulez modifier des blocs écrits pour Moodle 1.3 et 1.4 et les rendre compatibles avec les dernières versions (voir Annexe B).

Ce guide a été écrit comme un cours interactif dont le but est de développer un bloc configurable qui affiche du HTML arbitraire. Il vise principalement les personnes avec peu d'expérience sur Moodle ou la programmation en général et vise à montrer comment il est facile de créer de nouveaux blocs pour Moodle, bien qu'un minimum de connaissances en PHP soit toujours requis.

Les développeurs expérimentés et ceux qui veulent juste un texte de référence peuvent se référer à l' Annexe A, ce guide principal ayant une plutôt faible concentration d'information brute.

Concepts de Base

Tout au long de ce guide, nous suivrons la création d'un bloc "HTML" de A à Z dans le but de montrer la plupart des options de blocs à notre disposition. Notre bloc sera nommé "SimpleHTML". This does not constrain us regarding the name of the actual directory on the server where the files for our block will be stored, but for consistency we will follow the practice of using the lowercased form "simplehtml" in any case where such a name is required.

Partout où nous nolus référerons à un nom de fichier ou de catalogue qui contient "simlpehtml", il est important de retenir que nous ne pouvons changer seulement la partie "simplehtml"; le reste est standardisé et essentiel pour que Moodle fonctionne correctement.

Où qu'un chemin de fichier soit mentionned dans ce guide, il commencera toujours par un slahs. Cela faire référence au dossier racine de Moodle; tous les fichiers et répertoires seront nommés relativement à ce répertoire.

Prêt, Partez!

Pour définir un "bloc" dans Moodle, dans la plupart des cas de base nous aurons besoin de fournir seulement un fichier source. Nous commençons par créer le répertoire /blocks/simplehtml/ et créer un fichier nommé /blocks/simplehtml/'block_simplehtml.php qui contiendra notre code. Ensuite, commençons à coder le block :

<?php class block_simplehtml extends block_base {

 function init() {
   $this->title   = get_string('simplehtml', 'block_simplehtml');
   $this->version = 2004111200;
 }
 // Les balises PHP et les accolades pour la définition de classe 
 // seront seulement fermées après l'ajout d'une autre fonction, dans le prochain chapitre.

La première ligne est la définition de la classe de notre bloc; elle doit être nommée exactement comme c'est écrit. Par contre, seule la partie "simplehtml" peut (en fait, doit) changer; tout le reste est standardisé.

Ensuite, donnons à notre classe une petite méthode : init(). C'est essentiel pour tous les blocs, et son but est de créer les deux variables de classe listées à l'intérieur. Mais que signifient ces valeurs en réalité? Voici une description plus en détails.

$this->title est le titre affiché dans le header du bloc. Nous pouvons lui donner la valeur que nous voulons; in this case it's set to read the actual title from a language file we are presumably distributing together with the block. I 'll skip ahead a bit here and say that if you want your block to display no title at all, then you should set this to any descriptive value you want (but not make it an empty string). We will later see how to disable the title's display.

$this->version est la version de notre bloc. En réalité, cela fera une différence seulement si votre bloc doit garder ses propres valeurs dans des tables spéciales de la base de données (i.e. pour des blocs très compliqués). Dans ce cas, le numéro de version est utilisé exactement comme pour les activités; un script de mise à jour l'utilise pour mettre à jour les "anciennes" données du bloc vers les dernières. Nous passerons sur ce procédé, puisque les blocs ont tendance à être relativement simples et ne contiennent pas leurs propres données privées.

Dans notre exemple, c'est certainement le cas où nous mettons juste $this->version à YYYYMMMDD00 et pouvons l'oublier.

MISE A JOUR :
Avant la version 1.5, la structure de base de chaque classe de bloc était légèrement différente. Référez-vous à l' Annexe B pour plus d'informations à propos des changements sur les anciens blocs pour les rendre conformes au nouveau standard.

I Just Hear Static

In order to get our block to actually display something on screen, we need to add one more method to our class (before the final closing brace in our file). The new code is:

 function get_content() {
   if ($this->content !== NULL) {
     return $this->content;
   }

   $this->content         =  new stdClass;
   $this->content->text   = 'The content of our SimpleHTML block!';
   $this->content->footer = 'Footer here...';

   return $this->content;
 }

} // Here's the closing curly bracket for the class definition ?> // and here's the closing PHP tag from the section above.

It can't get any simpler than that, can it? Let's dissect this method to see what's going on...

First of all, there is a check that returns the current value of $this->content if it's not NULL; otherwise we proceed with "computing" it. Since the computation is potentially a time-consuming operation and it will be called several times for each block (Moodle works that way internally), we take a precaution and include this time-saver. Supposing the content had not been computed before (it was NULL), we then define it from scratch. The code speaks for itself there, so there isn't much to say. Just keep in mind that we can use HTML both in the text and in the footer, if we want to.

At this point our block should be capable of being automatically installed in Moodle and added to courses; visit your administration page to install it (Click "Notifications" under the Site Administration Block) and after seeing it in action come back to continue our tutorial.