2.4. Переменная окружения

Переменная окружения представляет из себя обычную переменную из запроса к серверу с названием "env". Само название данной переменной задано в константе ENV_VAR_NAME. Она была введена для того, чтобы реализовать возможность компактной передачи большого количества переменных между страницами сайта. В большинстве случаев в ней будет содержаться информация, при помощи которой можно будет загрузить объект из базы данных на странице (т.е. префикс и ID), но это совсем не обязательно.

Если в конфигурационном файле переданного префикса разрешена автоматическая загрузка, то при первом обращении к объекту префикс которого передан и при наличии его ID в запросе к серверу он будет автоматически загружен.

1 Структура
2 Получение данных из переменной окружения
3 Построение ссылок
- 3.1 Параметры специального назначения
- 3.2 Использование переданных параметров
4 Запись данных
- 4.1 Запись данных из шаблонов
- 4.2 Запись данных из событий
5 Системные переменные окружения

Структура

Значение, содержащееся в переменной окружения имеет следующую структуру:

<session_id>-<template>:m<main_prefix_variables>[:<prefix[.special]>-<value1>[-<value2>...[-<valueN>]]]

Как видно из приведённой выше схемы в переменной окружения всегда присутствуют следующие компоненты:

session_id - идентификатор сессии (“SessionKey” колонка) пользователя;
template - путь к шаблону, результат обработки которого будет показан на экране;
main_prefix_variables - ряд системных переменных, среди которых в том числе присутствуют ID темы и ID языка, которые будут использованы для вывода информации на странице (об этом позже).

Также в ней могут присутствовать данные неограниченного количества префиксов. Наборы данных разных префиксов друг от друга отделяются двоеточием (":"). Первое значение внутри каждого набора - префикс конфигурационного файла. Если необходимо, то можно указать и "special" следующим образом: "prefix.special".

Далее следует список параметров префикса, которые могут передаваться через переменную окружения, разделённых при помощи дефиса ("-"). Названия параметров, а также их порядок в пределах одного набора префикса задаётся в ключе QueryString его конфигурационного файла. Например:

'QueryString' => Array(
    1 => 'id',
    2 => 'Page',
    3 => 'event',
    4 => 'mode',
),

Пиведённое выше значение ключа QueryString является стандартным для большинства префиксов и поэтому будет описано ниже.

Название ключа	Описание

Название ключа	Описание
`id`	ID объекта (`Item`), которое может быть использовано для автоматической загрузки объекта.
`Page`	Номер страницы списка объектов (`List`).
`event`	Событие, которое требуется выполнить у данного префикса.
`mode`	Режим редактирования записей. Возможны 3 вида значений: "" - данные будут редактироваться в оригинальной таблице; "`t`" - данные будут редактироваться во временной таблице в основном окне; "`t<wid>`" - данные будут редактироваться во временной таблице, которая была создана при открытии всплывающего окна (`popup`) с идентификатором окна (`window id`) равным "`<wid>`".

Значения данного массива чувствительны к регистру (case-sensitive).

Получение данных из переменной окружения

Если в ссылке, используемой для посещения сайта находиться переменная окружения, то её значение будет автоматически обработано системой. Доступ напрямую к значению переменной окружения не рекомендуется. В результате обработки для каждого из переданных префиксов будут искуственно созданы переменные вида "prefix[.special]_VariableName". Будет создано по одной переменной для каждого значения в массиве QueryString у переданного префикса. Созданные таким образом переменные можно будет в последствии использовать также, как и любые другие переменные, переданные в запросе к серверу (т.е. при помощи метода Application::GetVar). Это будет наглядно показано на ниже приведённом примере.

Переменные, заданные в конфигурационном файле:

'Prefix' => 'sample-prefix',
'QueryString' => Array (
	1 => 'sample_variable',
	2 => 'another_variable',
),

Значение переменной окружения:

В выше приведённом примере у префикса "sample-prefix" в конфигурационном файле определены 2 переменные: "sample_variable" и "another_variable". В переменной окружения для данного префикса переданы значения этих переменных, равные "15" и "testing" соответственно. После обработки переменной окружения для данного префикса буду созданы 2 переменные:

