Основная схема — blocks.php

Доступные для использования типы блоков описываются в таком формате:

$schema = array(
    // Уникальный идентификатор типа блока => массив с параметрами
    'unique_block_type' => array(
        'settings' => array(),
        'templates' => array(),
        'cache' => array(),
        ...
    ),
);

Параметры типа блоков

settings (array)

В массиве settings хранятся настройки, которые будут задаваться на странице редактирования блока в панели администрирования на вкладке “Настройки блока”.

Список настроек представляет собой набор пар типа ключ-значение, где ключ — идентификатор настройки, а значение — массив, описывающий тип и поведение настройки. Соответственно идентификатору настройки должна быть определена языковая переменная, которая определяет текст названия этой настройки на странице редактирования блока.

Перечисление настроек блока выглядит так:

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

Доступные параметры

  • type (string) — один из типов настройки:

    • checkbox — галочка;
    • input — поле ввода;
    • selectbox — поле <select>;
    • input_long — поле ввода с классом input-text-long;
    • multiple_checkboxes — список галочек;
    • text — поле ввода текса типа WYSIWYG;
    • simple_text — обычное поле ввода текста без WYSIWYG;
    • picker — пикер;
    • template — шаблон. Вместо настройки будет отображаться тот шаблон, который указан в параметре template;
    • enum — перечисление объектов. Используется только в секции content;
  • required (bool) — если истинно, то в настройках блока поле будет обязательно для заполнения;

  • option_name (string) — имя языковой переменной для названия насткройки. Если не задано, то в качестве него будет использоваться идентификатор настройки;

  • default_value (mixed) — значение по-умолчанию;

  • values (array) — список возможных вариантов настройки для настроек типа selectbox, multiple_checkboxes.

    Это массив пар key => value, где key - значение настройки, сохраняемое в БД, а value - название языковой переменной для названия варианта, или непосредственно текст названия варианта при истинном no_lang;

  • no_lang (bool) — если истинно, то при отображении в админке у списка вариантов значение варианта будет выводится как есть, иначе - интерпретироваться как языковая переменная;

  • values_settings (array) — в этом параметре задаётся список вариантов и дополнительные настройки, которые будут появлятся при выборе определённых вариантов родительского списка. Работает только с настройкой типа selectbox.

    Пример использования:

    'settings' => array(
        'foo' => array(
            'type' => 'selectbox',
            'values' => array (
                'products' => 'products',
            ),
            'values_settings' => array(
                'products' => array(
                    'settings' => array(
                        'rss_sort_by' => array(
                            'type' => 'selectbox',
                            'values' => array(
                                'A' => 'rss_created',
                                'U' => 'rss_updated'
                            ),
                        ),
                        'rss_display_sku' => array (
                            'type' => 'checkbox',
                        ),
                    )
                )
            )
        )
    );
    
  • picker (string) — путь до шаблона пикера. Используется только с типом настройки picker;

  • picker_params (array) — настройки пикерa. Используется только с типом настройки picker;

  • remove_indent (bool) — если истинно, то при отображении в админке у настройки не будет отступа справа;

  • template (string) — путь к шаблону. Применятеся только с типом настройки template.

templates (array)

В массиве templates содержится список шаблонов:

'путь_к_шаблону' => array (
    'settings' => 'Список настроек (см. ниже)',
    'fillings' => 'Массив из типов заполнения, которые доступны для этого шаблона (все остальные типы заполнения будут автоматически исключены из списка)',
    'params' => 'Массив параметров, которые будут переданы в функцию получения элементов блока',
    'bulk_modifier' => 'Групповой модификатор. Функция которая применится к элементам блока перед выводом'
),

При генерации схемы всё, что есть в параметре template в схеме блоков, будет объединено с параметрами, заданными в схеме templates.php. Ключём является путь к шаблону.

Соответственно по ключу template в схеме блоков может быть:

А. Список путей к шаблонам с непосредственно полным переченем параметров, в таком случае не потребуется ничего писать в templates.php.
Б. Список путей к шаблонам, а все параметры по соотвествующим ключам указаны в templates.php.
В. Путь к папке с шаблонами, а все параметры по соотвествующим ключам указаны в templates.php.
Г. Название функции которая возвращает список шаблонов, а все параметры по соотвествующим ключам указаны в templates.php или так же возвращаются функцией.

wrappers (array)

В данном параметре по аналогии с templates может быть либо список врапперов, либо путь к папке с ними. Дополнительные настройки у них отсутствуют.

content (array)

Блок может содержать произвольное колличество переменных которые затем передадутся в шаблон. Например, имея такой блок:

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

