Add-on Blocks

Purpose of Use

Blocks are a recommended alternative to using modifiers. The purpose of using blocks is to conveniently integrate HTML add-on blocks into theme template files or module templates using special tags (comments).
A tag is a comment that contains the necessary parameters of the template's local variables in the form of a JSON string for the add-on block, identified by the add-on name and the key of the block, as follows:

<!-- [extension_p0bc5sa_block1{"param1":"<?= $id ?>"}] -->

An example of usage might be to display the online status of a user on pages that display user information.

Add-on Block Settings

In the add-on settings, blocks will be available in the "Instructions / Blocks" section. Blocks will be added as a numbered list, containing information about the block name, its description, the code to be inserted, and instructions on where in the template file this code is recommended to be added. Template files where blocks are found will be marked in green. There is also an "Update" button to check for the presence of comments (tags) in the required template files.

Block Development Example

Blocks are declared in the init() method of the add-on immediately after adding settings and calling the $this->configSettings() method by calling the add-on method blockAdd. Then, the block parameters are set by calling helper methods of the returned object of the ExtensionBlock class. An example of declaring a block:

$this->blockAdd('block1', function($params){
    // Handler function that creates the HTML block
    return 'HTML';
})
// The block name can be used to provide a brief description of the location on the page
// For example: User profile, user block.
->title($this->langAdmin('Block title'))
// Specify the application template file in which to add the block code
// If there are multiple files, there could be multiple such calls
->template('/modules/users/tpl/def/profile.php')
// Specify additional block parameters (accessible as variables in the template file)
->param('param1', '?$id')
->param('param2', '?$user_id')
// Describe the exact location in the file
// Markdown markup is supported, including single and multi-line code samples
->integration($this->langAdmin('Detailed description of the integration location ...'))
// Specify the block description
// Markdown markup is also supported
->description($this->langAdmin('Block description'));

$this->blockAdd('block2', array($this, 'blockMethod')) // Add-on method
 ->title($this->langAdmin('Block title #2'))
 ->template('/modules/shops/tpl/def/view.php')
 ->param('shop', '?$shop_id')
 ->description($this->langAdmin('Block description #2'));

Let's provide a detailed description of the arguments of the blockAdd('block_key', callable $callback) method:

• block_key - ID of the block (a unique key within the add-on), allowed characters: a-z,A-Z,0-9,-,_
• callback - a handler function responsible for rendering the block, can be declared directly in the block itself or as a public method of the add-on.
  Here is an example of such a method:

/**
 * An example method that generates the HTML code of the add-on block
 * @param array $params block parameters (specified when declaring the block): 'param1', 'param2', ...
 * @return string HTML (or an empty string)
 */
public function blockMethod($params)
{
    // Generate an HTML template by including the add-on template file /tpl/template.php
    return $this->view($params, 'template');
}

The $params method parameter is the parameters passed in the tag as a JSON string. In the insertion points, there are usually data in the form of local variables, which are necessary for rendering the block on the page. The tag is inserted directly into the template file declared during the block initialization.

To avoid an error in case the variable is missing in the template file, a special syntax is used in the parameter declaration, specifically a ? sign before its name:

param('shop', '?$shop_id')

Thus, in the resulting code of the tag, the variable will have the following format:

<!-- [extension_p0bc5sa_block1{"shop":"<?= isset($shop_id) ? $shop_id : '' ?>"}] -->