Hook Examples

Code Hook Example

Let's register a code hook for a fictitious module named "My Module", found in a "my_module" folder. The purpose is to execute out own PHP code when a certain event happends in the code. Here's how we register the hook:

ft_register_hook("code", "my_module", "start", "ft_process_form", "my_hook", 50);

This line registers the code hook for the function ft_process_form; it tells it to call the my_hook function at the "start" location in the function. The priority is set to 50 (out of 1-100). The priority determines the order in which the hook should get executed if there are multiple hooks assigned to the same hook.

As mentioned earlier, this line can be placed in your module's installation function, or called at some point in your module pages based on user input.

Now let's look at the my_hook function. This function MUST be located in your module's library.php file - or included by that file. When hooks are processed, they are looked for at that location. If it can't be found, the hook is ignored.

Code hook functions should always accept a single parameter: a hash (associative array) containing whatever information is passed by that particular function.

function my_hook($vars)
{
  // $vars always contains the form_tools_overridable_vars key: an array of variable names that
  // can be overwritten by your hook for this particular core function. Some core functions
  // don't allow any values to be overwritten, so this will be empty
  print_r($vars["form_tools_overridable_vars"]);

  // this key always contains the name of the core function that is calling your hook
  echo $vars["form_tools_calling_function"];

  // return values
  $info = array();
  $info["name"] = "Overridden!";
  return $info;
}

The comments should explain quite a bit. The two keys, form_tools_overridable_vars and form_tools_calling_function are always passed to the function. The calling function can be handy if you need your hook has been registered to multiple core functions and you'd like it to behave differently based on the context. The form_tools_overridable_vars key contains an array of the names of variables that can be overridden. To override them, just make your function return a hash with those values as keys. Any other values in that hash will be ignored. If the value isn't overridden, the core function will continue ordinary processing.

For more information about the meaning of each variable, you'll need to look at the core function.

Template Hook Example

Now let's register a template hook, to insert some HTML into one of the places in the Form Tools pages. Here's our register function:

ft_register_hook("template", "my_module", "edit_client_main_top", "", "say_hello", 50);

Like with the code hook register function calls, this line would usually be added to your module's installation script, so that the hook gets registered once when the module is first installed.

This line of code registers the template hook for the my_module function, to be called at the edit_client_main_top location in the templates. In order words, it'll be called wherever you find this line in one of the templates:

{template_hook location="admin_edit_client_main_top"}

(This happens to be in the /themes/default/admin/clients/tab_main.tpl template file).

Lastly, it tells the script to call the say_hello() PHP function, and gives it a priority of 50 (from 1-100, where 1 is top priority). Here's what the say_hello function would look like. All template hook functions should take two parameters:

/**
 * Our template hook function.
 *
 * @param string $location the name of the template hook (i.e. the value of the "location"
 *   attribute of the template hook, found in the Smarty template)
 * @param array $info a giant array containing all the data available to the template. This
 *   will contain whatever information you need, but you'll have to hunt for it.
 */
function say_hello($location, $info)
{
  echo "hello!";
}