Le fichier config/blocks.xml d'un module déclare l'ensemble des blocs du module et, pour chacun des blocs, les paramètres ainsi que les métadonnées disponibles.

La structure d'un fichier blocks.xml est, a minima :

<?xml version="1.0" encoding="UTF-8" ?>
<blocks>
  <block type="modules_mymodule_bloca" />
  <block type="modules_mymodule_blocb" />
  <block type="modules_mymodule_blocc" />
</blocks>

Le tableau suivant présente les attributs supportés par l'élément <block/> :

Toute modification dans blocks.xml doit être suivie de change.php compile-blocks.

La déclaration des paramètres de configuration d'un bloc se fait dans l'élément <parameters/> fils de <block/>. La syntaxe est similaire à la déclaration XML d'un document et les types des paramètres sont identiques à ceux des propriétés.

L'exemple suivant (tiré du module website) déclare trois paramètres :

• “depth”, de type Integer valant par défaut “1”
• “template”, de type String valant par défaut “default”
• “deployonlycurrentpath”, de type “Boolean” valant par défaut “false”

<?xml version="1.0"?>
<blocks>
  <block type="modules_website_menu"
         hidden="true" icon="earth_view"
         label="&amp;modules.website.bo.blocks.Menu;">
    <parameters>
      <parameter name="depth" type="Integer" default-value="1" />
      <parameter name="template" type="String" default-value="default" />
      <parameter name="deployonlycurrentpath" type="Boolean" default-value="false" />
    </parameters>
  </block>
</blocks>

Les messages utilisateurs localisés des paramètres sont à placer dans le fichier locale/bo/blocks/<blockName>.xml.

tout comme pour les propriétés des documents, chaque paramètre de bloc est associé à un libellé et un texte d'aide (locale suffixée par -help) :

<?xml version="1.0" encoding="utf-8"?>
<localization>
   <entity id="depth">
      <locale lang="fr">profondeur</locale>
   </entity>
   <entity id="depth-help">
      <locale lang="fr">profondeur du menu : profondeur maximale de parcours de l'arborescence. 0 signifie "non limité".</locale>
   </entity>
   ...
</localization>

Basé sur cette déclaration, RBS Change génère un formulaire d'édition permettant au rédacteur de régler les valeurs des paramètres du bloc.

Remarques complémentaires :

• l'attribut from-list n'est pas compatible avec les paramètres de type Boolean (il est alors sans effet)
• l'attribut list-id est déprécié au profit de from-list et sera supprimé en version 4.0
• les noms de paramètre “flex”, “width” et “type” sont réservés et non utilisables

Le fichier blocks.xml déclare les métadonnées disponibles pour le rédacteur de page, avec leur champ d'application (“titre”, “description” ou “mots-clefs”), dans la sections <metas/>.

Pour plus de détails sur l'implémentation, voir proposer des métadonnées au rédacteur de page.

Il est possible de surcharger un fichier blocks.xml venant d'un module donné en le déclarant dans le dossier override/ (override/modules/<moduleName>/config/blocks.xml) : le fichier ne remplace pas le fichier original mais le complète. On peut ainsi modifier la valeur par défaut d'un paramètre, l'icône associé, ou encore déclarer un nouveau paramètre de configuration utilisable dans la vue …

Pour rendre invisible un bloc déclaré dans un module standard par exemple, il faut le “re-déclarer” et positionner son attribut hidden à true :

<?xml version="1.0"?>
<blocks>
  <block type="modules_somemodule_uselessBlockForMyProject" hidden="true" />
</blocks>

Pour qu'une modification dans un fichier blocks.xml prenne effet, il faut exécuter change.php compile-blocks.

Cette commande “compile” les informations des blocs dans des fichiers PHP, à la manière de la compilation des documents. Ces fichiers PHP sont générés dans le dossier build/<profile>/modules/<module>/blocks/ :

• <module>_Block<blockName>Info.class.php : classe étandant block_BlockInfo, renseignant sur les paramètres ou métadonnées déclarés
• <module>_Block<blockName>Configuration.class.php : classe étandant block_BlockConfiguration permettant l'accès aux paramètres de configuration lors de son exécution

La méthode getConfiguration() permet d'accéder à l'objet configuration. L'objet configuration étend block_BlockConfiguration.

Ainsi, si mon bloc déclare un paramètre “mondoc” de type modules_monmodule/mondoc, un getter getMondoc() sera généré, renvoyant le document dont l'identifiant est dans la configuration. De même, les conversions vers les entiers, booléens sont effectuées de manière transparente dans les accesseurs spécialisés.

Ainsi, si le paramètre deployonlycurrentpath est un paramètre booléen du bloc :

if ($this->getConfiguration()->getDeployonlycurrentpath())
{
   // deploy only current path
}
else
{
   // deploy more ...
}

A titre d'information :
Des méthodes d'accès généraliste et non typées existent également et ne sont en général pas utilisées ; on leur préférera les méthodes d'accès spécialisées générées lors de change.php compile-blocks. Ces méthodes généralistes sont :

• getConfigurationParameter($parameterName, $defaultValue) : String
• hasConfigurationParameter($parameterName) : String
• hasNonEmptyConfigurationParameter($parameterName) : Boolean
• getConfigurationParameters() : array<String, String>

Le gabarit du bloc a accès à l'objet configuration sous la nom “configuration”.

Ainsi, si le paramètre “deployonlycurrentpath” est un paramètre booléen du bloc :

<tal:block tal:condition="configuration/getDeployonlycurrentpath">
  "deployonlycurrentpath" configuration parameter is set to true.
</tal:block>
<tal:block tal:condition="not: configuration/getDeployonlycurrentpath">
  "deployonlycurrentpath" configuration parameter is set to false.
</tal:block>

Il est possible d'agir sur l'ordre d'exécution d'un bloc en définissant l'attribut order, entier relatif.

Trois raccourcis booléens sont disponibles :

1. beforeAll : équivalent à “order = -100”
2. normal : valeur par défaut, équivalent à “order = 0”
3. afterAll : équivalent à “order = 100”

Lorsque deux blocs ont la même priorité, ils sont exécutés dans l'ordre d'apparition dans le contenu de la page.

Pour attribuer une priorité à un bloc, il suffit de renseigner la configuration du bloc. Dans l'exemple suivant, le bloc modules_website_thread sera exécuté après le bloc modules_website_sitemap :

<?xml version="1.0"?>
<blocks>
  <block type="modules_website_sitemap" display=""
       icon="earth_view" label="&amp;modules.website.bo.blocks.Sitemap;" />
 
  <block type="modules_website_thread" display="" hidden="true" afterAll="true"
       icon="earth_view" label="&amp;modules.website.bo.blocks.Thread;" />
</blocks>