В настроках блока в панели администратора появится поле ввода, в которое можно ввести значение. При отображении блока на витрине в шаблоне этого блока будет доступна переменная {$some_value}, значение которой задано в админке.

В качестве элемента контента может быть любая настройка (см. пункт settings), специальный тип “перечисление” (enum), функция.

С настройками всё просто: что пользователь сохранит в панели администратора, то и пойдёт в шаблон.

Тип “перечисление” (enum) нужен для того, чтобы определять списки элементов с различными типами заполнения (fililng), например список продуктов или категорий.

Параметры типа enum:

'имя_переменной' => array (
    'type' => 'enum',
    'object' => 'Название динамического объекта в схеме.'
    'items_function' => 'Функция генерации элементов'
    'fillings' => array ( // типы заполнения.
        'manually' => array ( // Ручной тип. Требует наличия параметров пикера.
            'picker' => 'pickers/companies/picker.tpl',
            'picker_params' => array (
                'multiple' => true,
            ),
        ),
        'some_another_filling' => array (
            'params' => array (

            ),
        ),
    ),
),

Для неручного типа заполнения можно задать секцию params, в которой будет список тех параметров, который в итоге будет передан в функцию генерации элементов. Также для типа заполнения можно задать список настроек по ключу settings, аналогично шаблонам или самим блокам.

Если в качестве элемента контента используется функция, то значение этой переменной будет равно результату, который вернёт эта функция. Формат определения таков:

'имя_переменной' => array (
    'type' => 'function',
    'function' => array('fn_get_languages'[, 'param1'][, 'param2'][..]),
),

cache (bool/array)

Общие настройки кеширования блока. Если параметр не указан (и для текущего dispatch нету записи в секции cache_overrides_by_dispatch), либо установлен в false, блок не будет кешироваться.

Возможные значения

  • false — блок не будет кешироваться;
  • true — блок будет кешироваться согласно глобальным настройкам кеширования блоков, взятыми из схемы block_cache_properties;
  • array — массив с настройками кеширования блока. Параметры, описанные в этом массиве, будут объединены с глобальными настройками кеширования блоков из схемы block_cache_properties.

Доступные параметры

Доступны несколько параметров, с помощью которых можно настроить то, как будет кешироваться блок. Все параметры необязательны, если не указано иное.

  • update_handlers (array) — список таблиц БД (без префиксов), при изменении которых кеш блока будет инвалидирован. Под изменением подразумевается модификация таблицы (добавление, изменение и удаление записей; изменение структуры), с использованием инструментов CS-Cart (функции и методы для работы с БД). Например, для блока, выводящего список пользователей имеет смысл перечислить таблицы users и user_profiles.

При генерации ключа записи в кеше для этого блока могут быть использованы сериализованные значения различных переменных и параметров. Это поведение настраивается перечислением названий требуемых параметров в нижеописанных массивах:

  • request_handlers (array) — список названий параметров HTTP-запроса (ключей в массиве $_REQUEST). Например, при указании параметров category_id и sort_by к ключу будет добавлена строка в виде ...|category_id=10|sort_by=price;, что позволяет использовать разные записи в кеше для каждой из комбинаций значений указанных параметров;
  • session_handlers (array) — список названий переменных в сессии пользователя (ключей в массиве $_SESSION). Например, при указании параметра items_per_page запись в кеше будет отдельной для каждого значения $_SESSION['items_per_page'];
  • cookie_handlers (array) — список названий параметров в куках пользователя (ключей в массиве, возвращаемом функцией fn_get_session_data());
  • auth_handlers (array) — список ключей в массиве $_SESSION['auth'];

Для request_handlers, session_handlers, cookie_handlers и auth_handlers существуют специальные формы записи значений:

  • Dot-syntax для доступа ко вложенным элементам. Запись вида 'session_handlers' => array('auth.user_id') выберет значение $_SESSION['auth']['user_id'];

  • Выбор всех значений с помощью *. Запись вида 'session_handlers' => array('*') выберет все значения в массиве $_SESSION. Это означает, что при генерации ключа кеша будет использован сериализованый массив $_SESSION целиком.

  • Операторы сравнения. Запись вида:

    'auth_handlers' => array(
        'user_id' => array('gt', 0),
    ),
    

    выберет значение (и добавит к ключу кеша) $_SESSION['auth']['user_id'] только в случае, если оно будет больше нуля.

    Доступные операторы сравнения:

    • gt - больше
    • eq - равно
    • neq - не равно
    • lte - меньше или равно
    • lt - меньше
    • gte - больше или равно
    • cont - вхождение подстроки
    • ncont - невхождение подстроки
    • in - содержится в массиве
    • nin - не содержится в массиве