Название переменной	Значение

Название переменной	Значение
`sample-prefix_sample_variable`	`15`
`sample-prefix_another_variable`	`testing`

Переменная будет создана, даже если её значение не передано.

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

пример для PHP:

пример для шаблона:

Чтобы не "зашивать" значение префикса в коде его можно получить динамически используя методы:

kEvent::getPrefixSpecial() - для событий
TagProcessor:getPrefixSpecial() - для тэгов

Построение ссылок

Т.к. переменная окружения используется только для компактной передачи данных между страницами сайта, то единственным способом в неё что-либо записать является построение ссылки. Все ссылки в K4 строятся используя метод "Application::HREF". Например он используется в методе Application::Redirect, а также в тэгах m_Link, st_ContentBlock, lang_LanguageLink и m_FormAction. Этот метод принимает 4 описанных ниже параметра.

Название параметра	Описание

Название параметра	Описание
`$t` (string)	Название шаблона, ссылку на который требуется построить (напр. "`custom/tests/test_edit`"). Параметр обязательный, но если передать пустое значение, то будет использован текущий (тот, на который зашёл пользователь) шаблон.
`$prefix` (string)	Данный необязательный параметр предназначен для того, чтобы можно было находясь в административной консоли построить ссылку на пользовательскую часть сайта. Для того, чтобы это сделать нужно передать в него значение "`_FRONT_END_`".
`$params` (array)	Набор параметров, которые следует передать в ссылку. Помимо параметров общего применения можно также передать ряд параметров специального назначения, описанных ниже.
`$index_file` (string)	Необязательное название `php` файла, который следует использовать в результирующей ссылке. По умолчанию равен "`index.php`" (для пользовательской части сайта) и "`admin/index.php`" (для административной консоли).

Параметры специального назначения

`pass` (string)	В данном параметре передаются названия тех префиксов (через запятую), которые будут использоваться при построении значения переменной окружения в результирующей ссылке. Также можно передать значение "`all`", чтобы были использованы все префиксы из ссылки на текущую страницу сайта. Например, "`m,sample-prefix`" или "`all`".
`index_file` (string)	Альтернативный способ задания значения параметра "`index_file`" методу `Application::HREF` через шаблон. Например (если передать "`another_index.php`"):
`escape` (int)	Если указать данный параметр, то на результирующую ссылку будет применена функция addslashes. Только при использовании на шаблонах вместо данного параметра следует использовать параметр "`js_escape`", т.к. он является усовершенствованной версией данного параметра и будет работать для всех тэгов. Например (если передать "`1`"): Обычно параметр "`js_escape`" (в шаблонах) следует использовать для построения ссылок, используемых в `JavaScript`.
`anchor` (string)	Данный параметр позволяет добавить указанное в нём значение, как якорь к результирующей ссылке. Например (если передать "`sample_anchor`"):
`no_amp` (int)	Если передать данный параметр, то все переменные, используемые в результирующей ссылке будут объединены используя символ "`&`" (совместимо с `JavaScript`). Во всех остальных случаях переменные будут объединены при помощи строки "`&`" (совместимо с `HTML`). Например (если передать "`1`"):

Использование переданных параметров

Сначала все переданные параметры делятся на 3 группы:

параметры специального назначения;
параметры, которые будут использоваться в переменной окружения;
остальные параметры.

Берётся список префиксов из значения параметра pass и для каждого префикса выстраивается фрагмент переменной окружения, который будет его представлять. В случае, если значение той или иной переменной префикса не задано в параметрах, то берётся значение, полученное из запроса к серверу или пустая строка, если ничего передано небыло. Все параметры, которые были использованы при построении значения переменной окружения убираются из общего списка параметров (чтобы они не попали в результирующую ссылку).

Остальные, не использованные в переменной окружения параметры (кроме параметров специального назначения) добавляются к результирующей ссылке используя строку "&" или "&" (если используется параметр специального назначения no_amp).

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

Запись данных

Запись значений в переменную окружения из шаблонов сводится к формированию ссылки, по которой в последствии перейдёт пользователь. Формирование ссылок внутри шаблонов производится с помощью тэга m_Link. В ниже приведённом примере продемонстрировано его использование.

