Основная схема — 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.