From In-Portal Developers Guide

Revision as of 23:16, 22 October 2009

Структура приложения
Статьи в этой категории
Folder Structure Application Process Flow Constants Environment Variable

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

Note that in case if in Configuration file of passed the Prefix is allowed auto-loading, then at the time of first call to that object of Prefix and existence of object ID in the env variable then that object will be loaded automatically.

Структура

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

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