Кроме того, для большей гибкости при генерации ключа кеша, он может содержать результат вызова функций и методов:

  • callable_handlers (array) — список названий параметров и соответствующих им функций, результат вызова которых будет использован в качестве значений этих параметров. Например, запись вида:

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

    добавит к ключу кеша строку: |currency=RUB.

    Формат описания функции, которую нужно вызвать, выглядит так: array(Callable[, Args]), где Callable это строка с именем функции или любое другое выражение, которое можно вызвать с помощью call_user_func() (http://php.net/manual/ru/language.types.callable.php), а Args - необязательный массив с перечислением аргументов, которые должны быть переданы в функцию. Если аргумент - это строка, начинающаяся с символа $, то она будет интерпретирована как название переменной, в случае если это глобальная переменная ($_REQUEST, ...) или одна из переменных $block_schema и $block_data.

    • $block_schema — содержит схему блока
    • $block_data — содержит данные о блоке из БД

    Пример:

    'callable_handlers' => array(
        'layout' => array('fn_get_products_layout', array('$_REQUEST')),
        'settings' => array('fn_foo_addon_cache_key_handlers', array('$block_data')),
    ),
    

    В этом случае к ключу записи в кеше будет добавлены результаты вызова этих функций.

  • disable_cache_when (array) — позволяет описывать правила отключения кеша данного блока. Может принимать параметры request_handlers, session_handlers, cookie_handlers, auth_handlers и callable_handlers в том же формате, что и сама секция настроек кеша cache, хотя работают они по-другому.

    Пример:

    'cache' => array(
        'request_handlers' => array('sort_by', 'items_per_page'),
        'auth_handlers' => array(
            'user_id' => array('gt', 0)
        ),
        'disable_cache_when' => array(
            'request_handlers' => array('sort_by', 'items_per_page'),
            'auth_handlers' => array(
                'user_id' => array('gt', 0)
            ),
        ),
    ),
    

    Рассмотрим на примере, как работают эти параметры в сравнении с секцией cache:

    • в секции cache: значения $_REQUEST['sort_by'] и $_REQUEST['items_per_page'] будут сериализованы и добавлены к ключу кеша блока. Значение $auth['user_id'] будет сериализовано и добавлено к ключу, только если оно больше нуля;

    • в секции cache.disable_cache_when: если массив $_REQUEST содержит хотя бы один из ключей: sort_by или items_per_page, то блок не будет кешироваться. Если массив $auth содержит ключ user_id, и значение, соответствующее этому ключу, больше нуля, то блок тоже не будет кешироваться.

      Поведение параметра callable_handlers тоже отличается в секции cache.disable_cache_when: если функция возвращает true, блок не будет кешироваться, и наоборот.

  • regenerate_cache_when (array) — позволяет описывать правила инвалидации кеша данного блока. Схема работы идентична параметру cache.disable_cache_when.

  • cache_overrides_by_dispatch (array) - позволяет описывать параметры работы кеша блока для каждого dispatch по отдельности в формате array('dispatch' => cache_params, ...), где cache_params - массив параметров кеширования для конкретного dispatch.

    Если в этом массиве есть запись для текущего dispatch, то параметры кеширования блока будут браться именно из неё, а не из общих настроек кеша блока в секции cache. Каждый вложенный массив параметров кеширования для отдельного dispatch может принимать все те же параметры, что принимает секция общих настроек кеша cache.

    Пример:

    'cache' => array(
        // Эти параметры кеширования будут использованы везде, кроме страницы категории
        'update_handlers' => array('users'),
    ),
    'cache_overrides_by_dispatch' => array(
        // Эти параметры кеширования будут использованы на странице категории
        'categories.view' => array(
            'update_handlers' => array('users', 'products'),
        ),
    ),
    
  • hide_on_locations (array) - список dispatch, на которых блок не может быть использован. Например, следующий код актуален, если необходимо запретить возможность добавлять блок на странице корзины:

    'hide_on_locations' => array('checkout.cart'),
    
  • single_for_location (bool) - если установлено в true, то на каждом dispatch блок может присутствовать только в единственном числе. Ситуация, когда параметр не указан, трактуется как значение false.

  • multilanguage (bool) - необходима ли возможность мультиязычности содержимого блока. Если установлено в true, содержимое блока будет разделено по языкам. Ситуация, когда параметр не указан, трактуется как значение false.