1,988
edits
Hooks system: Difference between revisions
m
add to category Development
PolyglotBot (talk | contribs) m (Import interlang links (links to translated versions of this page in other languages) from Multi Language Manager table.) |
m (add to category Development) |
||
| Line 9: | Line 9: | ||
{{TemplateDocDevEn}} | {{TemplateDocDevEn}} | ||
= Introduction = | =Introduction= | ||
Every business always requires something "extra" or different to the Dolibarr core functionality. | Every business always requires something "extra" or different to the Dolibarr core functionality. | ||
While all improvements and extensions to the Dolibarr code should be contributed back via Github to be included in a future version, some modifications will be too specific to be of interest to all. | While all improvements and extensions to the Dolibarr code should be contributed back via Github to be included in a future version, some modifications will be too specific to be of interest to all. | ||
| Line 23: | Line 23: | ||
So to use a hook, you need to know its context name (its location) and the hook name. | So to use a hook, you need to know its context name (its location) and the hook name. | ||
* The Hook Context Name (e.g.: "productcard" for products, "invoicecard" for invoices, etc..). can be found by searching for "'''initHooks('''" in the php files. | *The Hook Context Name (e.g.: "productcard" for products, "invoicecard" for invoices, etc..). can be found by searching for "'''initHooks('''" in the php files. | ||
This will find results such as "$hookmanager->initHooks(array('thirdpartycomm','globalcard'));" where "thirdpartycomm" is the context. | This will find results such as "$hookmanager->initHooks(array('thirdpartycomm','globalcard'));" where "thirdpartycomm" is the context. | ||
* The Hook Name can be found by searching for "'''executeHooks('''" in the block of code you are interest in modifying...possibly there may be no hook defined so you may add your own (and submit a corresponding pull-request in Github so it gets included in a future version). | |||
*The Hook Name can be found by searching for "'''executeHooks('''" in the block of code you are interest in modifying...possibly there may be no hook defined so you may add your own (and submit a corresponding pull-request in Github so it gets included in a future version). | |||
This will find results such as "$reshook = $hookmanager->executeHooks('addMoreBoxStatsCustomer', $parameters, $object, $action);" where "addMoreBoxStatsCustomer" is the Hook name. | This will find results such as "$reshook = $hookmanager->executeHooks('addMoreBoxStatsCustomer', $parameters, $object, $action);" where "addMoreBoxStatsCustomer" is the Hook name. | ||
= Adding a hook point into code= | =Adding a hook point into code= | ||
To add a hook into a module (so that the module can be ''hooked'' by others), two code additions are required in each php script where you want to implement hooks. Hooks are implemented in Dolibarr core modules in the same manner. | To add a hook into a module (so that the module can be ''hooked'' by others), two code additions are required in each php script where you want to implement hooks. Hooks are implemented in Dolibarr core modules in the same manner. | ||
| Line 43: | Line 46: | ||
$hookmanager->initHooks() takes 1 parameter (an array of contexts) and activates the hooks management for this script: | $hookmanager->initHooks() takes 1 parameter (an array of contexts) and activates the hooks management for this script: | ||
- ''''context'''' is a context string. This is simply a indicator that hooking functions can use, to detect in which context they are called. | - '<nowiki/>'''context'''' is a context string. This is simply a indicator that hooking functions can use, to detect in which context they are called. | ||
Note: you can set several contexts in the same init (for example if you want to have a common context into several pages and want also a specific context dedicated to your page). | Note: you can set several contexts in the same init (for example if you want to have a common context into several pages and want also a specific context dedicated to your page). | ||
| Line 62: | Line 65: | ||
'''$hookmanager->executeHooks()''' takes 4 parameters and add a hook (an entry point in your script for external functions): | '''$hookmanager->executeHooks()''' takes 4 parameters and add a hook (an entry point in your script for external functions): | ||
- ''''hookname'''' is the hook's name as a string (can be anything you want, or you can follow the Dolibarr's nomenclatura, look at the list of hooks below). eg: 'formObjectOptions' | - '<nowiki/>'''hookname'''' is the hook's name as a string (can be anything you want, or you can follow the Dolibarr's nomenclatura, look at the list of hooks below). eg: 'formObjectOptions' | ||
- '''$parameters''' is a custom array to send data to the hook so the hooking function can process it. It can be a file, an array of strings, anything... | - '''$parameters''' is a custom array to send data to the hook so the hooking function can process it. It can be a file, an array of strings, anything... | ||
| Line 79: | Line 82: | ||
Now your module should be hookable, and you can follow the procedure below in '''Implement a hook''' to implement a hooking function that will take advantage of your new hooks. | Now your module should be hookable, and you can follow the procedure below in '''Implement a hook''' to implement a hooking function that will take advantage of your new hooks. | ||
= Implement the Hook functions = | =Implement the Hook functions= | ||
To use a hook (to add to/replace a part of code), you first need to already have defined a module descriptor (see [[Module_development#Create_your_module_descriptor]]). Using a hook function is a part of creating a custom module, so please use the built-in Module Builder to easily create a custom module from a template so you can then modify the relevant hook section. | To use a hook (to add to/replace a part of code), you first need to already have defined a module descriptor (see [[Module_development#Create_your_module_descriptor]]). Using a hook function is a part of creating a custom module, so please use the built-in Module Builder to easily create a custom module from a template so you can then modify the relevant hook section. | ||
| Line 152: | Line 155: | ||
'''Where''': | '''Where''': | ||
* '''$parameters''' is an array of meta-data about the datas contained by the hook. Note the calling context is stored in $parameters['context'] which is added to the array when it branches through hookmanager. | |||
* '''$object''' is the object/data that you may work on. Eg: the product if you are in the productcard context. | *'''$parameters''' is an array of meta-data about the datas contained by the hook. Note the calling context is stored in $parameters['context'] which is added to the array when it branches through hookmanager. | ||
* '''$action''' is the action if one is passed (generally "create", "edit" or "view"). | *'''$object''' is the object/data that you may work on. Eg: the product if you are in the productcard context. | ||
* '''$hookmanager''' is propagated only to allow your hook to call another hook. | *'''$action''' is the action if one is passed (generally "create", "edit" or "view"). | ||
*'''$hookmanager''' is propagated only to allow your hook to call another hook. | |||
'''Returns''': | '''Returns''': | ||
* The return code from a hook ($reshook) is 0 / 1 if successful, or negative if in error. | |||
*The return code from a hook ($reshook) is 0 / 1 if successful, or negative if in error. | |||
Return Code 0. In this case if the subsequent core module code function is enclosed by | Return Code 0. In this case if the subsequent core module code function is enclosed by | ||
| Line 170: | Line 175: | ||
Return code is negative if an error has occurred in your function. You can also set $this->errors[]='Error message to report to user' | Return code is negative if an error has occurred in your function. You can also set $this->errors[]='Error message to report to user' | ||
* If the method sets the property $this->results with an array, then the array $hookmanager->resArray will automatically be loaded with the contents of this array, may be reused later. | *If the method sets the property $this->results with an array, then the array $hookmanager->resArray will automatically be loaded with the contents of this array, may be reused later. | ||
* If the method sets the property $this->resprints with a string, then this string will be displayed by the hook manager (method executeHook), immediately after your method exit. | *If the method sets the property $this->resprints with a string, then this string will be displayed by the hook manager (method executeHook), immediately after your method exit. | ||
* Your code may also modify the value of $object and $action. | *Your code may also modify the value of $object and $action. | ||
= List of available Hooks in Dolibarr = | =List of available Hooks in Dolibarr= | ||
How to find a complete list of all the available hooks in Dolibarr core code? | How to find a complete list of all the available hooks in Dolibarr core code? | ||
Just search for "'''executeHooks('''" through the whole sourcecode (generally called "find in files") and you should easily find all the hooked methods calls. | Just search for "'''executeHooks('''" through the whole sourcecode (generally called "find in files") and you should easily find all the hooked methods calls. | ||
| Line 184: | Line 189: | ||
Note: please note that this list changes continually as hooks and contexts are added into Dolibarr, so if you really need to find a specific hooks, please search directly in the sourcecode. | Note: please note that this list changes continually as hooks and contexts are added into Dolibarr, so if you really need to find a specific hooks, please search directly in the sourcecode. | ||
= List of available Contexts in Dolibarr = | =List of available Contexts in Dolibarr= | ||
To find a complete list of available module context names in Dolibarr, the procedure is similar to finding hooks. | To find a complete list of available module context names in Dolibarr, the procedure is similar to finding hooks. | ||
Search for "'''initHooks('''" through the whole sourcecode (generally called "find in files") and you should find all the possible contexts. | Search for "'''initHooks('''" through the whole sourcecode (generally called "find in files") and you should find all the possible contexts. | ||
| Line 194: | Line 199: | ||
Note: please note that this list changes as hooks and contexts are added into Dolibarr, so if you really need to find a specific context, please search directly in the sourcecode. | Note: please note that this list changes as hooks and contexts are added into Dolibarr, so if you really need to find a specific context, please search directly in the sourcecode. | ||
= See also = | =See also= | ||
* [[Triggers]] | |||
* [[Interfaces Dolibarr toward foreign systems]] | *[[Triggers]] | ||
* [[Interfaces from foreign systems toward Dolibarr]] | *[[Interfaces Dolibarr toward foreign systems]] | ||
*[[Interfaces from foreign systems toward Dolibarr]] | |||
[[Category:Development]] | |||