Système de Hooks

Retour index
Documentation développeur

Page waiting for translation. To translate, create an account, go back and clic on "Modify". Page en attente de traduction. Pour traduire, créez un compte, revenez et cliquez sur "Modifier". Página a traducir. Para traducirla, cree una cuenta, vuelva a la página y haga clic en "editar". Pagina da tradurre. Per tradurla, crea un utente, torna indietro e clicca su "modifica". Página a aguardar por tradução. Para traduzir, crie uma conta, volte atrás e clique em "Modificar". Seite wartet auf Übersetzung. Um Übersetzung zu erstellen, richte einen Account ein, geh zurück und klicke auf "bearbeiten". 页面等待翻译。若要翻译本页，先创建一个帐户、登录并返回本页后单击“编辑”。

Les Hooks permettent aux développeurs d'ajouter du code personnalisé aux pages standard de Dolibarr sans avoir à modifier les fichiers du coeur de Dolibarr. Contrairement aux triggers (autre manière d'interagir avec le code de Dolibarr) qui sont liés aux événements de Dolibarr, les Hooks peuvent s'exécuter n'importe ou et à n'importe quel moment. Ce sont des points d'entrée dans le programme.

• Les Hooks agissent selon le contexte (càd le module : par exemple "productcard" pour les produits, "invoicecard" pour les factures...). Pour trouver les Hooks existants faites une recherche pour "callHooks("
• Les Hooks sont des foncitons qui peuvent être surchargées. Vous décidez si votre code s'ajoute à celui de dolibarr ou s'il le remplace. Pour rechercehr le code qu'il est possible de surcharger faites une recherche pour "executeHooks("

Implementation

Pour utiliser un Hook (donc surcharger une fonction), vous devez d'abord avoir défini un module (voir le wiki sur la création d'un module). Ensuite vous devez suivre les étapes suivantes :

1. Pour ajouter votre module au contexte où me hook doit d'éxécuter Ce qui veut dire que lorsqu'on se trouve dans le contexte donné (module dolibarr), votre module sera appelé. Pour cela, éditer le descripteur de votre module (/htdocs/includes/modYourModuleName.class.php) et renseignez la variable $this->const comme par exemple (modifiez le code en gras selon votre module)

