Ajouter des fonctionnalités à Contao en utilisant les "hooks"

Les “hooks” fonctionnent de la même manière que les fonctions de callback du Tableau Conteneur de Données (DCA). Vous pouvez enregistrer une ou plusieurs fonctions pour un événement donné, et lorsque l'événement déclencheur survient, les fonctions de callback sont exécutées. Les hooks vous permettent d'ajouter des fonctionnalités au coeur de Contao.

Le hook activateAccount est déclenché lorsqu'un nouveau compte de front-office est activé. Il passe l'objet utilisateur en argument et n'attend pas de valeur de retour. Il est disponible depuis la version 2.4.3 de Contao.

// config.php
$GLOBALS['TL_HOOKS']['activateAccount'][] = array('MyClass', 'myActivateAccount');
 
// MyClass.php
public function myActivateAccount(Database_Result $objUser)
{
    // Faire quelque chose
}

Le hook activateRecipient est déclenché lorsqu'un nouveau destinataire de newsletter est ajouté. Il passe en arguments l'adresse email, les ID du destinataire et du canal, et n'attend pas de valeur de retour. Il est disponible depuis la version 2.8.RC1 de Contao.

// config.php
$GLOBALS['TL_HOOKS']['activateRecipient'][] = array('MyClass', 'myActivateRecipient');
 
// MyClass.php
public function myActivateRecipient($strEmail, $arrRecipients, $arrChannels)
{
    // Faire quelque chose
}

The addComment hook is triggered when a comment is added. It passes the ID of the record and the data array as arguments and does not expect a return value. It is available from version 2.8.2.

// config.php
$GLOBALS['TL_HOOKS']['addComment'][] = array('MyClass', 'myAddComment');
 
// MyClass.php
public function myAddComment($intId, $arrSet)
{
    // Do something
}

Le hook addCustomRegexp est déclenché lorsqu'une nouvelle expression régulière est trouvée. Il passe en arguments le nom de la regexp, la valeur courante et l'objet widget, et attend une valeur de retour de forme booléenne. Il est disponible depuis la version 2.6.2 de Contao.

// config.php
$GLOBALS['TL_HOOKS']['addCustomRegexp'][] = array('MyClass', 'myAddCustomRegexp');
 
// MyClass.php
public function myAddCustomRegexp($strRegexp, $varValue, Widget $objWidget)
{
    if ($strRegexp == 'postal')
    {
        if (!preg_match('/^0-9{4,6}$/', $varValue))
        {
            $objWidget->addError('Field ' . $objWidget->label . ' should be a postal code.');
        }
 
        return true;
    }
 
    return false;
}

Le hook addLogEntry est déclenché lorsqu'une nouvelle entrée est ajoutée au journal (log). Il passe en arguments le message, la fonction et l'action, et n'attend pas de valeur de retour. Il est disponible depuis la version 2.8.RC1 de Contao.

// config.php
$GLOBALS['TL_HOOKS']['addLogEntry'][] = array('MyClass', 'myAddLogEntry');
 
// MyClass.php
public function myAddLogEntry($strText, $strFunction, $strAction)
{
    // Faire quelque chose
}

Le hook checkCredentials est déclenché lorsqu'une tentative d'identification échoue à cause d'un mot de passe incorrect. Il passe en arguments le nom de l'utilisateur, le mot de passe et l'objet utilisateur, et attend une valeur de retour booléenne. Il est disponible depuis la version 2.6.0 de Contao.

// config.php
$GLOBALS['TL_HOOKS']['checkCredentials'][] = array('MyClass', 'myCheckCredentials');
 
// MyClass.php
public function myCheckCredentials($strUsername, $strPassword, User $objUser)
{
    // Vérification par rapport à la base de données
    if ($this->checkGlobalDbFor($strUsername, $strPassword))
    {
        return true;
    }
 
    return false;
}

Le hook closeAccount est déclenché lorsqu'un utilisateur clôture son compte. Il passe en arguments l'ID de l'utilisateur, le mode opérationnel et le module, et n'attend pas de valeur de retour. Il est disponible depuis la version 2.8.0 de Contao.

// config.php
$GLOBALS['TL_HOOKS']['closeAccount'][] = array('MyClass', 'myCloseAccount');
 
// MyClass.php
public function myCloseAccount($intId, $strMode, $objModule)
{
    if ($strMode == 'close_delete')
    {
        // Faire quelque chose
    }
}

