Vesthelm Engine

2.1.4 User Guide

Hooks Class

Hooks allows you to dynamically change or add functionality without changing Vesthelm Engine core files.

In Vesthelm Engine there are two types of hooks: controller and dynamic

  • Controller Hook - Use when you do not need to modify variables values in a file or class!!!
    Advantages: easier debugging, do not need to edit database table to change hook - hook code stored in a file.
    Disadvantages: less functionality than dynamic hook - can not modify variables values
  • Dynamic Hook - Use when you need to modify variables values in a file or class!!!
    Advantages: powerful
    Disadvantages: to change hook code need to edit database table, hard debugging - using eval()
  • Calling a Hook

Creating a Controller Hook

Let's say you want to assign variable to bulletin board application template. So you will use hook AfterRegisterFunctions defined in includes/smarty.php

defined('V_IN_FRONTEND') or die('Powered by <a href="http://www.vesthelm.com/">Vesthelm EE</a>');

class Bulletin_Board_AfterRegisterFunctions_Hook extends Vesthelm_Hook_Controller {

    public function execute() {
        var_dump('Testing Controller Hook');
    }

    public function init() {
        $this->_initBulletins();
    }

    public function assign() {
        $this->_assignBulletins();
    }

    protected function _initBulletins() {
        $this->sponsored_bulletins = $this->bulletin_board->Bulletin->getBulletins();
    }

    protected function _assignBulletins() {
        if (!empty($this->sponsored_bulletins)) {
            $this->View->assign("sponsored_bulletins", $this->sponsored_bulletins);
        }
    }

}

And now in your template files you can use $sponsored_bulletins variable:

{if $sponsored_bulletins}
    {foreach from=$sponsored_bulletins item=bulletin name="bulletins"}
        {$bulletin.description}
    {/foreach}
{/if}

Anatomy of a Controller Hook

Controller Hooks classes are stored in folders:

//Core hooks
example.com/frontend/hooks
example.com/acp/hooks

//Application hooks
example.com/applications/{application_name}/frontend/hooks
example.com/applications/{application_name}/acp/hooks

//Addon hooks
example.com/addons/{addon_name}/frontend/hooks
example.com/addons/{addon_name}/acp/hooks

The basic prototype for a hook class is:

class Enhancement_Name_Hook_Name_Hook extends Vesthelm_Hook_Controller {
    public function execute() {        
    }
}

Where Enhancement_Name is the name of your enhancement. Enhancement names must have the first letter capitalized after underscore _ character.

Where Hook_Name is the name of your class. Class names must have the first letter capitalized after underscore _ character.

The file name will be same as your class name (Hook_Name). For example, if your class is:

class Bulletin_Board_AfterRegisterFunctions_Hook extends Vesthelm_Hook_Controller {
    public function execute() {        
    }
}

Your file will be:

applications/bulletin_board/acp/hooks/AfterRegisterFunctions.php

Creating a Dynamic Hook

Dynamic Hooks evaluated by PHP eval()

Let's say you want to unset variable $enhancements in a file includes/smarty.php. So you will use hook AfterRegisterFunctions and add following code to database table hooks:

global $enhancements;

$enhancements = null;

MySQL query:

INSERT INTO `{your_table_prefix}_hooks` (`id`, `enh`, `file`, `name`, `value`, `code`, `status`, `enhancement`, `side`, `u_id`, `order`) VALUES
(NULL, '', 'index', 'AfterRegisterFunctions', 'global $enhancements;

$enhancements = null;', 'php', 'active', '', 'frontend', '', 0);

Calling a Hook

To call hook in a file:

call_hook('hookName', 'enhancement_name', 'file_name');

Where hookName is the name of your hook.

Where enhancement_name is the name of your enhancement. (if empty value specified will try to use V_APPLICATION or V_ADDON constant)

Where file_name is the name of your file where you adding call_hook() function. (if empty value specified will try to use V_REALM constant)