Hooks¶

General Information¶

1. Hooks are used by developers to extend functions. So it is best to include as many parameters as possible into hooks.

2. The name of the hook must include the name of the function.

3. Prefixes are prohibited. Only suffixes are allowed.

4. If you have a complex function that includes lots of hooks, you can name hooks using this example:

   Function:

   get_cart_product_data
   

   Hook:

   fn_set_hook('get_cart_product_data_post_options', $product['product_id'], $_pdata, $product);
   

5. When listing parameters of the hook, always put the parameters accepted by the function first. SQL hooks are the only exception: everything required is included into the params variable.

6. Hooks in classes must contain the name of the calling class in their name.

7. Hooks in classes must always pass the class instance as their first parameter:

   <?php
   
   class Patterns
   {
       public function save($style_id, $style, $uploaded_data)
       {
           ...
   
           /**
            * Executes before saving the uploaded pattern files, allows you to modify the uploaded files and their location.
            *
            * @param \Tygh\Themes\Patterns $this          Patterns instance
            * @param string                $style_id      Style name
            * @param array                 $style         Style data
            * @param array                 $uploaded_data Uploaded files
            * @param string                $path          Path where patterns will be saved
            * @param string                $rel_path      Relative patterns path
            */
           fn_set_hook('patterns_save', $this, $style_id, $style, $uploaded_data, $path, $rel_path);
   
           ...
   

How and Where to Add Hooks¶

We assume that each function must contain at least two hooks:

1. A pre hook like get_product_name_pre at the beginning of the function. All parameters accepted by the function must be passed to this hook.
2. A post hook like get_product_name_post at the end of the function. List the parameters in the following order: first all the parameters accepted by the function, then the parameters returned by the function, and then the other auxiliary parameters.

Also there are might be other extra hooks:

3. An SQL hook like get_product_name. All SQL variables are passed to this hook. It is recommended to create all $fields, $condition, $sorting, $limit, etc. values even if you think that it is unnecessary. You can leave them empty. For example:

   fn_set_hook('get_product_name', $product_id, $lang_code, $as_array, $field_list, $join, $condition);
   

4. extra hooks. As an example we will use products selection:

   fn_set_hook('get_products_before_select', $params, $join, $condition, $u_condition, $inventory_join_cond, $sortings, $total, $items_per_page, $lang_code, $having);
   

Some of the hooks do not comply with these standards. In this case we add a comment like:

/**
 * Deprecated: This hook will be removed in version 4.x or 3.3.x. Use get_product_price_pre instead.
 */

Then we also add a hook that follows the standards. In our case it is get_product_price_pre.

Hook Format Standard¶

The formats for comments from the hooks base are provided below.

<?php

/**
 * Processes cart data after calculating all prices and other data (taxes, shippings etc)
 *
 * @param array  $cart               Cart data
 * @param array  $cart_products      Cart products
 * @param array  $auth               Auth data
 * @param string $calculate_shipping // 1-letter flag
 *      A - calculate all available methods
 *      E - calculate selected methods only (from cart[shipping])
 *      S - skip calculation
 * @param bool $calculate_taxes       Flag determines if taxes should be calculated
 * @param bool $apply_cart_promotions Flag determines if promotions should be applied to the cart
 */
fn_set_hook('calculate_cart', $cart, $cart_products, $auth, $calculate_shipping, $calculate_taxes, $apply_cart_promotions);
?>

<?php

/**
 * Change SQL parameters for product data select
 *
 * @param int $product_id Product ID
 * @param string $field_list List of fields for retrieving
 * @param string $join String with the complete JOIN information (JOIN type, tables and fields) for an SQL-query
 * @param mixed $auth Array with authorization data
 * @param string $lang_code Two-letter language code (e.g. 'en', 'ru', etc.)
 * @param string $condition Condition for selecting product data
 */
fn_set_hook('get_product_data', $product_id, $field_list, $join, $auth, $lang_code, $condition);
?>

{** Dynamic menu item (on the navigation) *}
{hook name="index:dynamic_menu_item"}
...
{/hook}

{** Hooks for CSS styles *}
{hook name="index:styles"}{/hook}

/**
 * Hook description
 */
var hook_data = {
    'append_obj_content': append_obj_content, // int Id of bla bla
    'var_prefix': prefix, // string Prefix of var
    'object_html': unescape(append_obj.html()), // string Object
    'var_id': id, // int ID of var
    'item_id': js_items[id] // int Item ID
};

$.ceEvent('trigger', 'ce.picker_add_js_item', [hook_data]);