Le hook compileDefinition est déclenché quand une définition de formatage d'une feuille de style est écrite. Il passe le tableau de configuration en argument et attend une chaîne comme valeur de retour. Il est disponible depuis la version 2.9.4.

// config.php
$GLOBALS['TL_HOOKS']['compileDefinition'][] = array('MyClass', 'myCompileDefinition');
 
// MyClass.php
public function myCompileDefinition($arrRow)
{
    if (isset($arrRow['border-radius']))
    {
        return "\nborder-radius:" . $arrRow['border-radius'] . ";";
    }
 
    return '';
}

Le hook createDefinition est déclenché quand une définition de formatage d'une feuille de style est importée. Il passe la clé et la valeur, la définition de formatage d'origine et le tableau de données comme arguments et attend un tableau ou false comme valeur de retour. Il est disponible depuis la version 2.9.4.

// config.php
$GLOBALS['TL_HOOKS']['createDefinition'][] = array('MyClass', 'myCreateDefinition');
 
// MyClass.php
public function myCreateDefinition($strKey, $strValue, $strDefinition, $arrSet)
{
    if ($strKey == 'border-radius')
    {
         return array('border-radius'=>$strValue);
    }
 
    return false;
}

Le hook createNewUser est déclenché lorsqu'un nouvel utilisateur front-office s'enregistre sur le site. Il passe en arguments le nouvel utilisateur et le tableau de données, et n'attend pas de valeur de retour. Il est disponible depuis la version 2.2.0 de Contao.

// config.php
$GLOBALS['TL_HOOKS']['createNewUser'][] = array('MyClass', 'myCreateNewUser');
 
// MyClass.php
public function myCreateNewUser($intId, $arrData)
{
    // Modification de l'enregistrement
}

Le hook executePreActions est déclenché par les requêtes Ajax qui n'attendent pas de réponse. Il passe le nom de l'action en argument, et n'attend pas de valeur de retour. Il est disponible depuis la version 2.6.1 de Contao.

// config.php
$GLOBALS['TL_HOOKS']['executePreActions'][] = array('MyClass', 'myExecutePreActions');
 
// MyClass.php
public function myExecutePreActions($strAction)
{
    if ($strAction == 'update')
    {
        // Fait quelque chose
    }
}

Le hook executePostActions est déclenché par les requ?tes Ajax qui attendent une réponse. Il passe en paramètres le nom de l'action et l'objet conteneur de données, et n'attend pas de valeur de retour. Il est disponible depuis la version 2.6.1 de Contao.

// config.php
$GLOBALS['TL_HOOKS']['executePostActions'][] = array('MyClass', 'myExecutePostActions');
 
// MyClass.php
public function myExecutePostActions($strAction, DataContainer $dc)
{
    if ($strAction == 'update')
    {
        // Fait quelque chose
    }
}

Le hook generateFrontendUrl est déclenché lors de la re-création d'une URL de front-office. Il passe en arguments l'objet page, la chaîne de paramètres et l'URL par défaut, et attend une chaîne de caractères comme valeur de retour. Il est disponible à partir de la version 2.5.8 de Contao.

// config.php
$GLOBALS['TL_HOOKS']['generateFrontendUrl'][] = array('MyClass', 'myGenerateFrontendUrl');
 
// MyClass.php
public function myGenerateFrontendUrl(Database_Result $objPage, $strParams, $strUrl)
{
    return str_replace('.html', '.xml', $strUrl);
}

Le hook generatePage est déclenché avant la compilation de la présentation de la section principale (fe_page). Il passe en arguments l'objet page, l'objet présentation et une référence qui lui est propre, et n'attend pas de valeur de retour. Il est disponible depuis la version 2.8.RC1 de Contao.

// config.php
$GLOBALS['TL_HOOKS']['generatePage'][] = array('MyClass', 'myGeneratePage');
 
// MyClass.php
public function myGeneratePage(Database_Result $objPage, Database_Result $objLayout, PageRegular $objPageRegular)
{
    // Fait quelque chose
}

Le hook getAllEvents vous permet de modifier les jeux de résultat produits par les modules calendrier et événements. Il passe en arguments le résultat courant, les ID des éléments parents et les dates de début et de fin, et attend un jeu de résultats (tableau) comme valeur de retour. Il est disponible depuis la version 2.6.4 de Contao.

// config.php
$GLOBALS['TL_HOOKS']['getAllEvents'][] = array('MyClass', 'myGetAllEvents');
 
// MyClass.php
public function myGetAllEvents($arrEvents, $arrCalendars, $intStart, $intEnd)
{
    ksort($arrEvents);
    return $arrEvents;
}

