Voir le texte source

{{En cours de traduction}}

''' 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 [[:en:Blocks_Howto#appendix_b| 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'[[:en:Blocks_Howto#appendix_a| 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 :

<code php>
<?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.
</code>

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 : [[:en:Development:Blocks/Appendix_A#init.28.29| 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.

[[:en:Development:Blocks/Appendix_A#.24this-.3Etitle| $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 [[:en:Development:Blocks#Eye_Candy| how to disable the title's display]].

[[:en:Development:Blocks/Appendix_A#.24this-.3Eversion| $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 [[:en:Development:Blocks/Appendix_A#.24this-.3Eversion| $this->version]] à '''YYYYMMMDD00''' et pouvons l'oublier.

'''MISE A JOUR :'''<br />
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'[[:en:Development:Blocks/Appendix_B| 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:

<code php>  
  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.
</code>

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 [[Development:Blocks/Appendix_A#.24this-.3Econtent| $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.

[[Category:Développeur]]
[[en:Blocks_Howto]]

{{Ébauche}}