3
edits
Changes
m
Meilleure traduction du mot hook, capitaine
Line 1:
Line 1:
+{{ToTranslate}}
−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 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('''"+
+
+
+
+
+
+
+
+
+
+
+
+
+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:
−
−0=>array('MAIN_MODULE_YOURMODULENAME_HOOKS', 'chaine', 'productcard:invoicecard:propalcard',+
+
+
−$key=>array($const_name,$type,$value,$description,$visible_on_admin_panel=0,$entity='current',$deleteonunactive=0),+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.
−Create a file '''/htdocs/''yourmodulename''/class/actions_''yourmodulename''.class.php''' and then put something like this:+ + /** 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 =+{{ToComplete}}
−* '''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 =+
<!-- BEGIN interlang links -->
+<!-- Do NOT edit this section
+ Links below are automatically managed by PolyglotBot
+ You can edit links on the English source page : Hooks_system -->
+[[en:Hooks_system]]
+[[es:El_sistema_Hooks]]
+[[de:System_von_Hooks]]
+[[zh:钩子系统]]
+<!-- END interlang links -->
+
{{TemplateDocDevFr}}
{{TemplateDocDevFr}}
−Hooks is a developer feature to allow developer to add personalized code intod Dolibarr core code with no need to patch Dolibarr.
+=Introduction=
−Les Hooks (crochet en anglais, dans le sens de détour) sont une fonctionnalité destinée aux développeurs, leur permettant d'ajouter du code personnalisé aux pages standards de Dolibarr sans avoir à modifier le ''core'' de Dolibarr. Contrairement au [[Système de 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 où et à n'importe quel moment dès lors qu'ils ont été prévus dans le ''core'' de Dolibarr. Ce sont des points d'insertion dans le programme.
−* 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('''"
+*Les Hooks sont actifs ou pas selon un contexte (souvent un contexte par module : par exemple "productcard" pour les produits, "invoicecard" pour les factures...). Pour trouver les Hooks existants faites une recherche pour "'''initHooks('''"
+*Les Hooks sont des fonctions qui s'insèrent dans ou remplacent le code standard. Pour rechercher le code qu'il est possible de surcharger faites une recherche pour "'''executeHooks('''".
+=Ajouter un hook pour permettre l'insertion de code=
+Pour implémenter un hook dans votre propre module (afin que votre module puisse être "crocheté", "détourné" par d'autres), vous devrez procéder en 2 étapes.
+Ces étapes doivent êtres reproduites pour chaque script php de votre module où vous voulez implémenter des hooks.
+1- Initialiser l'object HookManager
+Pour une page, placez ce bout de code au début de votre script php (après le ''include'' du ''main''):
+<syntaxhighlight lang="php">
+// Initialize technical object to manage hooks of thirdparties. Note that conf->hooks_modules contains array array
+include_once(DOL_DOCUMENT_ROOT.'/core/class/hookmanager.class.php');
+$hookmanager=new HookManager($db);
+$hookmanager->initHooks(array('context'));
+</syntaxhighlight>
+$hookmanager->initHooks() accepte 1 paramètre (un array de contextes) et active la prise en charge des hooks pour ce script. '<nowiki/>'''context'''' est la chaine qui contient le contexte d'exécution. C'est un simple indicateur qui peut être utilisé par les fonctions de hook pour détecter dans quel cas elles sont appelées (plusieurs pages/modules peuvent appeler le même hook à différent endroit, et une fonction de hook peut ne vouloir s'exécuter que pour un contexte donné et pas les autres).
+Note: Vous pouvez positionner plusieurs contextes en même temps (par exemple si vous avez besoin d'avoir un contexte commun à plusieurs pages mais que vous voulez aussi un contexte propre à une page donnée).
+Pour une méthode ou fonction, il est possible de récupérer le gestionnaire de Hook par:
+<syntaxhighlight lang="php">
+global $hookmanager;
+</syntaxhighlight>
+2- Placer ensuite l'appel des hooks là où l'ajout de code est désiré :
+<syntaxhighlight lang="php">
+$parameters=array();
+$reshook=$hookmanager->executeHooks('hookname',$parameters,$object,$action); // See description below
+// Note that $action and $object may have been modified by hook
+if (empty($reshook))
+{
+ ... // standard code that can be disabled/replaced by hook if return code > 0.
+}
+</syntaxhighlight>
+'''$hookmanager->executeHooks()''' accepte 4 paramètres et ajoute un hook (qui est un point d'entrée dans votre script pour des fonctions externes à votre script et module):
+- '<nowiki/>'''hookname'''' est le nom de la méthode qui sera appelée. Par exemple: 'formObjectOptions'
−= Implementation =
+- '''$parameters''' est un tableau personnalisé pour transmettre plus de données personnalisées au hook (la fonction dans le hook peut traiter ces données). Placez ici ce que vous voulez, ce peut être un fichier, un tableau de chaînes de caractères, n'importe quoi... Par exemple :
+<syntaxhighlight lang="php">
+$parameters=array('file'=>'my/path/to/a/file', 'customnames'=>array('henry','david','john'));
+</syntaxhighlight>
−- '''$object''' est l'objet que vous voulez passer à la fonction du hook, certainement les données du module courant (ex: l'objet facture si on est dans un module de facture, etc..). Ce peut être ce que vous voulez, mais souvenez vous qu'il sera le principal composant utilisé par les fonctions du hook.
−- '''$action''' est une chaîne indiquant l'action courante (peut être ''null'' ou quelque chose qui ressemble à 'create' ou 'edit').
−<source lang="php">
+Note: Vous devrez refaire cette étape plusieurs fois si vous voulez ajouter plusieurs hooks à différent endroits de votre script.
−$this->const = array(
+Maintenant votre module devrait pouvoir exécuté des hooks d'autres origines. Vous pouvez à présent suivre la procédure ci-dessous ( '''Implémenter un hook''' ) pour construire une fonction qui se raccrochera au hook (permet aussi de tester que cela fonctionne).
−'Hooks list for managing printing functions of the CustomFields module', 0, 'current', 1)
+=Implémenter un Hook=
+Pour utiliser un Hook (donc ajouter ou surcharger une partie de code), vous devez d'abord avoir défini un descripteur de module (voir [[Développement_module#Créer_un_descripteur_de_Module_(obligatoire)]] pour cela). Ensuite vous devez suivre les étapes suivantes :
+1. Ajouter votre module au contexte où le hook doit s'exécuter.
+Ce qui veut dire que lorsqu'on se trouve dans le contexte donné, votre code sera appelé.
+Pour cela, éditer le descripteur de votre module ('''/htdocs/''yourmodulename''/core/modules/mod''YourModuleName''.class.php''') et renseignez la variable '''$this->module_parts''' comme sur l'exemple :
+<syntaxhighlight lang="php">
+$this->module_parts = array(
+'hooks' => array('hookcontext1','hookcontext2') // Set here all hooks context you want to support
);
);
−</source>
+</syntaxhighlight>
−Note: format of a const declaration:
+<source lang="php">
+Note: il est possible de trouver tous les contextes dans lequel vous êtes au sein d'une portion de code PHP en faisant
−<syntaxhighlight lang="php">
−$key2=>...
+print('Module context: '.join(',', $object->contextarray));
−</source>
+</syntaxhighlight>
−(rajoutez ce bout de code dans le fichier PHP où réside l'appel des hooks, et supprimez le, une fois la valeur des contextes relevée).
−Notez que le contexte '''all''' signifie que vous souhaitez que votre hook soit exécuté quel que soit le contexte. Le '''main''' signifie que vous voulez que votre hook soit exécuté pour n'importe quelle page Web, et '''cli''' signifie dans chaque script de ligne de commande (même si vous ne pouvez pas voir ces clés de contexte dans $object->contextarray).
−'''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.
+[[File:warning.png]] Attention: N'oubliez pas de désactiver puis de réactiver votre module dans l'interface d'administration des modules (ou directement dans le "constructeur de module") afin que la modification soit prise en compte, car l'enregistrement qui relie les éléments du couple "module-hook" est géré en base de donnée; celle-ci n'étant mise à jour qu'au moment de la (ré)activation du module.
−2- You will overload a hook (a function) with your own.
+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 qui contient la méthode appelée par le hook (le nom de cette méthode se voit au moment de l'appel executeHooks). Voici un exemple:
−<source lang="php">
+<syntaxhighlight lang="php">
−class ActionsYourModuleName // extends CommonObject
+class ActionsYourModuleName
{
{
− /**
− * Overloading the doActions function : replacing the parent's function with the one below
− *
− * @param array() $parameters Hook metadatas (context, etc...)
− * @param CommonObject &$object The object to process (an invoice if you are in invoice module, a propale in propale's module, etc...)
− * @param string &$action Current action (if set). Generally create or edit or null
− * @param HookManager $hookmanager Hook manager propagated to allow calling another hook
− * @return int < 0 on error, 0 on success, 1 to replace standard code
− */
− function doActions($parameters, &$object, &$action, $hookmanager)
− {
− $error = 0; // Error counter
− $myvalue = 'test'; // A result value
− print_r($parameters);
− echo "action: " . $action;
− print_r($object);
− if (in_array('somecontext', explode(':', $parameters['context'])))
+ {
+ // do something only for the context 'somecontext'
+ }
+ if (! $error)
+ {
+ $this->results = array('myreturn' => $myvalue);
+ $this->resprints = 'A text to show';
+ return 0; // or return 1 to replace standard code
+ }
+ else
+ {
+ $this->errors[] = 'Error message';
+ return -1;
+ }
+ }
}
}
−</source>
+</syntaxhighlight>
+La méthode sera alors automatiquement appelée au moment de l'appel du code qui contient le executeHooks fournissant à votre code les éléments $parameters, $object et $action.
+'''Avec''' :
+*'''$parameters''' est un tableau (array) de meta-data regroupant les données du hook (son contexte accessible par $parameters['context'] mais d'autres information peuvent etre disponible selon le cas)
+*'''$object''' est l'objet sur lequel vous désirez travailler (par exemple : product pour le contexte productcard)
+*'''$action''' désigne l'action à exécuter (par exemple "create", "edit" or "view").
+*'''$hookmanager''' n'est propagé que pour permettre à votre hook d'appeler d'autres hooks.<br />
+'''Retours de fonction''' :
+*Le code retour d'un hook doit être 0 ou 1 en cas de succès, négatif en cas d'erreur. En général, il sera 0. Il peut être 1, ce qui dans certains cas signifie que ce que fait votre hook remplace complètement ce que devait faire Dolibarr juste après l'appel du hook. Si le code est négatif, il est possible de fournir un message d'erreur à l'utilisateur en positionnant $this->errors[]='Message erreur'
+*Si la méthode positionne la propriété $this->results avec un tableau, alors le tableau $hookmanager->resArray sera automatiquement enrichi avec le contenu de ce tableau, lequel pourra être réutilisé plus tard.
+*Si la méthode positionne la propriété $this->resprints avec une chaîne, alors cette chaîne sera affiché par le gestionnaire de hook (executeHook), tout de suite à la sortie de votre méthode.
+*Votre hook peut de plus modifier les valeurs de $object et $action.
+=Liste des Hooks disponibles dans Dolibarr=
+Trouver les hooks disponibles dans Dolibarr ?
+Faites une recherche sur "'''executeHooks('''" dans le code source et vous trouverez facilement toutes les fonctions déjà implémentées.
+En voici une liste (non complète) : [[:Category:Hooks]]
+...
+Note: veuillez noter que cette liste s'enrichit à chaque version, donc si vous voulez vraiment savoir si un hook ou contexte spécifique existe, veuillez chercher directement dans le code source avec la méthode indiquée ci-dessus.
+=Liste des Contextes disponibles dans Dolibarr=
−Pour trouver les contextes disponibles dans Dolibarr, la procédure est similaire aux hooks.
−Faites une recherche sur "'''initHooks('''" dans le code source et vous trouverez facilement tous les contextes déjà implémentées.
−{{ListOfContexts}}
−Note: veuillez noter que cette liste s'enrichie à chaque version, donc si vous voulez vraiment savoir si un hook ou contexte spécifique existe, veuillez chercher directement dans le code source avec la méthode indiquée ci-dessus.
−=Voir aussi=
−*[[Triggers]]
−* [[Triggers]]
+*[[Interfaces Dolibarr toward foreign systems]]
−* [[Interfaces Dolibarr toward foreign systems]]
+*[[Interfaces from foreign systems toward Dolibarr]]
−* [[Interfaces from foreign systems toward Dolibarr]]