The Main Schema—blocks.php in Venddor IO

Multilingual Support

The multilanguage parameter addresses whether a block requires language adaptability. If set to true, the block's content will be influenced by the current language, ensuring that users receive content in their preferred or set language.

Delving into Block Type Parameters

Settings (array)

This parameter holds the configurations of a block which can be adjusted on the block editing interface accessible through Design → Layouts → Block options.

Each block setting is a duo of a key, representing the identifier, and a value, which is an array detailing the nature and behaviour of the said setting.
The key necessitates a matching language variable. This helps in naming the setting when you're on the block editing screen.

A visual representation of a block's settings could look something like:

'settings' => array(
        'ip_address' => array(
            'type' => 'text',
            'default_value' => '127.0.0.1',
        ),
        ...
),

In this example, the setting ip_address is of the text type and its default value is set to '127.0.0.1'.

Block Setting Parameters Explained

Within the Venddor IO platform, block settings are highly customizable. These are the possible configurations:

Type (string)

Defines the setting's input method. Options include:

checkbox: Toggling checkbox
input: A basic input field
selectbox: Dropdown list
input_long: Extended input field
multiple_checkboxes: Multiple selection checkboxes
text: Rich text editor
simple_text: Plain text box
picker: Special input selector
template: Template display instead of standard setting
enum: A list of items, mainly used in the content area

Other Parameters

required (bool): Specifies if the field is mandatory
option_name (string): Specifies the associated language variable. If not set, the setting's identifier is used
default_value: Sets a default value for the setting
values (array): Lists potential options for dropdowns or multiple checkboxes. These can either be actual names or language variables, dictated by the no_lang parameter
no_lang (bool): Decides if values are shown as entered (true) or as language variables (false)
values_settings (array): For selectbox types, this allows nested options based on the parent's selected value
picker: Indicates the template path for pickers
picker_params: Customizes picker parameters
remove_indent (bool): Removes the right indent in the admin panel if set to true
template: Indicates the template path. Used for template type

Block Templates Explained

Templates in Venddor IO provide a structured representation for block displays. Here's a breakdown of the templates' configuration:

Templates (array)

Contains the list of potential templates. Each template is described as:

'path_to_template' => array (
  'settings' => 'List of specific settings',
  'fillings' => 'Available fillings for the template',
  'params' => 'Parameters for the block element retrieval function',
  'bulk_modifier' => 'A function affecting all block elements before display'
),

When Venddor IO generates a schema, the information from the block's template parameter incorporates settings from templates.php.

The template parameter in the block schema can be defined in several ways:

Direct paths to templates with all associated settings
Only paths to templates; further details are in templates.php
The directory path having the templates; parameters are in templates.php
A function's name returning template lists; settings are either in templates.php or the function itself

Wrappers Configuration

The wrappers segment within Venddor IO encompasses either an array list of wrappers or the directory path where these wrappers are stored. Distinctly, wrappers don't come with any additional configurable parameters.

Block Content Configuration

Blocks within Venddor IO can be filled with several variables, which are later passed to the respective template. Take this example:

'test_block' => array (
        'content' => array(
            'some_value' => array(
                'type' => 'text',
            )
        )
    )

Here, the admin panel displays a text input for block settings. In the user interface, this block's template will contain the {$some_value} variable, which admins can set.

Content can encompass settings (explained above), enumerations, or functions:

Settings: These are user-defined in the admin panel and relayed to the template
Enumeration (enum): Use this setting type to devise lists of items with variable fillings. For example, a list of products or categories. It can have different fillings, with manual inputs requiring picker settings, or non-manual fillings passing parameters to the item generation function
Function: If a function type is chosen for a content element, the value for this variable is determined by the function's return

Cache Configuration

The cache segment defines caching policies for a block. Here's a breakdown of possibilities:

false: The block won't utilize caching
true: The block will adhere to Venddor IO's overarching block caching stipulations
array: This is an array detailing specific block caching settings. These parameters then get appended to the global block caching attributes

Cache Configuration Parameters

Update Handlers

The update_handlers parameter pertains to a list of database tables (omitting prefixes). Any changes to these tables, whether structural or data-wise, will refresh the block's cache. For instance, if a block presents a list of users, it would logically designate users and user_profiles as its update_handlers.

Key Generation for Cache Entries

The cache entry's key generation can incorporate serialized values of specific block parameters. To list necessary parameters, one can use:

Request Handlers: This parameter comprises a list of HTTP-request parameters. If parameters like category_id and sort_by are mentioned, the cache key might integrate a segment like ...|category_id=10|sort_by=price.
Session Handlers: This parameter lists variable names within a user's session. Different cache entries could be used based on various combinations of these session values.
Cookie Handlers: It represents the parameter names within a user's cookies.
Auth Handlers: It focuses on keys within the $_SESSION['auth'] array.

Special notations like Dot-syntax can be used for nested elements, and * can be employed to select all values. Moreover, comparison operators such as gt, eq, in, ncont, etc., can be applied to fine-tune the conditions under which values are chosen.

Callable Handlers

The callable_handlers parameter encapsulates a list of parameters and their associated functions. The function's outcome serves as the value for the parameter when caching. For instance, using:

'callable_handlers' => array(
    'currency' => array('fn_get_secondary_currency'),
),

will append a segment like |currency=RUB to the cache key.

The function invoked is defined as: array(Callable[, Args]).

Where Callable represents a function or any expression that can be executed using call_user_func(). The Args parameter, though optional, lists arguments that the function will utilize. If an argument starts with $, it's perceived as a variable name, specifically if it's a global variable or belongs to $block_schema and $block_data.

Disabling Cache Logic

The disable_cache_when parameter details conditions under which block caching is disabled. While parameters like request_handlers and auth_handlers can be the same as in the cache settings, their function differs:

In the cache setting, values such as $_REQUEST['sort_by'] and $_REQUEST['items_per_page'] would be serialized and included in the block's cache key. But, with disable_cache_when, if these parameters exist in $_REQUEST, the block won't cache. Similarly, if $auth['user_id'] is greater than 0, the block will refrain from caching.
The callable_handlers within disable_cache_when also deviates in behavior. If the associated function returns true, caching is bypassed.

Cache Invalidation Logic

regenerate_cache_when provides rules for cache invalidation of the block and operates similarly to disable_cache_when.

Cache Overrides by Dispatch

cache_overrides_by_dispatch allows for setting distinct cache parameters based on dispatch. If a particular dispatch is defined in this setting, cache specifics for that dispatch will override any general block caching settings. This is useful for having fine-grained cache behaviors for different site areas or functionalities.

Block Visibility Constraints

With hide_on_locations, developers can pinpoint dispatches where a block shouldn't appear. For instance, to prevent a block from appearing on the shopping cart page, one would use hide_on_locations with a value like checkout.cart.

Single Block Constraint

The single_for_location boolean parameter ensures that a specific dispatch only contains one instance of the block type. By default, it's set to false, meaning multiple block instances can be placed on a dispatch.