The getContentElement hook is triggered when a content element is rendered. It passes the database object and the buffer string as arguments and expects a buffer string as return value. It is available from version 2.9.0.

// config.php
$GLOBALS['TL_HOOKS']['getContentElement'][] = array('MyClass', 'myGetContentElement');
 
// MyClass.php
public function myGetContentElement(ContentElement $objElement, $strBuffer)
{
    return $strBuffer;
}

The getImage hook is triggered when a thumbnail is generated and allows you to add a custom routine. It passes the path, the width and height, the mode, the cache name and the file object as arguments and expects a path as return value. It is available from version 2.8.RC1.

// config.php
$GLOBALS['TL_HOOKS']['getImage'][] = array('MyClass', 'myGetImage');
 
// MyClass.php
public function myGetImage($image, $width, $height, $mode, $strCacheName, $objFile)
{
    return MyImage::generateThumbnail($image, $widht, $height, $mode);
}

Le hook getPageIdFromUrl est déclenché lors de l'évaluation des parties d'URL. Il passe les fragments d'URL en arguments, et attend un tableau de fragments d'URL en valeur de retour. Il est disponible depuis la version 2.5.4 de Contao.

// config.php
$GLOBALS['TL_HOOKS']['getPageIdFromUrl'][] = array('MyClass', 'myGetPageIdFromUrl');
 
// MyClass.php
public function myGetPageIdFromUrl($arrFragments)
{
    return array_unique($arrFragments);
}

Le hook getSearchablePages est déclenché lors de la reconstruction d'un index de recherche. Il passe en arguments le tableau des pages et l'ID de la page racine, et attend un tableau d'URL absolues (!) comme valeur de retour. Il est disponible depuis la version 2.2.0 de Contao.

// config.php
$GLOBALS['TL_HOOKS']['getSearchablePages'][] = array('MyClass', 'myGetSearchablePages');
 
// MyClass.php
public function myGetSearchablePages($arrPages, $intRoot)
{
    return array_merge($arrPages, array('Additional pages'));
}

Le hook importUser est déclenché lorsqu'un nom d'utilisateur ne peut être trouvé dans la base de données. Il passe le nom de la table en argument et attend une valeur de retour booléenne. Il est disponible depuis la version 2.7.RC1 de Contao.

// config.php
$GLOBALS['TL_HOOKS']['importUser'][] = array('MyClass', 'myImportUser');
 
