L'action d'un bloc est une classe étendant website_BlockAction. Son rôle est d'effectuer les traitements nécessaires (souvent récupérer ou mettre à jour des données en base) puis de déléguer l'affichage HTML à un gabarit PHPTal.

Les traitements sont implémentés par la méthode execute(). Pour accéder aux paramètres (GET ou POST) de la requête HTTP, execute() utilise la méthode getParameter() de l'objet $request qui lui est transmis.

Une fois les traitements effectués, execute() retourne le nom du gabarit à afficher. Pour transmettre des données au gabarit, le bloc utilise la méthode setAttribute() de l'objet $request.

Le nom de la classe PHP du bloc est important : pour un bloc <blockName> du module <moduleName>, la classe est exactement <moduleName>_Block<BlockName>Action ; notez bien la casse des caractères !

Exemple : la classe du bloc iframe du module website est website_BlockIframeAction :

class website_BlockIframeAction extends website_BlockAction
{
   // ...
}

La chaîne de caractère retournée par la méthode execute() détermine le gabarit PHPTal utilisé, selon une convention de nommage précise : si execute() retourne la chaîne <templateName>, le gabarit affiché sera templates/<ModuleName>-Block-<BlockName>-<templateName>.html.

Un bloc peut décider d'afficher différents gabarits selon le contexte d'exécution.

Exemple : le bloc iframe du module website affiche le gabarit “Backoffice” ou “Success”, selon que le bloc est rendu dans l'éditeur de page ou non. Les gabarits affichés par le bloc iframe sont donc soit templates/Website-Block-Iframe-Success.html ou templates/Website-Block-Iframe-Backoffice.html :

class website_BlockIframeAction extends website_BlockAction
{
  function execute($request, $response)
  {
    if ($this->isInBackofficeEdition())
    {
      return "Backoffice";
    }
    return "Success";
  }
}

Pour utiliser un gabarit d'un autre module ou ne respectant pas la convention de nommage, le bloc peut retourner directement un objet TemplateObject et pour cela utiliser la méthode getTemplateByFullName() :

Exemple : utilisation du gabarit modules/othermodule/templates/SomeTemplate.html :

function execute($request, $response)
{
  return $this->getTemplateByFullName('modules_othermodule', 'SomeTemplate');
}

Qu'un paramètre de requête HTTP provienne de $_GET ou $_POST, le bloc peut en récupérer la valeur avec la méthode getParameter() de l'objet $request. Si le paramètre n'est pas disponible, getParameter() renvoie null.

Afin d'éviter les conflits, les paramètres de requête sont cloisonnés entre les différents modules : par défaut, un bloc n'accède qu'aux paramètres de son module, tous regroupés dans le tableau <moduleName>Param.

Exemple : récupération du paramètre HTTP myParam, correspondant ici au paramètre HTTP mymoduleParam[myParam] :

class mymodule_BlockMyblockAction extends website_BlockAction
{
  /**
   * @param website_BlockActionRequest $request
   * @param website_BlockActionResponse $response
   * @return String
   */
  function execute($request, $response)
  {
    $myParam = $request->getParameter("myParam");
  }
}

Pour plus de détails, voir Gestion des paramètres de requête.

Les blocs peuvent être paramétrables. Pour paramétrer un bloc, il suffit de déclarer les paramètres supportés dans le fichier config/blocks.xml. Chaque paramètre est déclaré par un élément <parameter/>, sur lequel on renseigne a minima les attributs name et type.

Exemple : déclaration du paramètre de configuration someParam de type Boolean sur le bloc myblock du module mymodule :

<block type="modules_mymodule_myblock">
  <parameters>
    <parameter name="someParam" type="Boolean" default-value="true" />
  </parameters>
</block>

N.B. : lorsque le fichier config/blocks.xml est modifié, la commande change.php compile-blocks doit être exécutée.

Le bloc accède à sa configuration avec la méthode getConfiguration(), retournant un objet exposant une méthode d'accès pour chaque paramètre de bloc : au paramètre de configuration paramName correspond la méthode getParamName() de l'objet configuration.

Ces méthodes effectuent des conversions de type ; pour un paramètre de type Boolean par exemple, les chaînes de caractères sont converties en true ou false, selon que le paramètre vaut “true” ou non.

Exemple : utilisation du paramètre de configuration someParam précédemment déclaré :

class mymodule_BlockMyblockAction extends website_BlockAction
{
  /**
   * @param website_BlockActionRequest $request
   * @param website_BlockActionResponse $response
   * @return String
   */
  function execute($request, $response)
  {
    /* @var $configuration mymodule_BlockMyblockConfiguration */
    $configuration = $this->getConfiguration();
    if ($configuration->getSomeParam())
    {
      // "someParam" equals "true"
    }
    else
    {
      // "someParam" does not equals "true"
    }
  }
}

Pour plus détails sur la configuration d'un bloc, voyez la configuration.

Le bloc transmet des données à la vue en utilisant la méthode setAttribute() de l'objet $request. Les données peuvent être de tous les types : scalaires, tableaux, objets…

Le gabarit utilise les données transmises pour créer un HTML.

Exemple : transmission d'une chaîne, d'un tableau et d'un document sous les noms aString, anArray et mydoc.

class mymodule_BlockMyblockAction extends website_BlockAction
{
  /**
   * @param website_BlockActionRequest $request
   * @param website_BlockActionResponse $response
   * @return String
   */
  function execute($request, $response)
  {
    // Transmit some dummy string
    $request->setAttribute("aString", "Text with HTML <characters>");
    // Transmit some dummy array
    $request->setAttribute("anArray", array("v1", "v2 & v3"));
 
    // Retrieve document using "cmpref" parameter
    $cmpref = $request->getParameter("cmpref");
    $document = mymodule_persistentdocument_mydocument::getInstanceById($cmpref);
    // Transmit document
    $request->setAttribute("mydoc", $document);
 
    return "MyTemplate";
  }
}

Le gabarit (ici “MyTemplate”) utilise ensuite les valeurs transmises pour générer un HTML précis.

Exemple : utilisation de la chaine aString et du tableau anArray dans le gabarit PHPTal MyTemplate :

<div>
  <h2>${escape: aString}</h2>
 
  <ul>
    <li tal:repeat="str anArray">${escape: str}</li>
  </ul>
 
  <p>Document label is : <strong>${mydoc/getLabelAsHtml}</strong></p>
</div>

En supposant que le document transmis aie pour libellé “My document label”, l'exemple précédent générerai l'HTML suivant :

• La valeur de aString a été placée dans la balise <h2/>
• L'élément <li/> a été répété en utilisant les valeurs du tableau anArray
• Le libellé du document transmis a été placé dans l'élément <strong/>

<div>
  <h2>Text with HTML &lt;characters&gt;</h2>
 
  <ul>
    <li>v1</li>
    <li>v2 &amp; v3</li>
  </ul>
 
  <p>Document label is : <strong>My document label</strong></p>
</div>

Pour plus d'informations sur les gabarits PHPTal, consultez le gabarit.