From In-Portal Developers Guide

Структура приложения
Статьи в этой категории
Структура директорий Протекание Процессов в Приложении Константы Переменная окружения

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

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

Структура

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

<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 является стандартным для большинства префиксов и поэтому будет описано ниже.

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

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

Если в ссылке, используемой для посещения сайта находиться переменная окружения, то её значение будет автоматически обработано системой. Доступ напрямую к значению переменной окружения не рекомендуется. В результате обработки для каждого из переданных префиксов будут искуственно созданы переменные вида "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_variable = $this->Application->GetVar('sample-prefix_sample_variable');

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

Чтобы не "зашивать" значение префикса в коде его можно получить динамически используя методы 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_". На текущий момент данная функциональность не работает (см. этот вопрос) и чтобы построить ссылку на пользовательскую часть сайта нужно передать "index.php" в качестве значения параметра index_file.
$params (array)	Набор параметров, которые следует передать в ссылку. Помимо параметров общего применения можно также передать ряд параметров специального назначения, описанных ниже.
$index_file (string)	Необязательное название php файла, который следует использовать в результирующей ссылке. По умолчанию равен "index.php" (для пользовательской части сайта) и "admin/index.php" (для административной консоли).

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

pass (string)	В данном параметре передаются названия тех префиксов (через запятую), которые будут использоваться при построении значения переменной окружения в результирующей ссылке. Также можно передать значение "all", чтобы были использованы все префиксы из ссылки на текущую страницу сайта. Например, "m,sample-prefix" или "all". Также следует отметить, что всегда, когда указывается список префиксов первым из них должен быть префикс "m".
index_file (string)	Альтернативный способ задания значения параметра "index_file" методу Application::HREF через шаблон. Например (если передать "another_index.php"): http://www.sample-site.com/another_index.php?env=-template:m0--1--s- (с параметром) http://www.sample-site.com/index.php?env=-template:m0--1--s- (без параметра)
escape (int)	Если указать данный параметр, то на результирующую ссылку будет применена функция addslashes. Только при использовании на шаблонах вместо данного параметра следует использовать параметр "js_escape", т.к. он является усовершенствованной версией данного параметра и будет работать для всех тэгов. Например (если передать "1"): http://www.sample-site.com/index.php?env=-template:m0--1--s-:sample\\-prefix-15-testing (с параметром) http://www.sample-site.com/index.php?env=-template:m0--1--s-:sample\-prefix-15-testing (без параметра) Обычно параметр "js_escape" (в шаблонах) следует использовать для построения ссылок, используемых в JavaScript.
anchor (string)	Данный параметр позволяет добавить указанное в нём значение, как якорь к результирующей ссылке. Например (если передать "sample_anchor"): http://www.sample-site.com/index.php?env=-template:m0--1--s-#sample_anchor (с параметром) http://www.sample-site.com/index.php?env=-template:m0--1--s- (без параметра)
no_amp (int)	Если передать данный параметр, то все переменные, используемые в результирующей ссылке будут объединены используя символ "&" (совместимо с JavaScript). Во всех остальных случаях переменные будут объединены при помощи строки "&" (совместимо с HTML). Например (если передать "1"): http://www.sample-site.com/index.php?env=-template:m0--1--s-&sample_parameter=value1&another_parameter=value2 (с параметром) http://www.sample-site.com/index.php?env=-template:m0--1--s-&sample_parameter=value1&another_parameter=value2 (без параметра)

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

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

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

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

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

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

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

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

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

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

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

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

После успешного выполнения каждого события происходит автоматическое перенаправление на шаблон, с которого данное событие было вызвано. Для того, чтобы в ссылке построенной для этого перенаправления присутствовали дополнительные параметры нужно использовать метод 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". Подробнее о последующем получении значений переданных параметров написано в этой, выше описанной главе.

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

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