98
edits
Hooks system: Difference between revisions
Jump to navigation
Jump to search
m
→Implement the Hook
| Line 71: | Line 71: | ||
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 = | = Implement the Hook functions = | ||
To use a hook (add | 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. | ||
1- add your module to the list of contexts you want to hook on. | One the descriptor is created, two further steps are required: | ||
This means that when a context | |||
1- add your module/the core module context name to the list of contexts you want to hook on. | |||
This means that when the core program code executes a context, your module hook function will be called. | |||
Edit your '''/htdocs/''yourmodulename''/core/modules/mod''YourModuleName''.class.php''' and add the context name to the variable '''$this->module_parts'''. | |||
eg: | |||
<source lang="php"> | <source lang="php"> | ||
$this->module_parts = array( | $this->module_parts = array( | ||
| Line 84: | Line 87: | ||
</source> | </source> | ||
Don't forget to change YourModuleName to your own module's name! | |||
Note: | Note: one way to determine the context name of the core module that you wish to modify is by adding this code in that modules php code: | ||
print('Module context: '.$object->context); | |||
[[File:warning.png]] | [[File:warning.png]] Note that when you add a new context name to the 'hooks' => array, this list of contexts must be stored in the database. This only occurs when the custom module is enabled. | ||
So, when you add/remove/modify/rename any context name, you MUST disable and enable the custom module for the changes to take effect. | |||
2- You will | 2- You will override a hook (a function) with your own function. | ||
Create a file '''/htdocs/''yourmodulename''/class/actions_''yourmodulename''.class.php''' and then put something like this: | Create a file '''/htdocs/''yourmodulename''/class/actions_''yourmodulename''.class.php''' and then put something like this: | ||
| Line 99: | Line 104: | ||
{ | { | ||
/** | /** | ||
* | * Overriding the doActions function : replacing the parent function with the one below | ||
* | * | ||
* @param array() $parameters Hook metadatas (context, etc...) | * @param array() $parameters Hook metadatas (context, etc...) | ||
| Line 136: | Line 141: | ||
</source> | </source> | ||
Your function should now be called when | Your function should now be called when the program executes the module/context and you will see the parameters and object and action. | ||
'''Where''': | '''Where''': | ||
* '''$parameters''' is an array of meta-data about the datas contained by the hook | * '''$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 that you may work on. Eg: the product if you are in the productcard context. | * '''$object''' is the object/data that you may work on. Eg: the product if you are in the productcard context. | ||
* '''$action''' is the action if one is | * '''$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. | * '''$hookmanager''' is propagated only to allow your hook to call another hook. | ||
'''Returns''': | '''Returns''': | ||
* The return code from a hook is 0 | * The return code from a hook ($reshook) is 0 / 1 if successful, or negative if in error. | ||
* If the method sets the property $this->results with an array, then the array $hookmanager->resArray will automatically be | |||
Return Code 0. In this case if the subsequent core module code function is enclosed by | |||
if (empty($reshook)) {...} | |||
it will execute as normal but with the data modified by your custom function. | |||
Return Code 1. In this case if the subsequent core module code function is enclosed by | |||
if (empty($reshook)) {...} | |||
it will not execute at all. So this means it has been replaced by your custom function. | |||
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->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 | * Your code may also modify the value of $object and $action. | ||
= List of available Hooks in Dolibarr = | = List of available Hooks in Dolibarr = | ||