// MyClass.php
public function myImportUser($strUsername, $strPassword, $strTable)
{
    if ($strTable == 'tl_member')
    {
        // Importe l'utilisateur à partir d'un serveur LDAP
        if ($this->importUserFromLdap($strUsername, $strPassword))
        {
            return true;
        }
    }
 
    return false;

Le hook listComments est déclenché lorsque des commentaires sont listés dans le back-office. Il passe l'enregistrement courant en argument, et attend une chaîne de caractères comme valeur de retour. Il est disponible depuis la version 2.8.RC2 de Contao.

// config.php
$GLOBALS['TL_HOOKS']['listComments'][] = array('MyClass', 'myListComments');
 
// MyClass.php
public function myListComments($arrRow)
{
    return '<a href="contao/main.php?do= … ">' . $arrRow['title'] . '</a>';
}

Le hook loadFormField est déclenché lorsqu'un champ de formulaire est chargé. Il passe en arguments l'objet widget, l'ID et les données du formulaire, et attend un objet widget comme valeur de retour. Il est disponible depuis la version 2.5.0 de Contao.

// config.php
$GLOBALS['TL_HOOKS']['loadFormField'][] = array('MyClass', 'myLoadFormField');
 
// MyClass.php
public function myLoadFormField(Widget $objWidget, $strForm, $arrForm)
{
    $objWidget->class = 'myclass';
    return $objWidget;
}

The loadDataContainer hook is triggered when a DCA file is loaded. It passes the file name as argument and does not expect a return value. It is available from version 2.8.2.

// config.php
$GLOBALS['TL_HOOKS']['loadDataContainer'][] = array('MyClass', 'myLoadDataContainer');
 
// MyClass.php
public function myLoadDataContainer($strName)
{
    // Do something
}

Le hook loadLanguageFile est déclenché au chargement d'un fichier langue. Il passe en arguments le nom du fichier et la langue, et n'attend pas de valeur de retour. Il est disponible depuis la version 2.8.RC1 de Contao.

// config.php
$GLOBALS['TL_HOOKS']['loadLanguageFile'][] = array('MyClass', 'myLoadLanguageFile');
 
// MyClass.php
public function myLoadLanguageFile($strName, $strLanguage)
{
    // Faire quelque chose
}

Le hook outputBackendTemplate est déclenché lors de l'affichage à l'écran d'un template de back-office. Il passe en arguments le contenu et le nom du template, et attend le contenu du template comme valeur de retour. Il est disponible à partir de la version 2.6.0 de Contao.

// config.php
$GLOBALS['TL_HOOKS']['outputBackendTemplate'][] = array('MyClass', 'myOutputBackendTemplate');
 
// MyClass.php
public function myOutputBackendTemplate($strContent, $strTemplate)
{
    if ($strTemplate == 'be_main')
    {
        // Modification de la sortie
    }
 
    return $strContent;
}

Le hook outputFrontendTemplate est déclenché lors de l'affichage à l'écran d'un template de front-office. Il passe en arguments le contenu et le nom du template, et attend le contenu du template en valeur de retour. Il est disponible à partir de la version 2.6.0 de Contao.

// config.php
$GLOBALS['TL_HOOKS']['outputFrontendTemplate'][] = array('MyClass', 'myOutputFrontendTemplate');
 
// MyClass.php
public function myOutputFrontendTemplate($strContent, $strTemplate)
{
    if ($strTemplate == 'fe_page')
    {
        // Modification de la sortie
    }
 
    return $strContent;
}

Le hook parseBackendTemplate est déclenché lorsqu'un template de back-office est analysé (“parsé”). Il passe en arguments le contenu et le nom du template, et attend le contenu du template comme valeur de retour. Il est disponible depuis la version 2.6.0 de Contao.

// config.php
$GLOBALS['TL_HOOKS']['parseBackendTemplate'][] = array('MyClass', 'myParseBackendTemplate');
 
// MyClass.php
public function myParseBackendTemplate($strContent, $strTemplate)
{
    if ($strTemplate == 'be_main')
    {
        // Modification de la sortie
    }
 
    return $strContent;
}

Le hook parseFrontendTemplate est déclenché lors de l'analyse (“parsing”) d'un template de front-office. Il passe en arguments le contenu et le nom du template, et attend le contenu du template en valeur de retour. Il est disponible depuis la version 2.6.0 de Contao.

// config.php
$GLOBALS['TL_HOOKS']['parseFrontendTemplate'][] = array('MyClass', 'myParseFrontendTemplate');
 
// MyClass.php
public function myParseFrontendTemplate($strContent, $strTemplate)
{
    if ($strTemplate == 'ce_text')
    {
        // Modification du contenu
    }
 
    return $strContent;
}

Le hook postDownload est déclenché après le chargement d'un fichier par l'élément download(s). Il passe le nom de fichier en argument, et n'attend pas de valeur de retour. Il est disponible depuis la version 2.4.6 de Contao.

// config.php
$GLOBALS['TL_HOOKS']['postDownload'][] = array('MyClass', 'myPostDownload');
 
// MyClass.php
.public function myPostDownload($strFile)
{
    // Faire quelque chose
}

Le hook postLogin est déclenché après qu'un utilisateur se soit identifié dans le front-office. Il passe l'objet utilisateur en argument et n'attend pas de valeur de retour. Il est disponible depuis la version 2.4.3 de Contao.

// config.php
$GLOBALS['TL_HOOKS']['postLogin'][] = array('MyClass', 'myPostLogin');
 
// MyClass.php
public function myPostLogin($objUser)
{
    // Faire quelque chose
}

Le hook postLogout est déclenché après qu'un utilisateur se soit déconnecté du front-office. Il passe l'objet utilisateur en argument, et n'attend pas de valeur de retour. Il est disponible depuis la version 2.4.3 de Contao.

// config.php
$GLOBALS['TL_HOOKS']['postLogout'][] = array('MyClass', 'myPostLogout');
 
// MyClass.php
public function myPostLogout(Database_Result $objUser)
{
    // Fait quelque chose
}

Le hook postUpload est déclenché après qu'un utilisateur ait chargé un ou plusieurs fichiers dans le back-office. Il passe un tableau de noms de fichiers en argument, et n'attend pas de valeur de retour. Il est disponible depuis la version 2.6.4 de Contao.

// config.php
$GLOBALS['TL_HOOKS']['postUpload'][] = array('MyClass', 'myPostUpload');
 
// MyClass.php
public function myPostUpload($arrFiles)
{
    // Faire quelque chose
}

Le hook printArticleAsPdf est déclenché lorsqu'un article est exporté en format PDF. Il passe en arguments le texte de l'article et l'objet article, et n'attend pas de valeur de retour. Il est disponible depuis la version 2.8.RC1 de Contao.

// config.php
$GLOBALS['TL_HOOKS']['printArticleAsPdf'][] = array('MyClass', 'myPrintArticleAsPdf');
 
// MyClass.php
public function myPrintArticleAsPdf($strArticle, ModuleArticle $objArticle)
{
    // Fait quelque chose
    exit;
}

Le hook processFormData est déclenché après la soumission d'un formulaire. Il passe en arguments le tableau des données du formulaire, le Tableau Conteneur de Données (DCA) et le tableau de fichiers, et n'attend pas de valeur de retour. Il est disponible depuis la version 2.4.4 de Contao.

// config.php
$GLOBALS['TL_HOOKS']['processFormData'][] = array('MyClass', 'myProcessFormData');
 
// MyClass.php
public function myProcessFormData($arrPost, $arrForm, $arrFiles)
{
    // Faire quelque chose
}

Le hook removeOldFeeds est déclenché à la suppression de vieux fichiers XML du répertoire Contao. Il ne passe pas d'argument et retourne un tableau de noms de fichiers à conserver. Il est disponible depuis la version 2.5.8 de Contao.

// config.php
$GLOBALS['TL_HOOKS']['removeOldFeeds'][] = array('MyClass', 'myRemoveOldFeeds');
 
// MyClass.php
public function myRemoveOldFeeds()
{
    return array('custom.xml');
}

Le hook removeRecipient est déclenché à la suppression d'un destinataire de newsletter. Il passe en arguments l'adresse email et l'ID du canal, et n'attend pas de valeur de retour. Il est disponible depuis la version 2.8.RC1 de Contao.

// config.php
$GLOBALS['TL_HOOKS']['removeRecipient'][] = array('MyClass', 'myRemoveRecipient');
 
// MyClass.php
public function myRemoveRecipient($strEmail, $arrChannels)
{
    // Faire quelque chose
}

Le hook replaceInsertTags est déclenché lorsqu'un tag d'insertion inconnu est trouvé. Il passe le tag d'insertion en argument, et attend, en valeur de retour, la valeur de remplacement ou false. Il est disponible à partir de la version 2.6.0 de Contao.

// config.php
$GLOBALS['TL_HOOKS']['replaceInsertTags'][] = array('MyClass', 'myReplaceInsertTags');
 
// MyClass.php
public function myReplaceInsertTags($strTag)
{
    if ($strTag == 'mytag')
    {
        return 'mytag replacement';
    }
 
    return false;
}

Le hook reviseTable est déclenché lorsque Contao supprime d'une table des enregistrements orphelins. Il passe en arguments le nom de la table courante, les ID de tous les nouveaux enregistrements, le nom de la table parente, et les noms de toutes les tables enfants, et attend une valeur de retour de forme booléenne (le retour de la valeur true provoque le rechargement de la page courante). Il est disponible depuis la version 2.6.4 de Contao.

// config.php
$GLOBALS['TL_HOOKS']['reviseTable'][] = array('MyClass', 'myReviseTable');
 
// MyClass.php
public function myReviseTable($table, $new_records, $parent_table, $child_tables)
{
    // Faire quelque chose
}

Le hook setNewPassword est déclenché après la saisie d'un nouveau mot de passe. Il passe en arguments l'objet utilisateur et le mot de passe crypté, et n'attend pas de valeur de retour. Il est disponible à partir de la version 2.2.3 de Contao.

// config.php
$GLOBALS['TL_HOOKS']['setNewPassword'][] = array('MyClass', 'mySetNewPassword');
 
// MyClass.php
public function mySetNewPassword(User $objUser, $strPassword)
{
    // Faire quelque chose
}

Le hook validateFormField est déclenché à la soumission d'un champ de formulaire. Il passe en arguments l'objet widget et l'ID du formulaire, et attend un objet widet comme valeur de retour. Il est disponible depuis la version 2.5.0 de Contao.

// config.php
$GLOBALS['TL_HOOKS']['validateFormField'][] = array('MyClass', 'myValidateFormField');
 
// MyClass.php
public function myValidateFormField(Widget $objWidget, $intId)
{
    if ($objWidget instanceof FormPassword)
    {
        // Faire quelque chose
    }
 
    return $objWidget;
}