K4:Переменная окружения
From In-Portal Developers Guide
Revision as of 14:36, 25 December 2008
| ||
---|---|---|
Статьи в этой категории | ||
|
Переменная окружения представляет из себя обычную переменную из запроса к серверу с названием "env
". Само название данной переменной задано в константе ENV_VAR_NAME. Она была введена для того, чтобы реализовать возможность компактной передачи большого количества переменных между страницами сайта. В большинстве случаев в ней будет содержаться информация, при помощи которой можно будет загрузить объект из базы данных на странице (т.е. префикс и ID
), но это совсем не обязательно.
Если в конфигурационном файле переданного префикса разрешена автоматическая загрузка, то при первом обращении к объекту префикс которого передан и при наличии его ID
в запросе к серверу он будет автоматически загружен.
Contents |
Структура
Значение, содержащееся в переменной окружения имеет следующую структуру:
<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 вида значений:
|
Получение данных из переменной окружения
Если в ссылке, используемой для посещения сайта находиться переменная окружения, то её значение будет автоматически обработано системой. Доступ напрямую к значению переменной окружения не рекомендуется. В результате обработки для каждого из переданных префиксов будут искуственно созданы переменные вида "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() (для тэгов).
|
Построение ссылок
Т.к. переменная окружения используется только для компактной передачи данных между страницами сайта, то единственным способом в неё что-либо записать является построение ссылки. Все ссылки в K4 строятся используя метод "Application::HREF
". Например он используется в методе Application::Redirect
, а также в тэгах m_Link, st_ContentBlock, lang_LanguageLink и m_FormAction. Этот метод принимает 4 описанных ниже параметра.
параметр | описание | ||
---|---|---|---|
$t (string) | Название шаблона, ссылку на который требуется построить (напр. "custom/tests/test_edit "). Параметр обязательный, но если передать пустое значение, то будет использован текущий (тот, на который зашёл пользователь) шаблон.
| ||
$prefix (string) | Данный необязательный параметр предназначен для того, чтобы можно было находясь в административной консоли построить ссылку на пользовательскую часть сайта. Для того, чтобы это сделать нужно передать в него значение "_FRONT_END_ ".
| ||
$params (array) | Набор параметров, которые следует передать в ссылку. Помимо параметров общего применения можно также передать ряд параметров специального назначения, описанных ниже. | ||
$index_file (string) | Необязательное название php файла, который следует использовать в результирующей ссылке. По умолчанию равен "index.php " (для пользовательской части сайта) и "admin/index.php " (для административной консоли).
|
Параметры специального назначения
pass (string) | В данном параметре передаются названия тех префиксов (через запятую), которые будут использоваться при построении значения переменной окружения в результирующей ссылке. Также можно передать значение "all ", чтобы были использованы все префиксы из ссылки на текущую страницу сайта. Например, "m,sample-prefix " или "all ".
| ||
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 (без параметра) Обычно параметр " | ||
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, использованных в выше приведённом примере.
параметр | пояснение |
---|---|
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
". Подробнее о последующем получении значений переданных параметров написано в этой, выше описанной главе.
Системные переменные окружения
Помимо данных от пользовательских префиксов в переменной окружения всегда передаётся префикс "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'); ").
Данный массив храниться в сессии. Значение, переданное в данной переменной будет рассматриваться как команда к изменению содержания массива "
|
m_wid (int) | Идентификатор окна, который используется только для всплывающих окон (popups ). Для основного окна значение данной переменной равно пустоте. Также идентификатор окна используется в формировании названия массива "opener_stack_<m_wid> ", управляемого через значение переменной m_opener.
|