View source

{{toc | category = Структура приложения | sortkey = 004.001}}
<!-- Пишите ПОСЛЕ этой строки, пожалуйста. Ничего не стирать! -->
Переменная окружения представляет из себя обычную переменную из запроса к серверу с названием "<code>env</code>". Само название данной переменной задано в константе [[K4:Константы#ENV_VAR_NAME|ENV_VAR_NAME]]. Она была введена для того, чтобы реализовать возможность компактной передачи большого количества переменных между страницами сайта. В большинстве случаев в ней будет содержаться информация, при помощи которой можно будет загрузить объект из [[K4:Работа с базой данных|базы данных]] на странице (т.е. [[K4:Unit Configs#Prefix|префикс]] и <code>ID</code>), но это совсем не обязательно.

Если в [[K4:Unit Configs|конфигурационном файле]] переданного [[K4:Unit Configs#Prefix|префикс]]а разрешена [[K4:Unit_Configs#AutoLoad|автоматическая загрузка]], то при первом обращении к объекту [[K4:Unit Configs#Prefix|префикс]] которого передан и при наличии его <code>ID</code> в запросе к серверу он будет автоматически загружен.

== Структура ==
Значение, содержащееся в переменной окружения имеет следующую структуру:
 <session_id>-<template>:m<main_prefix_variables>[:<prefix[.special]>-<value1>[-<value2>...[-<valueN>]]]

Как видно из приведённой выше схемы в переменной окружения всегда присутствуют следующие компоненты:
* <code>session_id</code> - [[K4:UserSession#SessionKey|идентификатор сессии]] [[K4:PortalUser|пользователя]];
* <code>template</code> - путь к шаблону, результат обработки которого будет показан на экране;
* <code>main_prefix_variables</code> - ряд системных переменных, среди которых в том числе присутствуют [[K4:Theme#ThemeId|ID темы]] и [[K4:Language|ID языка]], которые будут использованы для вывода информации на странице (об этом позже).

Также в ней могут присутствовать данные неограниченного количества [[K4:Unit Configs#Prefix|префикс]]ов. Наборы данных разных [[K4:Unit Configs#Prefix|префикс]]ов друг от друга отделяются двоеточием ("<code>:</code>"). Первое значение внутри каждого набора - [[K4:Unit Configs#Prefix|префикс]] конфигурационного файла. Если необходимо, то можно указать и "<code>special</code>" следующим образом: "<code>prefix.special</code>".

Далее следует список параметров [[K4:Unit Configs#Prefix|префикс]]а, которые могут передаваться через переменную окружения, разделённых при помощи дефиса ("<code>-</code>"). Названия параметров, а также их порядок в пределах одного набора [[K4:Unit Configs#Prefix|префикс]]а задаётся в ключе [[K4:Unit Configs#QueryString|QueryString]] его [[K4:Unit Configs|конфигурационного файла]]. Например:
<source lang="php">
'QueryString' => Array(
    1 => 'id',
    2 => 'Page',
    3 => 'event',
    4 => 'mode',
),
</source>

Пиведённое выше значение ключа [[K4:Unit Configs#QueryString|QueryString]] является стандартным для большинства [[K4:Unit Configs#Prefix|префикс]]ов и поэтому будет описано ниже.

{| class="prettytable"
! название || описание
|-
| <code>id</code> || ID объекта (<code>Item</code>), которое может быть использовано для [[K4:Unit Configs#AutoLoad|автоматической загрузки]] объекта.
|-
| <code>Page</code> || Номер страницы списка объектов (<code>List</code>).
|-
| <code>event</code> || [[EventHandler:About|Событие]], которое требуется выполнить у данного [[K4:Unit Configs#Prefix|префикс]]а.
|-
| <code>mode</code>
| Режим редактирования записей. Возможны 3 вида значений:
* "" - данные будут редактироваться в оригинальной таблице;
* "<code>t</code>" - данные будут редактироваться во временной таблице в основном окне;
* "<code>t<wid></code>" - данные будут редактироваться во временной таблице, которая была создана при открытии всплывающего окна (<code>popup</code>) с идентификатором окна (<code>window id</code>) равным "<code><wid></code>".
|}
{{InfoBox|Значения данного массива чувствительны к регистру (<code>case-sensitive</code>).}}

== Получение данных из переменной окружения ==
Если в ссылке, используемой для посещения сайта находиться переменная окружения, то её значение будет автоматически обработано системой. Доступ напрямую к значению переменной окружения не рекомендуется. В результате обработки '''для каждого''' из переданных [[K4:Unit Configs#Prefix|префиксов]] будут искуственно созданы переменные вида "<code>'''prefix[.special]_VariableName'''</code>". Будет создано по одной переменной для каждого '''значения''' в массиве [[K4:Unit Configs#QueryString|QueryString]] у переданного [[K4:Unit Configs#Prefix|префикс]]а. Созданные таким образом переменные можно будет в последствии использовать также, как и любые другие переменные, переданные в запросе к серверу (т.е. при помощи метода <code>'''Application::GetVar'''</code>). Это будет наглядно показано на ниже приведённом примере.
* Переменные, заданные в [[K4:Unit Configs|конфигурационном файле]]:
<source lang="php">
'Prefix' => 'sample-prefix',
'QueryString' => Array (
	1 => 'sample_variable',
	2 => 'another_variable',
),
</source>

* Значение переменной окружения:
<source lang="xml">-template:m0--1--s-:sample\-prefix-15-testing</source>

В выше приведённом примере у префикса "<code>sample-prefix</code>" в [[K4:Unit Configs|конфигурационном файле]] определены 2 переменные: "<code>sample_variable</code>" и "<code>another_variable</code>". В переменной окружения для данного префикса переданы значения этих переменных, равные "<code>15</code>" и "<code>testing</code>" соответственно. После обработки переменной окружения для данного префикса буду созданы 2 переменные:
{| class="prettytable"
! название || значение
|-
| <code>sample-prefix_sample_variable</code> || <code>15</code>
|-
| <code>sample-prefix_another_variable</code> || <code>testing</code>
|}
{{TipBox|Переменная будет создана, даже если её значение не передано.}}

Получить значение любой из созданных выше переменных можно будет используя код вида:
{| class="prettytable"
! пример для <code>PHP</code> || пример для шаблона
|-
| <source lang="php">$sample_variable = $this->Application->GetVar('sample-prefix_sample_variable');</source>
| <source lang="xml">value: <inp2:m_Get name="sample-prefix_sample_variable"/></source>
|}
{{InfoBox|Чтобы не "зашивать" значение префикса в коде его можно получить динамически используя методы <code>'''kEvent::getPrefixSpecial()'''</code> (для [[EventHandler:About|событий]]) и <code>'''TagProcessor:getPrefixSpecial()'''</code> (для [[TagProcessor:About|тэгов]]).}}

== Построение ссылок ==
Т.к. переменная окружения используется только для компактной передачи данных между страницами сайта, то единственным способом в неё что-либо записать является построение ссылки. Все ссылки в K4 строятся используя метод "<code>'''Application::HREF'''</code>". Например он используется в методе <code>'''Application::Redirect'''</code>, а также в [[TagProcessor:About|тэгах]] [[TagProcessor:m_Link|m_Link]], [[TagProcessor:st_ContentBlock|st_ContentBlock]], [[TagProcessor:lang_LanguageLink|lang_LanguageLink]] и [[TagProcessor:m_FormAction|m_FormAction]]. Этот метод принимает 4 описанных ниже параметра.

{| class="prettytable"
! параметр || описание
|-
| {{ConfigProperty|$t|string}} || Название шаблона, ссылку на который требуется построить (напр. "<code>custom/tests/test_edit</code>"). Параметр обязательный, но если передать пустое значение, то будет использован текущий (тот, на который зашёл пользователь) шаблон.
|-
| {{ConfigProperty|$prefix|string}} || Данный необязательный параметр предназначен для того, чтобы можно было находясь в административной консоли построить ссылку на пользовательскую часть сайта. Для того, чтобы это сделать нужно передать в него значение "<code>_FRONT_END_</code>". {{InfoBox|На текущий момент данная функциональность не работает (см. [[Вопрос:Как принудительно указать тегу m Link строить линк на Front-End?|этот вопрос]]) и чтобы построить ссылку на пользовательскую часть сайта нужно передать "<code>index.php</code>" в качестве значения параметра [[#index_file|index_file]].}}
|-
| {{ConfigProperty|$params|array}} || Набор параметров, которые следует передать в ссылку. Помимо параметров общего применения можно также передать ряд параметров специального назначения, описанных [[#Параметры специального назначения|ниже]].
|-
| {{ConfigProperty|$index_file|string}} || Необязательное название <code>php</code> файла, который следует использовать в результирующей ссылке. По умолчанию равен "<code>index.php</code>" (для пользовательской части сайта) и "<code>admin/index.php</code>" (для административной консоли).
|}

=== Параметры специального назначения ===
{| class="prettytable"
| {{ConfigProperty|pass|string}} || В данном параметре передаются названия тех [[K4:Unit Configs#Prefix|префикс]]ов (через запятую), которые будут использоваться при построении значения переменной окружения в результирующей ссылке. Также можно передать значение "<code>'''all'''</code>", чтобы были использованы все [[K4:Unit Configs#Prefix|префикс]]ы из ссылки на текущую страницу сайта. Например, "<code>m,sample-prefix</code>" или "<code>all</code>". {{TipBox|Также следует отметить, что '''всегда''', когда указывается список префиксов первым из них должен быть [[K4:Unit Configs#Prefix|префикс]] "<code>m</code>".}}
|-
| {{ConfigProperty|index_file|string}}
| Альтернативный способ задания значения параметра "<code>index_file</code>" методу <code>Application::HREF</code> через шаблон. Например (если передать "<code>another_index.php</code>"):
<source lang="xml">
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- (без параметра)
</source>
|-
| {{ConfigProperty|escape|int}}
| Если указать данный параметр, то на результирующую ссылку будет применена функция [http://php.prod.intechnic.lv/manual/en/function.addslashes.php addslashes]. Только при использовании на шаблонах вместо данного параметра следует использовать параметр "<code>'''js_escape'''</code>", т.к. он является усовершенствованной версией данного параметра и будет работать для всех тэгов. Например (если передать "<code>1</code>"):
<source lang="xml">
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 (без параметра)
</source>
Обычно параметр "<code>'''js_escape'''</code>" (в шаблонах) следует использовать для построения ссылок, используемых в <code>JavaScript</code>.
|-
| {{ConfigProperty|anchor|string}}
| Данный параметр позволяет добавить указанное в нём значение, как якорь к результирующей ссылке. Например (если передать "<code>sample_anchor</code>"):
<source lang="xml">
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- (без параметра)
</source>
|-
| {{ConfigProperty|no_amp|int}}
| Если передать данный параметр, то все переменные, используемые в результирующей ссылке будут объединены используя символ "<code>&</code>" (совместимо с <code>JavaScript</code>). Во всех остальных случаях переменные будут объединены при помощи строки "<code>&amp;amp;</code>" (совместимо с <code>HTML</code>). Например (если передать "<code>1</code>"):
<source lang="xml">
http://www.sample-site.com/index.php?env=-template:m0--1--s-&amp;sample_parameter=value1&amp;another_parameter=value2 (с параметром)
http://www.sample-site.com/index.php?env=-template:m0--1--s-&sample_parameter=value1&another_parameter=value2 (без параметра)
</source>
|}

=== Использование переданных параметров ===
Сначала все переданные параметры делятся на '''3 группы''':
* параметры [[#Параметры специального назначения|специального назначения]];
* параметры, которые будут использоваться в [[#Структура|переменной окружения]];
* остальные параметры.

Берётся список [[K4:Unit Configs#Prefix|префикс]]ов из значения параметра [[#pass|pass]] и для каждого префикса выстраивается [[#Структура|фрагмент]] переменной окружения, который будет его представлять. В случае, если значение той или иной [[#Структура|переменной префикса]] не задано в параметрах, то берётся значение, полученное из запроса к серверу или пустая строка, если ничего передано небыло. Все параметры, которые '''были использованы''' при построении значения переменной окружения убираются из общего списка параметров (чтобы они не попали в результирующую ссылку).

Остальные, не использованные в переменной окружения параметры (кроме параметров [[#Параметры специального назначения|специального назначения]]) добавляются к результирующей ссылке используя строку "<code>&amp;amp;</code>" или "<code>&</code>" (если используется параметр специального назначения [[#no_amp|no_amp]]).

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

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

=== Запись данных из шаблонов ===
<source lang="xml">
<a href="<inp2:m_Link template='cart' cart_event='OnAddProduct' pass='m,cart,product'/>">Add To Cart</a>
</source>

Ниже приведено описание параметров тэга [[TagProcessor:m_Link|m_Link]], использованных в выше приведённом примере.
{| class="prettytable"
! параметр || пояснение
|-
| {{ConfigProperty|template|string}} || Путь к шаблону. В пользовательской части сайта это путь относительно директории с [[K4:Theme|темой]].
|-
| {{ConfigProperty|cart_event|string}} || Название [[EventHandler:About|события]] для префикса <code>cart</code>. Указанное событие будет выполнено только в том случае, когда префикс <code>cart</code> указан в параметре <code>pass</code>.
|-
| {{ConfigProperty|pass|string}} || Параметр указывает на то, данные каких префиксов необходимо передать в переменной окружения.
|}

=== Запись данных из событий ===
После успешного выполнения каждого [[EventHandler:About|события]] происходит автоматическое перенаправление на шаблон, с которого данное событие было вызвано. Для того, чтобы в ссылке построенной для этого перенаправления присутствовали дополнительные параметры нужно использовать метод '''<code>kEvent:setRedirectParam</code>'''. В свою очередь свойство '''<code>kEvent:redirect</code>''' позволит задать альтернативный шаблон, использующийся в ссылке на перенаправление. Это будет наглядно показано на ниже приведённом примере.

<source lang="php">
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');
}
</source>
В данном примере значение переменной "<code>param_name</code>" будет доступно на шаблоне "<code>alternative_destination_template</code>". Подробнее о последующем получении значений переданных параметров написано в [[#Получение данных из переменной окружения|этой, выше описанной главе]].

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

{| class="prettytable"
! название || описание
|-
| {{ConfigProperty|m_cat_id|int}} || [[K4:Category#CategoryId|ID текущей категории]], т.е. той категории, данные из которой пользователь просматривает в данный момент.
|-
| {{ConfigProperty|m_cat_page|int}} || Номер страницы в списке категорий, находящихся в категории, заданной в переменной [[#m_cat_id|m_cat_id]].
|-
| {{ConfigProperty|m_lang|int}} || [[K4:Language#LanguageId|ID языка]], на котором нужно показывать содержание сайта (также работает и в административной консоли). Если не задать, то будет использовано [[K4:Language#PrimaryLang|ID основного языка]], заданное в [[K4:Добавление секций в дереве|секции]] "<code>Configuration -> Regional</code>".
|-
| {{ConfigProperty|m_theme|int}} || [[K4:Theme#ThemeId|ID темы]], которую нужно использовать для показывания пользовательской части сайта. Значение данной переменной не используется в административной консоли. Если не задать, то будет использовано [[K4:Theme#PrimaryTheme|ID основной темы]], заданное в [[K4:Добавление секций в дереве|секции]] "<code>Configuration -> Themes</code>".
|-
| {{ConfigProperty|m_opener|int}}
| Данная переменная используется для того, чтобы после при нажатии на кнопки "<code>Save</code>" (события [[EventHandler:OnSave|OnSave]], [[EventHandler:OnCreate|OnCreate]], [[EventHandler:OnUpdate|OnUpdate]]) и "<code>Cancel</code>" (события [[EventHandler:OnCancelEdit|OnCancelEdit]], [[EventHandler:OnCancel|OnCancel]]) на панели инструментов на формах редактирования автоматически происходил возврат на тот шаблон, с которого пользователь попал на эту форму редактирования. Для этого используется массив "<code>'''opener_stack_<m_wid>'''</code>", содержащий шаблоны, заходя на которые пользователь в итоге попал на данный шаблон (напр. "<code>Array ('users/user_list', 'users/user_edit_groups');</code>").
{{TipBox|Последним элементом в этом массиве будет шаблон, с которого пользователь попал на текущий.}}

Данный массив храниться в [[K4:SessionData|сессии]]. Значение, переданное в данной переменной будет рассматриваться как команда к изменению содержания массива "<code>'''opener_stack_<m_wid>'''</code>" для текущего окна:
* <code>'''r''' (reset)</code> - стереть массив (используется для построения ссылок для [[K4:Добавление секций в дереве|секций]] в дереве);
* <code>'''d''' (down)</code> - добавить текущий шаблон в массив (используется при переходе на шаблон редактирования записи с шаблона списка записей);
* <code>'''u''' (up)</code> - удалить последний шаблон из массива (используется при возвращении с шаблона редактирования записи на шаблон списка записей);
* <code>'''p''' (popup)</code> - добавить текущий шаблон в массив и создать новый [[#m_wid|идентификатор окна]] (тоже самое, что "<code>'''d'''</code>", но только с поправкой на то, что форма редактирования будет открыта в новом всплывающем окне);
* <code>'''s''' (stay)</code> - ничего не делать с массивом (значение по умолчанию).
|-
| {{ConfigProperty|m_wid|int}} || Идентификатор окна, который используется только для всплывающих окон (<code>popups</code>). Для основного окна значение данной переменной равно пустоте. Также идентификатор окна используется в формировании названия массива "<code>'''opener_stack_<m_wid>'''</code>", управляемого через значение переменной [[#m_opener|m_opener]].
|}