1. This site uses cookies. By continuing to use this site, you are agreeing to our use of cookies. Learn More.

[Docs] Working with Plugin Hooks

Discussion in 'Developing Plugins' started by Nick, Jun 27, 2009.

  1. Nick

    Nick Well-Known Member

    Part 1: The Basics of Plugin Hooks

    Plugin hooks allow developers to add functionality to Hotaru CMS or other plugins. A typical plugin hook looks like this:

    In a plugin:
    PHP:
    $h->pluginHook('hook_name');
    In a template:
    PHP:
    <?php $h->pluginHook('hook_name'); ?>
    Some plugin hooks are built into Hotaru and the default themes, others are custom hooks that plugin developers ask users to add to their themes. The only significant difference between the two is that a custom hook uses a name chosen by the plugin developer, usually the name of the plugin. Here are examples of each:

    PHP:
    $results $h->pluginHook('theme_index_top');
    PHP:
    <?php $h->pluginHook('rss_show'); ?>
    In order for your plugin to use a hook, you must include the hook's name at the top of your plugin file, eg.

    PHP:
    hookstheme_index_top
    Then, you need a function with the same name as the hook, e.g.

    PHP:
    public function theme_index_top($h)
    {
    ...
    // your code
    ...
    }
    Note that if you want your plugin to output something, you should echo it from within the function instead of returning it, e.g.

    PHP:
    public function hello_world($h)
    {
        echo 
    "Hello World!";
    }
    In the next post, we'll look at some configuration options for the pluginHook function.
     
    Last edited: Jan 6, 2010
  2. Nick

    Nick Well-Known Member

    Part 2: Using the check_actions() function

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

    PHP:
    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.
    (5) an array of plugins you don't want to be included.

    Examples

    Run all functions with the theme_index_top hook:
    PHP:
    $h->pluginHook('theme_index_top');
    Only run functions is the Users plugin that use the theme_index_top hook:
    PHP:
    $h->pluginHook('theme_index_top''users');
    Send the values 'red', 'green' and 'blue' to all functions using the theme_index_top hook:
    PHP:
    $h->pluginHook('theme_index_top''users', array('red''green''blue'));
    Tell the RSS Show plugin to display feed #3:
    PHP:
    $h->pluginHook('rss_show''', array(3));
    2. Sending results back to the check_actions 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:

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

    PHP:
    $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.
    (3) 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:
    PHP:
    $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:

    PHP:
    $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.
     
    Last edited: Jan 8, 2010
  3. Nick

    Nick Well-Known Member

    Checking for results from plugins

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

    PHP:
    // 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.
     

Share This Page