In-Portal Developers Guide

This is a wiki-based Developers Guide for In-Portal Open Source CMS. The purpose of this guide is to provide advanced users, web developers and programmers with documentation on how to expand, customize and improve the functionality and the code the In-Portal software. Please consider contributing to our documentation writing effort.

K4:Переменная окружения

From In-Portal Developers Guide

Jump to: navigation, search
Line 97: Line 97:
=== Special Purpose Parameters ===
=== Special Purpose Parameters ===
{| class="prettytable"
{| 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|pass|string}} || In this parameter are passed the names of the [[K4:Unit Configs#Prefix|prefix]] tags (comma delimited) that will be used for building the value of the environment variable in the resulting link. It's also possible to pass the value "<code>'''all'''</code>" so that all [[K4:Unit Configs#Prefix|prefix]]es in a link are used on the page of a site. For example, "<code>m,sample-prefix</code>" or "<code>all</code>". {{TipBox|'''Always''' when writing a list of prefixes, the first one must be the [[K4:Unit Configs#Prefix|prefix]] "<code>m</code>".}}
|-
|-
| {{ConfigProperty|index_file|string}}
| {{ConfigProperty|index_file|string}}
-
| Альтернативный способ задания значения параметра "<code>index_file</code>" методу <code>Application::HREF</code> через шаблон. Например (если передать "<code>another_index.php</code>"):
+
| An alternative way to set the value of the "<code>index_file</code>" parameter for the <code>Application::HREF</code> method through the template. For example (if passing "<code>another_index.php</code>"):
<source lang="xml">
<source lang="xml">
-
http://www.sample-site.com/another_index.php?env=-template:m0--1--s- (с параметром)
+
http://www.sample-site.com/another_index.php?env=-template:m0--1--s- (with parameter)
-
http://www.sample-site.com/index.php?env=-template:m0--1--s- (без параметра)
+
http://www.sample-site.com/index.php?env=-template:m0--1--s- (without parameter)
</source>
</source>
|-
|-

Revision as of 21:51, 31 October 2009

Структура приложения Структура приложения
Статьи в этой категории

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.

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.

Contents

Structure

The value contained in the environment variable has the following structure:

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

For the above scheme, it can be seen that the environment variable is always made up of the following components:

  • session_id - session identifier user;
  • template - path to the template, the rendering of which will be shown on the screen;
  • main_prefix_variables - system variables, among which are theme ID and language ID, which will be used to output information on the page (will be explained later).

Also, it may contain data from an unlimited number of prefixes. Data sets from different prefixes are separated with a colon (":"). The first value in each set is the prefix of the configuration file. If necessary, then the "special" can be indicated in the following format: "prefix.special".

The following is a list of parameters of the prefix that can be passed through the environment variable, delimited using a hyphen ("-"). Parameter names and their order in a single set of a prefix is set in the key QueryString of its Configs|configuration file]]. For example:

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

The above key value QueryString is the standard for most prefixes and therefore will be described below.

Name Description
id Object ID (Item) that can be used for automatic loading of an object.
Page Page number of the object list (List).
event Event, that needs to be executed from a given prefix.
mode Three types of values are possible:
  • "" - values will be edited in the original table;
  • "t" - values will be edited in a temporary table in the main window;
  • "t<wid>" - values will be edited in a temporary table that was created as the result of a popup, where the window id is "<wid>".
Image:Infobox Icon.gif The values in this array are (case-sensitive).

Getting Data from the Environment Variable

If the URL used to open the site contains an environment variable, then its value will automatically be processed by the system. Direct access to the value of the environment variable isn't recommended. The result of processing each of the passed prefixes creates variables, e.g. "prefix[.special]_VariableName". One variable will be created for each value in the QueryString array of the passed prefix. Variables created by this process can then be used just like any other variables passed in a request to the server (i.e. use the method Application::GetVar). This will be demonstrated in the below example.

'Prefix' => 'sample-prefix',
'QueryString' => Array (
	1 => 'sample_variable',
	2 => 'another_variable',
),
  • Environment Variable Values:
-template:m0--1--s-:sample\-prefix-15-testing

There are two variables defined in the above example for the "sample-prefix" prefix in the configuration file: "sample_variable" and "another_variable". The values that are passed in the environment variable for this prefix are "15" and "testing", respectively. Two variables will be created after processing the environment variable for this prefix:

Name Value
sample-prefix_sample_variable 15
sample-prefix_another_variable testing
Image:Tipbox Icon.gif The variable will be created even if a value isn't passed.

The following code will allow getting the value of either of the variables created above:

PHP Example Template Example
$sample_variable = $this->Application->GetVar('sample-prefix_sample_variable');
value: <inp2:m_Get name="sample-prefix_sample_variable"/>
Image:Infobox Icon.gif To avoid hard-coding the value of the prefix, it can be obtained dynamically using the following methods:kEvent::getPrefixSpecial() (for events) and TagProcessor:getPrefixSpecial() (for tags).

Building Links

Since the environment variable is used to compactly pass data between the pages of a site, the only way to to add something to it is by building a link. All links in K4 are built using the method "Application::HREF". For example, it's used in the method code>Application::Redirect</code> and in the tags m_Link, st_ContentBlock, lang_LanguageLink and m_FormAction. This method accepts the following four parameters.

Parameter Description
$t (string) Name of the template to which a link needs to be built (for example "custom/tests/test_edit"). This parameter is required, but if a blank value is passed, then the current template will be used (the one the user opened).
$prefix (string) This optional parameter is available to make it possible to build a link to the front end of the site while located in the administrative console. To do this, it's value has to be passed as "_FRONT_END_".
Image:Infobox Icon.gif Currently, this functionality doesn't work (see this question) and to build a link to the front-end, "index.php" has to be passed as the value of the index_file parameter.
$params (array) This is a set of parameters that should be passed in a link. In addition to passing general application parameters, it's also possible to pass many special purpose parameters, which are described in below.
$index_file (string) Optional name of the php file that should be used in the resulting link. By default, it's set to "index.php" (for the front-end) and "admin/index.php" (for the administrative console).

Special Purpose Parameters

pass (string) In this parameter are passed the names of the prefix tags (comma delimited) that will be used for building the value of the environment variable in the resulting link. It's also possible to pass the value "all" so that all prefixes in a link are used on the page of a site. For example, "m,sample-prefix" or "all".
Image:Tipbox Icon.gif Always when writing a list of prefixes, the first one must be the prefix "m".
index_file (string) An alternative way to set the value of the "index_file" parameter for the Application::HREF method through the template. For example (if passing "another_index.php"):
http://www.sample-site.com/another_index.php?env=-template:m0--1--s- (with parameter)
http://www.sample-site.com/index.php?env=-template:m0--1--s- (without parameter)
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). Во всех остальных случаях переменные будут объединены при помощи строки "&amp;" (совместимо с HTML). Например (если передать "1"):
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 (без параметра)

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

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

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

Остальные, не использованные в переменной окружения параметры (кроме параметров специального назначения) добавляются к результирующей ссылке используя строку "&amp;" или "&" (если используется параметр специального назначения 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');").
Image:Tipbox Icon.gif Последним элементом в этом массиве будет шаблон, с которого пользователь попал на текущий.

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