Système de Hooks

De Dolibarr Open Source ERP CRM Wiki.

Retour index
Documentation développeur

File Doc dev.png

Contents

Introduction

Les Hooks sont une fonctionnalité pour les développeurs, disponible à partir de Dolibarr 3.2, leur permettant d'ajouter du code personnalisé aux pages standards 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 dès lors qu'ils ont été prévu dans le core de Dolibarr. Ce sont des points d'insertion dans le programme.

  • 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 "hooké" par d'autres), vous devrez procéder à 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 (placez ce bout de code au début de votre script php, juste après ou avant les includes):

// 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'));

$hookmanager->initHooks() accepte 1 paramètre (un array de contextes) et active la prise en charge des hooks pour ce script:

- '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 context commun à plusieurs pages mais que vous voulez aussi un context propre à une page donnée).


2- Placer ensuite l'appel des hooks la où permettre l'ajout de code:

$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.
}

$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):

- 'hookname' est le nom de la méthode qui sera appelée. Par exemple: 'formObjectOptions'

- $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 :

$parameters=array('file'=>'my/path/to/a/file', 'customnames'=>array('henry','david','john'));

- $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').

Note: Vous devrez refaire cette étape plusieurs fois si vous voulez ajouter plusieurs hooks à différent endroits de votre script.

Maintenant votre module devrait pouvoir être hooké, vous pouvez suivre la procédure ci-dessous dans Implémenter un hook pour implémenter une fonction hook qui en prendra avantage (permet aussi de tester que cela fonctionne).

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/modYourModuleName.class.php) et renseignez la variable $this->module_parts comme sur l'exemple :

$this->module_parts = array(
'hooks' => array('hookcontext1','hookcontext2')  // Set here all hooks context you want to support
);

Note: il est possible de trouver le contexte d'un module en rajoutant

print('Module context: '.$object->context);

(rajoutez ce bout de code dans le fichier php où réside l'appel des hooks, et supprimez le, une fois la valeur du context relevée).

Warning.png Attention: N'oubliez pas de désactiver puis de réactiver votre module dans l'interface d'administration des modules afin que la modification soit prise en compte car la sauvegarde des couples "modules-hooks" qui doit être gérée est faite en base, laquelle n'est mise à jour qu'au moment de l'activation du module.


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:

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;
		}
	}
}

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.

Retours:

  • Le code retour d'un hook doit 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):

  • afterLogin
  • beforePDFCreation
  • afterPDFCreation
  • afterODTCreation
  • createFrom
  • doActions
  • printLeftBlock
  • printSearchForm
  • printTopRightMenu
  • printObjectLine
  • formAddObject: Add a product into an element
  • formObjectOptions: called everytime fields associated to the main object are printed or inputted (eg: creation form, datasheet, edit form, etc..).
  • formConfirm
  • createDictionaryFieldlist
  • editDictionaryFieldlist
  • viewDictionaryFieldlist

...

Note: veuillez noter que cette liste peut changer à tout moment dans le futur au fur et à mesure que les hooks et contextes soient implémentés dans Dolibarr, 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 Contexts 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.

En voici une liste (non complète): adherents\card.php(111): membercard
adherents\type.php(73): membertypecard
categories\categorie.php(96): categorycard
comm\card.php(72): commcard
comm\propal.php(99): propalcard
comm\action\card.php(85): actioncard
comm\action\index.php(112): agenda
comm\mailing\card.php(55): mailingcard
commande\card.php(93): ordercard
compta\facture.php(105): invoicecard
compta\paiement.php(70): paiementcard
compta\deplacement\card.php(50): tripsandexpensescard
compta\dons\card.php(53): doncard
compta\localtax\clients.php(172): externalbalance
compta\salaries\card.php(47): salarycard
compta\tva\card.php(45): taxvatcard
contact\card.php(77): contactcard
contrat\card.php(70): contractcard
expedition\card.php(85): expeditioncard
fichinter\card.php(80): interventioncard
fourn\card.php(54): suppliercard
fourn\commande\card.php(80): ordersuppliercard
fourn\commande\orderstoinvoice.php(88): orderstoinvoicesupplier
fourn\facture\card.php(72): invoicesuppliercard
fourn\facture\paiement.php(71): paymentsupplier
livraison\card.php(68): deliverycard
product\card.php(91): productcard
product\fournisseurs.php(62): pricesuppliercard
product\stats\commande.php(45): productstatsorder
product\stats\commande_fournisseur.php(45): productstatssupplyorder
product\stats\contrat.php(45): productstatscontract
product\stats\facture.php(48): productstatsinvoice
product\stats\facture_fournisseur.php(47): productstatssupplyinvoice
product\stats\propal.php(45): productstatspropal
product\stock\card.php(54): warehousecard
projet\card.php(48): projectcard
projet\tasks.php(67): projecttaskcard
resource\card.php(60): resource_card
resource\element_resource.php(58): element_resource
societe\agenda.php(41): agendathirdparty
societe\commerciaux.php(40): salesrepresentativescard
societe\consumption.php(80): consumptionthirdparty
societe\info.php(41): infothirdparty
societe\soc.php(80): thirdpartycard
user\card.php(93): usercard
user\passwordforgotten.php(56): passwordforgottenpage
...

Note: veuillez noter que cette liste peut changer à tout moment dans le futur au fur et à mesure que les hooks et contextes soient implémentés dans Dolibarr, 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

Outils personnels
  • Ask to contact@dolibarr.org to request an account to contribute to this documentation
  • Connexion
Autres langues
AnglaisEspagnolAllemand
Pas de traduction en Allemand.
Italien
Pas de traduction en Italien.
Grèque
Pas de traduction en Grèque.
<multilanguagemanager_cn>
Pas de traduction en &lt;multilanguagemanager_cn&gt;.

Social networks
Follow us on Google+ Follow us on Facebook Follow us on LinkedIn Follow us on Twitter