Запись данных из шаблонов

Ниже приведено описание параметров тэга m_Link, использованных в выше приведённом примере.

параметр	пояснение

параметр	пояснение
`template` (string)	Путь к шаблону. В пользовательской части сайта это путь относительно директории с темой.
`cart_event` (string)	Название события для префикса `cart`. Указанное событие будет выполнено только в том случае, когда префикс `cart` указан в параметре `pass`.
`pass` (string)	Параметр указывает на то, данные каких префиксов необходимо передать в переменной окружения.

Запись данных из событий

После успешного выполнения каждого события происходит автоматическое перенаправление на шаблон, с которого данное событие было вызвано. Для того, чтобы в ссылке построенной для этого перенаправления присутствовали дополнительные параметры нужно использовать метод kEvent:setRedirectParam. В свою очередь свойство kEvent:redirect позволит задать альтернативный шаблон, использующийся в ссылке на перенаправление. Это будет наглядно показано на ниже приведённом примере.

В данном примере значение переменной "param_name" будет доступно на шаблоне "alternative_destination_template". Подробнее о последующем получении значений переданных параметров написано в этой, выше описанной главе.

Системные переменные окружения

Помимо данных от пользовательских префиксов в переменной окружения всегда передаётся префикс "m" (main), содержащий системные переменные окружения. Конфигурационный файл от данного префикса находиться в папке "core/units/general" и соответственно называется "general_config.php" (название папки плюс "_config.php"). В данном конфигурационном файле используется ключ PortalStyleEnv, из-за которого в результирующей переменной окружения для данного префикса не будет дефиса ("-") между названием префикса и значением его первой переменной (т.е. "m5", а не "m-5" как обычно). При помощи данного префикса передаются следующие переменные:

название	описание

название	описание
`m_cat_id` (int)	ID текущей категории, т.е. той категории, данные из которой пользователь просматривает в данный момент.
`m_cat_page` (int)	Номер страницы в списке категорий, находящихся в категории, заданной в переменной m_cat_id.
`m_lang` (int)	ID языка, на котором нужно показывать содержание сайта (также работает и в административной консоли). Если не задать, то будет использовано ID основного языка, заданное в секции "`Configuration -> Regional`".
`m_theme` (int)	ID темы, которую нужно использовать для показывания пользовательской части сайта. Значение данной переменной не используется в административной консоли. Если не задать, то будет использовано ID основной темы, заданное в секции "`Configuration -> Themes`".
`m_opener` (int)	Данная переменная используется для того, чтобы после при нажатии на кнопки "`Save`" (события OnSave, OnCreate, OnUpdate) и "`Cancel`" (события OnCancelEdit, OnCancel) на панели инструментов на формах редактирования автоматически происходил возврат на тот шаблон, с которого пользователь попал на эту форму редактирования. Для этого используется массив "`opener_stack_<m_wid>`", содержащий шаблоны, заходя на которые пользователь в итоге попал на данный шаблон (напр. "`Array ('users/user_list', 'users/user_edit_groups');`"). Данный массив храниться в сессии. Значение, переданное в данной переменной будет рассматриваться как команда к изменению содержания массива "`opener_stack_<m_wid>`" для текущего окна: `r (reset)` - стереть массив (используется для построения ссылок для секций в дереве); `d (down)` - добавить текущий шаблон в массив (используется при переходе на шаблон редактирования записи с шаблона списка записей); `u (up)` - удалить последний шаблон из массива (используется при возвращении с шаблона редактирования записи на шаблон списка записей); `p (popup)` - добавить текущий шаблон в массив и создать новый идентификатор окна (тоже самое, что "`d`", но только с поправкой на то, что форма редактирования будет открыта в новом всплывающем окне); `s (stay)` - ничего не делать с массивом (значение по умолчанию).
`m_wid` (int)	Идентификатор окна, который используется только для всплывающих окон (`popups`). Для основного окна значение данной переменной равно пустоте. Также идентификатор окна используется в формировании названия массива "`opener_stack_<m_wid>`", управляемого через значение переменной m_opener.

Developers Guide (Russian)