From In-Portal Developers Guide

Revision as of 23:35, 6 November 2009

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

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.

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.

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.

• Variables defined in the configuration file:

'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:

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:

$sample_variable = $this->Application->GetVar('sample-prefix_sample_variable');

value: <inp2:m_Get name="sample-prefix_sample_variable"/>

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_". 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". 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)	If this parameter is defined, then the addslashes function will be applied to the resulting link. When using in a template, use "js_escape" instead of this parameter because it's the latest version of this parameter and will work for all tags. For example (if passing "1"): http://www.sample-site.com/index.php?env=-template:m0--1--s-:sample\\-prefix-15-testing (with parameter) http://www.sample-site.com/index.php?env=-template:m0--1--s-:sample\-prefix-15-testing (without parameter) Usually the "js_escape" (in templates) is used to build links that are used in JavaScript.
anchor (string)	This parameter allows adding the value defined in it as an anchor in the resulting link. For example (passing "sample_anchor"): http://www.sample-site.com/index.php?env=-template:m0--1--s-#sample_anchor (with parameter) http://www.sample-site.com/index.php?env=-template:m0--1--s- (without parameter)
no_amp (int)	If this parameter is passed, then all variables, used in the resulting link will be combined with the "&" symbol (compatible with JavaScript). In all other cases, the variables will be combined using the "&" characters (compatible with HTML). For example, (if passing "1"): http://www.sample-site.com/index.php?env=-template:m0--1--s-&sample_parameter=value1&another_parameter=value2 (with parameter) http://www.sample-site.com/index.php?env=-template:m0--1--s-&sample_parameter=value1&another_parameter=value2 (without parameter)

Using Passed Parameters

All passed parameters are divided into 3 groups:

• Special use parameters]];
• Parameters that will be used in the environment variable;
• All other parameters.

A list of prefixes is taken from the value of the pass parameter and a fragment of the environment variable is set for each prefix that will represent it. If the value of a variable's prefix isn't indicated in the parameter, the value received in the request to the server will be used or, if nothing was passed then a blank space will be used. Al parameters that were used in building the value of the environment variable are removed from the general list of parameters (to avoid them ending up in the resulting link).

The rest of the parameters, having not been used in the environment variable parameter (except special purpose parameters), are added to the resulting link using the line "&" or "&" (if the special purpose parameter is used no_amp).

After the completion of the all of the above steps, the special purpose parameters are applied to the link.

Recording Data

Recording values into the environment variable from templates results in creating the link, which the user will eventually follow. Formatting links from templates is done with the m_Link tag. The below examples demonstrates its use.

Recording Data from a Template

<a href="<inp2:m_Link template='cart' cart_event='OnAddProduct' pass='m,cart,product'/>">Add To Cart</a>

Below are descriptions of m_Link tag parameters, used in the above example.

Recording Data from an Event

After successfully executing each event, there is an automatic redirect to the template, from which the event was called. In order for the link that was built for the redirect to contain additional parameters, the method kEvent:setRedirectParam must be used. kEvent:redirect event will allow setting an alternative template to be used in the redirect link. This is demonstrated in the below example.

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');
}

In this example, the value of the "param_name" variable will be available on the "alternative_destination_template" template. More information on getting the values of passed parameters is written in Above Heading.

System Environment Variables

Apart from data from user prefixes, the "m" (main) prefix is always passed into the environment variable. It contains system environment variables. The prefix's configuration file is located in the "core/units/general" folder and is named "general_config.php" (name of the folder plus "_config.php"). There is a key (PortalStyleEnv) used in this configuration file, because of which the resulting environment variable for the prefix will not contain a dash ("-") between the name of the prefix and the value of its first variable (e.g. "m5" instead of the usual "m-5"). The following variables are passed with the help of this prefix:

Name	Description
m_cat_id (int)	Category ID, i.e. the category that the user is currently viewing.
m_cat_page (int)	Page number in the categories list in the category indicated in the m_cat_id variable.
m_lang (int)	Language ID in which the site needs to be shown (works the same way in the Administrative Console). If not set, then Primary Language ID will be used, set in the "Configuration -> Regional" section.
m_theme (int)	Theme ID that needs to be used to show the front-end of the site. The value of this variable isn't used in the Administrative Console. If not set, then ID основной темы will be used, which is set in the "Configuration -> Themes" section.
m_opener (int)	This variable is used so that after "Save" is clicked (events OnSave, OnCreate, OnUpdate) and "Cancel" (event OnCancelEdit, OnCancel) in the edit form toolbar, so that the user is automatically returned to the template from which he came. For this, the array "opener_stack_<m_wid>" is used, which contains the templates that the user accessed before finally getting to the given template (for example "Array ('users/user_list', 'users/user_edit_groups');"). The last element in this array will be the template that the user was on before the open template. This array is stored in the session. The value, passed in the variable will be taken as a command to change the contents of the "opener_stack_<m_wid>" array for the open window: r (rest - delete the array (used to build a link for the section tree); d (down) - add the open template to the array (used when switching to the editing template from a records list template); u (up) - delete the last template from the array (used when returning from the edit template to the grid/records list template); p (popup) - add the open template to the array and create a new window ID (the same as "d", except that the edit form will be open in a popup window); s (stay) - do nothing with the array (default value).
m_wid (int)	Window ID that's only used for (popups). For main windows, the value is blank. The window ID is also used in formatting the name of the "opener_stack_<m_wid>" array, which is controlled through the value of the m_opener variable.