Loading...

Hooks

We no longer maintain the Knowledge Base since version 4.3.x. All the latest user and developer documentation for 4.3.x and newer versions is now available at docs.cs-cart.com.

  • This article applies to CS-Cart versions:
  • 3.0.x

Hooking is a concept in programming dealing with control flow. A hook is just a special place in the source code which serves as an entry point for some external code.

Thanks to this technique, you can create an add-on and hook it to the necessary part of code. As a result, your add-on will work without affecting the core functionality. A great practical example of hook usage is provided in the Advanced Add-on Tutorial.

CS-Cart uses 2 kinds of hooks—in the source code (PHP hooks) and in the templates (TPL hooks). Below, you can find both hook types explained.

Some general information on hooking can be found on Wikipedia.

PHP Hooks

PHP or code hook is a specially defined part in the program code that can pass control to an add-on. A hook is declared by calling a special function in the necessary part of code:

fn_set_hook('hook_name', $params, [$param2], [$paramN]);

Hooking is a very flexible technique; one function can have any number of hooks. Some CS-Cart functions have

Review all available PHP hooks in all CS-Cart versions using the Hook base tool on our official website.

What a PHP Hook Looks Like in the Source Code

Here is an example of a PHP hook used in CS-Cart. It is declared in the function fn_get_gift_certificate_info used by the Gift certificates add-on:

1
fn_set_hook('get_gift_certificate_info', $_certificate, $certificate, $type)

 

When PHP Hooks Are Used

Hooks provide a convenient way for add-ons to perform additional actions in the middle of the main flow.

Knowing the hook name, any addon can intercept execution of the program code, perform necessary manipulations, and then return the execution process to the main program. When calling a certain hook, all variables directly defined in this hook become available for the addon.

A hook call within an add-on is carried out by defining the function which name consists of the prefix "fn_", addon name, underscore and the full name of the called hook:

1
fn_gift_certificates_get_gift_certificate_info($_certificate, $certificate, $type)

 

So, according to the function name, the code inside the function will be executed in the hook get_gift_certificate_info in the add-on Gift certificates.

How to Use a PHP Hook

In order to use PHP hooks in your add-on:

  1. Declare the hook to be used in the add-on's init.php file:
    1
    2
    3
    4
    5
    6
    7
    
    ...
     
    fn_register_hooks(
    	'get_category_data_pre'
    );
     
    ...
  2. Create a function to perform actions on the hook occurence in the add-on's func.php file:
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    
    <?php
     
    if ( !defined('AREA') ) { die('Access denied'); }
     
    function fn_my_addon_get_category_data_pre($category_id, $field_list, $get_main_pair, $skip_company_condition, $lang_code)
    {
    	...
    }
     
    ?>

And that's it! The add-on is now "aware" that it should use the hook, and CS-Cart is ware that it should pass the control to the add-on when the hook occurs.

A complete and working example of hook usage in an add-on is given in the Advanced Add-on Tutorial.

TPL Hooks

TPL or template hooks are parts of a template enclosed in the tags:

{hook name="section:hook_name"}
    ...
{/hook}
that can be supplemented or completely redefined by any add-on.

What a TPL Hook Looks Like in a Template

This is an example of a template hook from the file skins/basic/admin/views/order_management/totals.tpl:

1
2
3
4
5
{hook name="order_management:product_info"}
	{if $cp.product_code}
		<p>{$lang.sku}:&nbsp;{$cp.product_code}</p>
	{/if}
{/hook}

 

When TPL Hooks Are Used

TPL hooks are used to show additional data in an existing template. For example, if an add-on collects some data that should be shown in the store administration panel in a separate block, this block can be added using a TPL hook. Such a use case is described in the Advanced Add-on Tutorial.

How to Use a TPL Hook

Unlike PHP hooks, template hooks sould not be declared explicitly. A proper file naming and placing will do the trick.

The naming algorithm is as follows:

skins/[skin name]/[admin|customer]/addons/[addon id]/hooks/[template name]/[hook name].[pre|post].tpl

Then again, an example of practical usage of a TPL hook is given in the Advanced Add-on Tutorial.

<< Read previous Read next >>