Hooks in Venddor IO

Each hook should have a brief overview explaining its role and detailing its parameters (only for PHP-hooks).

Understanding Hooking in Venddor IO

Hooking is akin to placing a digital anchor in a codebase, letting you extend or modify functionalities without disrupting the core process. Think of it as a designated spot where you can introduce custom or additional behaviours.

For instance, with hooking, you can design a module for Venddor IO, attaching it at a specific code juncture, ensuring seamless integration without touching the core operations. For a hands-on example, check the Advanced Module Tutorial.

Venddor IO incorporates two primary hook types:

• Within the source code, known as PHP hooks.
• Within design layouts or templates, termed as TPL hooks.

Dive deeper into the specifics of these hooks below:

1. PHP Hooks

These are entry points within the Venddor IO's core PHP code, letting modules introduce, modify, or augment functionalities. They offer a way to interact with data, processes, or even modify how certain core functionalities respond.

PHP Hooks in Venddor IO

In programming, PHP hooks offer specific anchor points in the code, enabling extensions or modules to interact with the main software without changing its core functions. Let's dive into how PHP hooks using the Hook base tool work in Venddor IO.

What is a PHP Hook?

A PHP hook in Venddor IO is a predefined point in the software's core code that allows a module to intervene or modify a process. It's initiated by a distinct function:

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

One function can have multiple hooks, making it a versatile tool. You can check out all available PHP hooks for Venddor IO on our official website's Hook base tool.

When are PHP Hooks Used?

Hooks are essential when an add-on needs to execute specific actions amidst the main code flow. With the hook's name, a module can pause the main code execution, perform its operations, and then continue the main flow. Any variables defined within this hook can be accessed by the add-on.

For a hook call within a module, a function is defined that includes the module's name and the hook's name:

fn_gift_certificates_get_gift_certificate_info($_certificate, $certificate, $type)

Utilizing a PHP Hook in Your Module:

1. Declaration: First, mention the hook you want to use in your module's init.php file:

   ...
   fn_register_hooks(
       'get_category_data_pre'
   );
   ...

2. Action Function: Now, in your module's func.php file, define a function that carries out actions when the hook is activated:

   ?php
   if ( !defined('AREA') ) { die('Access denied'); }
   function fn_my_module_get_category_data_pre(&$category_id, &$field_list, &$get_main_pair, &$skip_company_condition, &$lang_code)
   {
       ...
   }
   ?>

This ensures that your module is alert to the hook, and Venddor IO knows that it should pass control to your module when the hook triggers.

Expanding One Module with Another:

For times when one module needs features from another module, hooks can be used for integration. For instance, if the "News and Emails" module requires some functionalities from the "SEO" module, instead of intertwining their functionalities, you can use a hook:

design/backend/templates/addons/news_and_emails/addons/seo/hooks/

Here, the SEO functionalities are transferred to a hook, ensuring modularity. Working principles remain similar to regular hooks. But hooks within modules are activated only when the respective module is enabled.

To register the PHP hooks:

fn_register_hooks( array('get_news_data', '', 'seo') )

In this instance, the function managing the hook would be named fn_seo_get_news_data and it would activate when the SEO module is on.

All these processes happen within the "News and Emails" module in the context of Venddor IO.

2. TPL Hooks

Akin to PHP hooks, TPL hooks are designated spots within Venddor IO's template or design files. They allow modules to enhance, change, or introduce new design elements or visual functionalities without disturbing the core template structure.

TPL Hooks in Venddor IO

TPL hooks in Venddor IO relate to the template part of the platform. They are used to modify or extend the look and feel without altering the main template files.

Understanding TPL Hooks

TPL hooks are segments within templates, surrounded by tags like:

{hook name="section:hook_name"}
...
{/hook}

These sections can be augmented or entirely customized by any module.

TPL Hook in Action:

Consider a template from the design/backend/templates/views/order_management/components/totals.tpl in Venddor IO:

{hook name="order_management:product_info"}
    {if $cp.product_code}
        <p>{$lang.sku}: {$cp.product_code}</p>
    {/if}
{/hook}

When to Use TPL Hooks?

These are essentially used when there's a need to introduce extra data into an existing template. Suppose a module gathers specific information to be displayed as a distinct block in the store's admin panel. Such a block can be seamlessly integrated using a TPL hook.

Implementing TPL Hooks:

Unlike their PHP counterparts, TPL hooks don't require explicit declarations. Instead, following a systematic naming convention and placing files accurately is sufficient.

Overriding a Template:

Venddor IO offers the capability to entirely override a template within a module. Here's how:

1. Navigate to either design/backend/templates/addons/[addon id] (for admin area) or design/themes/[theme name]/templates/addons/[addon id] (for customer side) and create a folder named overrides.
2. Inside the overrides directory, craft a template adhering to the path it originally had in relation to the templates directory.

This modularity in Venddor IO, aided by TPL hooks, ensures that customizations are seamlessly integrated, enhancing flexibility without risking core functionalities.

For an in-depth understanding, refer to our section on hooking basics.

Should you feel the need for a new hook or have suggestions, please put forth your request on our developer forum or join the developer chat. Remember, while we appreciate suggestions, any new hook might be aligned with Venddor IO's standards before integration.

Check out Venddor IO's comprehensive hooks repository at [Venddor IO API link].

General Guidance

1. Hooks help developers to enhance functions. Therefore, including as many parameters as possible in hooks is advisable.
2. The hook's name should mirror the function's name.
3. No prefixes. Only suffixes are permissible.
4. For complex functions with multiple hooks, name them accordingly:

Function:

get_cart_product_data

Hook:

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

5. When specifying the hook's parameters, the function's parameters should be prioritized. The only exception is SQL hooks where everything required gets encompassed in the params variable.
6. Class hooks should integrate the calling class's name in their moniker.
7. Class hooks should always pass the class instance as their primary 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);
        …

Venddor IO Hook Format Guidelines

Understanding hooks is crucial when working with Venddor IO. Here's a simplified guide to the comment formats of hooks:

1. PHP Hooks and Functions

• Format inspiration is drawn from PHPDocumentor, which ensures uniformity across functions.
• Use the Doxygen program for documentation.
• Starting your comment? Begin with a capital letter and don't end with a period.
• Describe function actions using verbs in the third-person singular. E.g., "Retrieves user data".

<?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);
?>

• For emphasis, italicise names, values, file paths, etc. in the comments. Like: Function foo is found in foo/bar/functions and uses the parameter $bar.
• Reference a function as class::function. If no class is involved, just ::function.

/** ...
*      - period - If set, fetches pages by time period. ::fn_create_periods
* ...
*/

• Always clarify the purpose of a variable in the function.

/**
 * Processes shopping cart data after all calculations.
 *
 * @param array $cart              Cart details.
 * ...
 */
fn_set_hook('calculate_cart', ... );

2. TPL Hooks

When dealing with Smarty-templates:

• Distinguish between usual comments and hook comments. Use two asterisks (**) for the opening tag of the hook comment and one asterisk (*) for the closing tag.

{** Dynamic menu entry for navigation *}
{hook name="index:dynamic_menu_item"}
...
{/hook}

3. JS Hooks

Here's the step-by-step approach:

• Initiate with a description of the event.
• Next, declare your variables.
• Finally, invoke the event.

/**
 * 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]);

For all parameters, the comment should first specify the variable type, followed by its purpose.

This guidance aims to make Venddor IO's hooks more approachable and manageable for developers, whether you're a seasoned Module developer or just starting out.