Joomla如何使用状态变量

How to use user state variables

Why should I use the Joomla! User State Variables?

Joomla!'s built in session handling capabilities make it easy to retain values of certain variables across page accesses. This makes development much simpler because the developer no longer has to worry about losing variable values if it is left out of a form. Storing variables with sessions also makes the application cleaner and tidier since it reduces the amount of form variables, and persistent variables no longer have to be passed in either the query string (making very long URLs) or in POST variables.

The downside of using session variables is that it makes page URLs stateful. That is, if used improperly, a URL might point to certain information in one context, but different information in another context. This can make search engines less effective since the web crawler might pull up a certain page using a certain URL, that when the user links to the URL from the search engine, might pull up a different page, resulting in user confusion and frustration.

Joomla内建的session处理能力能非常方便的在page之间传递变量，这样URL就更简洁了。

负面就是使URL保存不变，不利于搜索引擎

Setting and retrieving user state variables

There are two ways to set user state variables. The first is fairly intuitive, and is done using the JApplication::setUserState method. The second is a little less obvious, and uses the JApplication::getUserStateFromRequest method. There are also two ways to retrieve user state variables. The first is using the JApplication::getUserStatemethod, and the second is to use the JApplication::getUserStateFromRequest method. JApplication::getUserStateFromRequest can be used to both store and retrieve user state variables.

2种方式设置状态变量：JApplication::setUserState 和 JApplication::getUserStateFromRequest 

2种方式获取状态变量： JApplication::getUserState 和 JApplication::getUserStateFromRequest（获取和设置是一个函数）

The following methods are used for accessing the user state variables:

Method 1: JApplication::setUserState

$mainframe =JFactory::getApplication();
 
// store the variable that we would like to keep for next time
// function syntax is setUserState( $key, $value );
$mainframe->setUserState( "$option.state_variable", "state1" );

The first parameter is the key under which to store the variable. You will note that in this example the key began with the $option variable. Although the value for $key is arbitrary, it is good practice to use this as a prefix for all user state variables since these are all in the same name space. Using an extension-specific prefix avoids extensions interfering with each other. In the example above, state_variable is the name of the state variable that will be stored, and the second parameter is the value to store with the state variable.

参数是键值对，键可以任意设置，但是最好有个代表扩展的前缀，以免互相影响

Method 2: JApplication::getUserStateFromRequest

$mainframe =JFactory::getApplication();
 
// retrieve the value of the state variable. First see if the variable has been passed
// in the request. Otherwise retrieve the stored value. If none of these are specified,
// the specified default value will be returned
// function syntax is getUserStateFromRequest( $key, $request, $default );
$stateVar = $mainframe->getUserStateFromRequest( "$option.state_variable", 'state_variable', 'state1' );

The first parameter is the key under which to store the variable. Note again that this is prefixed with the name of the current extension. This method will update the user state variable by looking in the variables that were passed with the request (in either GET or POST) and updating the user state variable if the specified request variable is set. This can be used to set user state variables with values that are passed from forms (i.e. from the user). If an existing value can be found either in the request or in the stored state variable, this is returned. Otherwise, the specified default value is returned (if it is specified), or NULL is returned if no value can be found.

获取状态变量的值。首先，看看request中有没有传过来第二个参数的值，有的话就返回；没有就看看第一个参数中有没有存着值；如果都没有，就返回第三个参数的值。都没有就返回NULL

Method 3: JApplication::getUserState

$mainframe =JFactory::getApplication();
 
// retrieve the value of the state variable. If no value is specified,
// the specified default value will be returned.
// function syntax is getUserState( $key, $default );
$stateVar = $mainframe->getUserState( "option.state_variable", 'state1' );

The first parameter is the key under which to store the variable. Note again that this is prefixed with the name of the current extension. This method will retrieve the value of the specified user state variable. If this user state variable has not been set, then the value is read from the $default parameter. If the user state variable has not been set and $default is not specified, the method will return NULL.

