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

Data Source Eng Data Source Confluence

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

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

2.4.1. Структура

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

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

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

  • session_id - идентификатор сессии пользователя;

  • 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).

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

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

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

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

-template:m0--1--s-:sample\-prefix-15-testing

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

название

значение

sample-prefix_sample_variable

15

sample-prefix_another_variable

testing

Примечание

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

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

пример для PHP

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

 
$sample_variable = $this->Application->GetVar(
  'sample-prefix_sample_variable'
);

value: <inp2:m_Get name="sample-prefix_sample_variable"/>

Примечание

Чтобы не «зашивать» значение префикса в коде его можно получить динамически используя методы kEvent::getPrefixSpecial() (для событий) и TagProcessor:getPrefixSpecial() (для тэгов).

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

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

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

<a href="<inp2:m_Link template='cart' cart_event='OnAddProduct' pass='m,cart,product'/>">Add To Cart</a>

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

параметр

пояснение
template (string)

Путь к шаблону. В пользовательской части сайта это путь относительно директории с темой.
cart_event (string)

Название события для префикса cart. Указанное событие будет выполнено только в том случае, когда префикс cart указан в параметре pass.
pass (string)

Параметр указывает на то, данные каких префиксов необходимо передать в переменной окружения.

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

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

function OnCreate(&$event)
{
    parent::OnCreate($event);

    if ($event->status == erSUCCESS) {
        return ;
    }


    $event->redirect = 'alternative_destination_template';
    $event->setRedirectParam('pass', 'm,test');
    $event->setRedirectParam('param_name', 'param_value');
}

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

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

Помимо данных от пользовательских префиксов в переменной окружения всегда передаётся префикс 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.