Hotaru Docs

 [həʊdɒks]

Using the pluginHook() function

pluginHook() is a function in PluginFunctions.php in Hotaru's libs folder.

Note: Read Plugin Hook Basics before reading this.

public function pluginHook($hook = '', $folder = '', $parameters = array(), $exclude = array())
{
...
}

Rather then explain the function here, let's look at possible input arguments and the different results you can get.

1. Input parameters

pluginHook has four default inputs:

  1. $hook = "";
  2. $folder = "";
  3. $parameters = array();
  4. $exclude = array();
  1. is the name of the plugin hook.
  2. is if you want to specify which plugin to use. In most cases, this will be blank so all plugins with the same hook will run.
  3. an array of additional arguments to pass to each function at that hook.
  4. an array of plugins you don't want to be included.

Examples

Run all functions with the theme_index_top hook:

$h->pluginHook('theme_index_top');

Only run functions in the Users plugin that use the theme_index_top hook:

$h->pluginHook('theme_index_top', 'users');

Send the values 'red', 'green' and 'blue' to all functions using the theme_index_top hook:

$h->pluginHook('theme_index_top', 'users', array('red', 'green', 'blue'));

Tell the RSS Show plugin to display feed #3:

$h->pluginHook('rss_show', '', array(3));

2. Sending results back to the pluginHook hook

Note: In most cases, you shouldn't need to send data back to a plugin hook. Even if you do, it is only worthwhile if there is additional code after the hook that does something with the returned data. The easy way:

The easiest way to pass data back and forth is by storing it in the global $h object. Here's an example:

$h->vars['stuff'] = "manipulate me in a plugin!";
$h->pluginHook('hook_name'); // plugins can change $h->vars['stuff']
echo $h->vars['stuff'];

The hard way:

Returning data can get confusing, so let's try to visualize what happens:

  • HOOK <- pluginHook() <- FUNCTION 1
  • ....................... FUNCTION 2
  • ....................... FUNCTION 3

The pluginHook function can return 2 possible results to the hook:

  1. false
  2. array of data
  1. occurs when no hook name is specified, no functions with that hook name were found, or all plugins returned false.
  2. is returned when at least one function sends data back or simple true.

Because there may be more than one function at any hook, data returned from the functions is collected by pluginHook in an associative array like this:

$return_array = (
                  'class1name_hookname' => $data1,
                  'class2name_hookname' => $data2,
                  'class3name_hookname' => $data3
);

In many cases, you won't know which plugins will be returning values to the hook, so it's best not to explicitly use class names. If you're only interested in the value returned by the first plugin, try something like this:

$plugin_result = $h->pluginHook('hook_name');
if ($plugin_result) {
     reset ($plugin_result); // order the array
     echo key($plugin_result); // get the real name of class1name_hookname
     echo $plugin_result[key($plugin_result)]; // get the value of that key
}

Note: For additional information about plugin hooks and how theme designers can work around them, read Designing around Plugin Hooks.

Checking for results from plugins

This code works well when you need to prevent your regular code running when a plugin is used:

// Allow other plugins to override this code
$result = $h->pluginHook('hook_name');
if (!$result)
{ 
    // No plugin results, so do the regular stuff here...
 
}

You can see that used a few times in the default theme's index.php file.

Getting StartedDesign and LayoutPlugin DevelopmentAdvanced TopicsFunction ReferenceTroubleshooting