A real life example of the use of Joomla! user state variables

The following code excerpts are taken from the admin section of the Newsfeed component, which is a core Joomla! component. These snippets are meant to demonstrate how user state variable can be used in an actual application.

通过Newsfeed组件来介绍状态变量怎么用

Purpose

Notice that many components that have database tables associated with them present to the user a list of items. In the case of the Newsfeed component, the administration section presents a list of Newsfeeds. If there are too many newsfeeds to list on one page, two variables are used to keep track of where the user is in the list: the limit variable and the limitstart variable. The Newsfeed component (like other components) uses state variables to store the value of limit and limitstart between page requests.

两个变量： limit， limitstart。分页显示用

If a user goes to administer another component or navigates away from the component, these values are available when the user returns. In addition, these values only have to be passed if they are being changed. The developer does not have to bother with inserting hidden form feeds to pass these values along.

这两个变量到其他的组件也一样用，除非他们改变了。

Setting and retrieving the variables

The following code is used to set and retrieve the values of these variables:

$mainframe =JFactory::getApplication();
 
$limit = $mainframe->getUserStateFromRequest( "limit", 'limit', $mainframe->getCfg('list_limit') );
$limitstart = $mainframe->getUserStateFromRequest( "$option.limitstart", 'limitstart', 0 );

The first variable that is stored is the limit variable. The limit variable specifies how many records should be retrieved from the database and displayed. Note that there is no$option prefix in the $key parameter. This variable is used as a global parameter (and its initial value is retrieved from the site configuration value). 注意，这个变量没有$option，因为它是全局变量。The value is retrieved from the request variable called 'limit'. If the state variable has not been specified yet and it is not specified in the request, then the value is retrieved from the site configuration using the JApplication::getCfg method.这个参数的默认值是通过设置来调取。

The second variable that is stored is the limitstart variable. This specifies how many records to skip over before returning records from the database. Each component has its own list and so keeps its own place in its own list. The $option parameter in this case has the value 'com_newsfeeds', and so the session variable name is 'com_newsfeeds.limitstart'.

$option 竟然自带组件名的纸？？

Passing values to JPagination class

In this example, the stored values are used as parameters for constructing the pagination class, which helps the developer implement pagination functionality.

传值到JPagination来使用

Ultimately, this will result in the following form elements being displayed on the page:

<div class="limit">Display #
<select name="limit" id="limit" class="inputbox" size="1" onchange="document.adminForm.submit();">
<option value="5"  selected="selected">5</option>
<option value="10" >10</option>
<option value="15" >15</option>
<option value="20" >20</option>
<option value="25" >25</option>
<option value="30" >30</option>
<option value="50" >50</option>
<option value="100" >100</option></select>
</div>
 
<div class="start"><span>Start</span></div>
<div class="button2-right off"><div class="prev"><span>Prev</span></div></div>
<div class="button2-left"><div class="page">
<span>1</span>
<a title="2" onclick="javascript: document.adminForm.limitstart.value=5; document.adminForm.submit();return false;">2</a>
</div></div>
 
<div class="button2-left"><div class="next">
<a title="Next" onclick="javascript: document.adminForm.limitstart.value=5; document.adminForm.submit();return false;">Next</a>
</div></div>
 
<div class="button2-left"><div class="end"><a title="End" onclick="javascript: document.adminForm.limitstart.value=5; document.adminForm.submit();return false;">End</a></div></div>
 
<div class="limit">
Results 1 - 5 of 10</div>
 
<input type="hidden" name="limitstart" value="0" />

One may be observant and notice that the values are passed in hidden form elements anyway, and claim therefore that it is really not necessary to use state variables. But this will not help in the situation where the user has navigated away from the component, and it will also not help in the situation which occurs in the list, for example, where each newsfeed is listed and linked using a standard link, and not the form. Using state variables saves having to add limit and limitstart on to the end of these URLs.