How to develop hooks compliant code

Hooks are strategically placed function calls that checks if a certain file exists in order to execute its code. Their purpose is to allow banks to customize the application without changing the core code, thus making updates easier to perform.

Contents 1 Controllers hooks 1.1 Recap 2 Views hooks 2.1 Recap

Usually, a call to a hook looks like

$hook_link = $this->hook('format');
if($hook_link){
	require($hook_link); 
}

In this example, "format" is the name of the hook. The hook name is used to find the file to execute. Thus, the name is optional when there is a single hook in a function but as soon as there is two or more, the name becomes mandatory. Hooks file name construction will is detailed in How to develop hooks.

It's important to follow hooks conventions as most as you can. Otherwise you'll make hooks programming a nightmare. If you want to know more about hooks development, see How to develop hooks.

Controllers hooks

In a display only controller function (eg.: detail, index, list all), there is generally only one hook that is at the very last lines of the function. The name used for that hook is "format". Format hooks are called after the structure is set to allow the custom code to alter it. The objective of this hook is to allow custom code to load different structures and set different variables that will be used by views hooks. Note: Since there is only one hook in those functions, the name could have been optional, but for the sake of consistency, it's been decided to keep using "format" as name.

In a data saving controller function (eg.: add, edit), there is generally two hooks. Again, the "format" hook is present, but this time it's not at the end of the function. It's right before the save/validation process starts. (Usually right before if(!empty($this->data)){). It still allows to alter the structure and variables before the view is called, but also before the core starts validating on it. There is also a second hook that is named "presave_process". That hook allows custom code to perform extra validation and to alter the data before its being saved.

The "presave_process" hooks comes along with a variable declaration:

$submitted_data_validates = true;

And right after the hook,

if($submitted_data_validates) {
	if ( $this->Participant->save($this->data) ) {
		[...]
	}
}

As you may have guessed, "$submitted_data_validates" allows the hooked code to block the save process.

Recap

Two hooks to put in controllers functions:

• format: Called before validation on submitted code starts, or at the very end of the function if this is not a data saving function. (Always present)
• presave_process: Called before the save call and preceded by $submitted_data_validates = true;. (Only in saving functions)

Views hooks

Since most views are only based on one structure, they only contain one hook. The goal of views hooks is to allow custom code to alter $structures->build parameters. Advanced users can also use them to print completely new structures and layouts.

Let's look at an example.

// Set form structure and option 
$final_atim_structure = $atim_structure; 
$final_options = array('links'=>$structure_links);

// CUSTOM CODE
$hook_link = $structures->hook();
if($hook_link){
	require($hook_link);
}
	
// BUILD FORM
$structures->build( $final_atim_structure, $final_options );

The first step is to put what will be used for $structures->build parameters in named variables. So the structure to build goes into $final_atim_structure and the options go into $final_options. Then you have the hook call... and that's it!

For views with many structures, you need many hooks, hence you'll need to specify hooks names. You are free to use whatever name you want, but stay relevant. If you load a collections structure followed by aliquots structure, naming your hooks "collections" and "aliquots" might be a good idea.

Recap

You need to:

• Have a hook before each $structures->build call.
• You need to set $final_atim_structure and $final_options which will be used in $structures->build call.
• Name your hook if you have more than one in your view.

If you want to develop hooks, see How to set up customize models => Custom hooks.