Modular Scripts

A modular script is the primary building block of the Melbis platform. Each module solves one isolated task: builds a catalog menu, renders a product card, processes a cart, or executes a background task. The entire site is assembled from these blocks.

Working with Modules in the IDE

All modules are displayed in the file tree under “Scripts, Templates” in the development environment. Modular scripts are grouped by company and group — this makes navigation convenient even in large projects with dozens of modules.

When a module is opened in the editor, its interface consists of three parts:

• Above the editor — two fields: the module description and the input parameter declaration. This data is used by the IDE for autocompletion when editing templates.
• Code editor — the module’s PHP code.
• Right panel — module parameters: connected libraries, database table list, cache settings, entry point and lazy loading flags.

PHP File Structure

A typical module looks like this:

<?php
/**
 * Function MELBIS_CATALOGE
 **/
function MELBIS_CATALOGE($mVars)
{
    // Create a template engine pointer
    $tpl = MELBIS()->TplCreate();

    // Retrieve data from the database
    $command = "SELECT id, name
                  FROM {DBNICK}_topic
                 WHERE no_visible = 0
              ORDER BY absindex";
    $menu = MELBIS()->SqlSelect(__LINE__, $command);

    // Pass data to the template engine
    MELBIS()->TplAssign($tpl, 'MENU', $menu);

    // Return the result
    return MELBIS()->TplFinal($tpl, 'main');
}

The main function is the only required part of a module. Its name matches the filename in uppercase. The parser calls exactly this function, passing the input parameters as the $mVars array.

The module may contain any number of helper functions — they are named with the main function’s name as a prefix (see the “Naming Conventions” section).

Module Workflow

Most modules follow the same pattern:

1. Create a template engine pointer:

$tpl = MELBIS()->TplCreate();

2. Retrieve data from the database using MELBIS()->Sql* methods:

// Return a flat array of a single record
$topic = MELBIS()->SqlSelectFlat(__LINE__, $command, $params);

// Return an array of records
$menu = MELBIS()->SqlSelect(__LINE__, $command, $params);

// Return an array indexed by key
$image = MELBIS()->SqlSelectEnumFlat(__LINE__, $command, 'id', $id, $params);

// Return a page of records and the total row count
$goods = MELBIS()->SqlSelectLimit(__LINE__, $command, $offset, $limit, $params);

Pagination, data writing, transactions, and table locking are described in the “Working with the Database” section.

3. Pass data to the template engine using MELBIS()->Tpl* methods:

// Pass a single value
MELBIS()->TplAssign($tpl, 'TITLE', $topic['name']);

// Pass an entire array
MELBIS()->TplAssign($tpl, $topic);

// Parse a template and place the result into a variable
MELBIS()->TplParse($tpl, 'CONTENT', 'page_index');

4. Return the result — the final parsing of the main template:

return MELBIS()->TplFinal($tpl, 'main');

The full list of Sql* and Tpl* methods is described in the corresponding documentation sections.

Input Parameters

Parameters are passed to the module through the $mVars array. How the array is formed depends on how the module was called.

If the module is called as an entry point (via MELBIS()->Run()), parameters are passed explicitly from the root script:

// In index.php:
$entry_param = [serialize($_GET), serialize($_POST)];
MELBIS()->Run('melbis_base_page', $entry_param);

The module declares get: serial, post: serial — and inside the function:

$id = (int) ( $mVars['get']['topic_id'] ?? 0 );

If the module is called from a template, parameters are passed directly in the call tag — positionally, separated by commas:

{MELBIS:melbis_store_image([ID],kDefault)}
{MELBIS:melbis_store_random(8)}
{MELBIS:melbis_cataloge_sub(,,[ID])}

Variable values are substituted in square brackets — [ID], not {ID}. Arguments are parsed by comma and by the closing parenthesis, so any “dirty” value — a name containing a comma, text with a quote, a serialized array — when substituted via {ID} will break the argument list and the module will receive garbage. Square brackets run the value through urlencode, and the parser on the receiving end performs a matching urldecode, so the content arrives intact in any form. This rule also applies to variables of the current loop row:

{#GOODS}
    {MELBIS:melbis_store_card([VAR:LANG],[ID],[PRIOR])}
{GOODS#}

Literals (kDefault, 8) are written as-is — they are not variables, there is nothing to encode.

The module must declare the corresponding parameters, for example id: int, key: str, and inside the function:

$id  = $mVars['id'];
$key = $mVars['key'];

Parameter types are declared in the field above the editor in the IDE:

Ways to Call a Module

From a template — the primary and safe method. The parser encounters a {MELBIS:module_name(...)} tag in an HTML template, runs the module, and substitutes its HTML result in place of the tag. Available for any module without restrictions.

As an entry point — a call via MELBIS()->Run() in the root script. The URL can be anything — the key criterion is the call via Run. To allow such a call, the “Entry Point Module” option must be enabled in the IDE’s right panel. Without this flag, the parser will refuse to run the module directly. Entry points are typically page router modules, form handlers, and cron tasks.

Module Nesting

The HTML fragment returned by a module may contain call tags for other modules — to any depth: the parser processes the entire chain on its own. A breakdown using the demo store page as an example is provided in the “Storefront Architecture” section.

Libraries and Tables

The right panel of the IDE displays all available library modules (inc). To connect a library, simply check the checkbox — the parser will automatically load it before running the current module, making all its functions available.

The “Tables” tab displays two lists: - Left — the database tables directly accessed by the current module. The developer marks the required tables. - Right — tables from connected libraries (informational only, cannot be changed).

This data is used by the caching system: when data in a tracked table changes, the platform knows which modules’ caches need to be invalidated. See the “Caching” section for details.

Utility Methods

In addition to working with templates and the database, a module occasionally needs platform utility calls — the current module’s name, calling its own function, the path to an uploaded file. These are covered in the “Utility Methods” section.