$this->const = array(
0=>array(''''MAIN_MODULE_YOURMODULENAME_HOOKS'''', 'chaine', ''''productcard:invoicecard:propalcard'''',
''''Hooks list for managing printing functions of the CustomFields module'''', 0, 'current', 1)
);

Rappel Note: format d'une déclaration de constante :

$key=>array($const_name,$type,$value,$description,$visible_on_admin_panel=0,$entity='current',$deleteonunactive=0),
$key2=>...

où $key being est un entier positif.

IMPORTANT: n'oubliez pas de désactiver puis de réactiver votre module pour que la modification soit prise en compte. Attention le dernier paramètre doit être 1 et no 0 (valeur par défaut) pour écraser une éventuelle valeur précédente.

2. Pour remplacer une fonction existante par la votre (surcharge)

Créez /htdocs/yourmodulename/class/actions_yourmodulename.class.php dans votre module avec un code comme celui-ci

class ActionsYourModuleName // extends CommonObject 
{ 
 
    /** Overloading the doActions function : replacing the parent's function with the one below 
     *  @param      parameters  meta datas of the hook (context, etc...) 
     *  @param      object             the object you want to process (an invoice if you are in invoice module, a propale in propale's module, etc...) 
     *  @param      action             current action (if set). Generally create or edit or null 
     *  @return       void 
     */ 
    function doActions($parameters, $object, $action) 
    { 
        print_r($parameters); 
        echo "action: ".$action; 
        print_r($object); 
 
        if ($parameters->context == 'somecontext') 
        { 
          // do something only for the context 'somecontext'
        }
    }
}

Où

• $parametersest un tableau (array) de meta-data regroupant les da is an array of meta-data about the datas contained by the hook (eg: the context, always accessible by $parameters->context).
• $object is the object that you may work on. Eg: the product if you are in the productcard context.
• $action is the action if one is conveyed (generally "create", "edit" or "view").

---

Hooks is a developer feature to allow developer to add personalized code intod Dolibarr core code with no need to patch Dolibarr. On the contrary to the triggers (another feature to interact with Dolibarr code) which are by definition linked to a business action, hooks can happen anywhere at anytime, they are an entry point into the program.

• Hooks work by context (ie the module, eg: "productcard" for products, "invoicecard" for invoices, etc..). It's easy to find them, just search for "callHooks("
• Hooks are functions that can be overloaded by your own. You decide if your code is added to standard Dolibarr code or if it replace Dolibarr code. You can find overloadable functions by searching for "executeHooks("

Implementation

To use a hook (overload a function), you first need to already have defined a module (see the wiki for that), and then you need to do 2 things:

1- to add your module to the hooks of the context you want to hook on. This means that when this context (module) will happen, your module will be called. To do that, just edit your /htdocs/includes/modYourModuleName.class.php and edit the $this->const variable with something like this:

$this->const = array(
0=>array('MAIN_MODULE_YOURMODULENAME_HOOKS', 'chaine', 'productcard:invoicecard:propalcard',
'Hooks list for managing printing functions of the CustomFields module', 0, 'current', 1)
);

Note: format of a const declaration:

$key=>array($const_name,$type,$value,$description,$visible_on_admin_panel=0,$entity='current',$deleteonunactive=0),
$key2=>...

With $key being a positive integer.

Of course change YourModuleName with your own module's name. Don't touch 'chaine' which defines the type of the constant. Then you get the value at the third index, which is a string with contexts separated by a comma.

IMPORTANT: Be careful: do not forget to DISABLE then RENABLE the module in the admin panel to accept the new const values, because these constants are only added to the database when enabling the module. And please note that the const is updated because the last parameter is set to 1 (which represent $deleteonunactive) which by default is set to 0 to preserve the constants even when the module is disabled.

2- You will overload a hook (a function) with your own.

Create a file /htdocs/yourmodulename/class/actions_yourmodulename.class.php and then put something like this:

class ActionsYourModuleName // extends CommonObject 
{ 
 
    /** Overloading the doActions function : replacing the parent's function with the one below 
     *  @param      parameters  meta datas of the hook (context, etc...) 
     *  @param      object             the object you want to process (an invoice if you are in invoice module, a propale in propale's module, etc...) 
     *  @param      action             current action (if set). Generally create or edit or null 
     *  @return       void 
     */ 
    function doActions($parameters, $object, $action) 
    { 
        print_r($parameters); 
        echo "action: ".$action; 
        print_r($object); 
 
        if ($parameters->context == 'somecontext') 
        { 
          // do something only for the context 'somecontext'
        }
    }
}

where

• $parameters is an array of meta-data about the datas contained by the hook (eg: the context, always accessible by $parameters->context).
• $object is the object that you may work on. Eg: the product if you are in the productcard context.
• $action is the action if one is conveyed (generally "create", "edit" or "view").

Your function should now be called when you access the module/context and you will see the parameters and object and action.

List of available Hooks

Page waiting to complete. To complete, create an account, go back and clic on "Modify". Page en attente d'être complété. Pour compléter, créez un compte, revenez et cliquez sur "Modifier". Página a completar. Para completarla, cree una cuenta, vuelva a la página y haga clic en "editar" Seite wartet auf Vervollständigung. Um zu helfen, erstelle ein Konto, gehe zurück und klicke auf "Bearbeiten". 待完成，欲帮助完成，注册帐号，点击“编辑" ページは未完成の状態です。完成させるにはアカウントを作成し、ページに戻って「編集」をクリックして下さい。

• formObjectOptions: called everytime fields associated to the main object are printed or inputted (eg: creation form, datasheet, edit form, etc..).

How to find the available hooks ? Just search for "executeHooks(" and you should easily find all the hooked methods calls.

See also

• Triggers
• Interfaces Dolibarr toward foreign systems
• Interfaces from foreign systems toward Dolibarr