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

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

The Environment variable is a standard query variable called "env". Name of this variable is defined in ENV_VAR_NAME constant. The purpose of env variable is to pass a large number of variables in a compact way through the website pages. In most cases env variable will carry the values to load the object from the database on the current page (т.е. Prefix и ID), but usage is not limited by that.

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

Структура

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

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

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

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

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

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

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

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

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

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

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

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- (без параметра)

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 (без параметра)

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- (без параметра)

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" как обычно). При помощи данного префикса передаются следующие переменные: