Joomla! Documentation - User contributions [en]

Talk:How do you redirect users after a successful login?

2013-07-16T16:35:58Z

Wazz: Created page with "the first sentence of this is vague: "Select the redirection page from the list of menu links offered." it assumes knowledge of how to begin setting the redirect. i, for exam..."

the first sentence of this is vague: "Select the redirection page from the list of menu links offered."

it assumes knowledge of how to begin setting the redirect. i, for example, don't know where to begin and am told to make a selection from a list of menu links. i don't know where the 'list of menu links' is.

How to use user state variables

2013-06-30T22:50:44Z

Wazz:

Joomla! provides built in functionality to make it easy for Joomla! developers to store and retrieve variables that are stored with the session.

==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.

==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|JApplication::setUserState]] method. The second is a little less obvious, and uses the [[JApplication/getUserStateFromRequest|JApplication::getUserStateFromRequest]] method. There are also two ways to retrieve user state variables. The first is using the [[JApplication/getUserState|JApplication::getUserState]] method, and the second is to use the [[JApplication/getUserStateFromRequest|JApplication::getUserStateFromRequest]] method. [[JApplication/getUserStateFromRequest|JApplication::getUserStateFromRequest]] can be used to both store and retrieve user state variables.

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

===Method 1: JApplication::setUserState===
<source lang="php">
$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" );
</source>

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===
<source lang="php">
$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' );
</source>

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.

===Method 3: JApplication::getUserState===
<source lang="php">
$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' );
</source>

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.

===Purpose===
It will be noticed that in many of the 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 to the user a list of Newsfeeds. If there are too many newsfeeds to list on one page, then 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 variable to store the value of these variables between page requests.

By storing these variable in a state variable, then if a user goes to administer another component or navigates away from the component, then these values are still remembered when the user returns. In addition, these values then 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 user to set and retrieve the values of these variables:
<source lang="php">
$mainframe =& JFactory::getApplication();

$limit = $mainframe->getUserStateFromRequest( "limit", 'limit', $mainframe->getCfg('list_limit') );
$limitstart = $mainframe->getUserStateFromRequest( "$option.limitstart", 'limitstart', 0 );
</source>

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. It is noted that there is no **$option** prefix in the **$key** parameter. This is because this variable is used as a global parameter (and its initial value is retrieved from the site configuration value). 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|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'.

===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.

Ultimately, this will result in the following form elements being displayed on the page:
<source lang="html4strict">
<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" />
</source>

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.

==See Also==
For information on the Joomla! API relating to session variables, please consult the following sources:
* [[JApplication]]
* [[JSession]]
<noinclude>[[Category:Development]]</noinclude>

J1.5:Creating a submenu

2013-06-30T01:11:20Z

Wazz:

In Joomla!, submenus can be shown either as one menu with two or more levels or as completely separate menu modules. To show how to do this, we will step through creating a two-level menu and then see how to show it either as one large menu or as separate parent and child menus.

==Sample Data==
In our example, we will create a menu called "Pets". It will have two top-level menu items called "Dogs" and "Cats". Under Dogs, we will have "Collies" and "Greyhounds". Under Cats we will have "Tabbies" and "Siamese". So the structure of the Pets menu will be as follows:
*Dogs
**Collies
**Greyhounds
*Cats
**Tabbies
**Siamese

==Menu and Menu Items==
To create this structure, we create one menu with two levels of Menu Items. Note that we do this whether we want to have everything shown as one large menu or whether we want to create separate menu modules (one parent menu and two child menus). We'll see how to do this later on, when we create the modules.

Here are the steps to create the Menu and Menu Items.
# Create a new Menu in the Menu Manager called "Pets".
# Add a new Menu Item called "Dogs". For this example, we don't really care what the type of the Menu Items is. For example, you can just create one article called "Pet Menu Test" and then create all of the Menu Items as type '''Article → Article Layout''' and point to this article.
# Add a second Menu Item called "Collies" (again, Menu Type of Article Layout as above). In the Parent Item box, select "Dogs", as shown below: [[Image:submenu_example1.png|frame|center]]
# Add a third Menu Item called "Greyhounds", again making "Dogs" the Parent Item. (Remember, these can all point to the same article.)
# Add the "Cats" Menu Item. Be sure to make the Parent Item for this "Top".
# Add the last two Menu Items, "Tabbies" and "Siamese", making "Cats" the Parent Item for both.

When you get done, the Menu Item Manager should look like the following:[[Image:submenu_example2.png|frame|center]]

==Menu Modules==
At this point, we've got the Menu and Menu Items done. Now we need to create the Menu Modules. In Joomla!, the Menu Module determines three main things: (1) what the menu looks like; (2) where on the page it will show; and (3) on which pages it will show. We will do two examples. In the first example, we will create one Menu Module that shows all of the items in one menu. In the second, we will create three separate menu modules to show the Pets, Dogs, and Cats menus as separate modules.

===One Menu Module===
To show this as one module, follow these steps:
# Navigate to Extensions → Module Manager, click the "New" icon in the toolbar, and select "Menu".
# Enter the Title as "Pets Menu" and Position as "left".
# In the Menu Assignment, enter "Select Menu Item(s) from the List" and select "Home" (under "mainmenu"), and all of the Menu Items under the "pets-menu".
# In Menu Name, select "pets-menu" from the drop-down list box.
# If you are using the default "rhuk_milkyway" template and want the menu to look like the other menus, in the Advanced Parameters enter "_menu" for Module Class Suffix.

Now, navigate to the front-end home page. You should see the Pets Menu as shown below:[[Image:submenu_example3.png|frame|center]]Click on the Dogs Menu Item. The selected article displays and the Dogs menu expands to show the two submenu items, Collies and Greyhounds. Note that we can set a parameter in the Module Manager to always show submenu items. Here we have taken the default value of "No".

Click on "Collies" and again the article changes. (Or it would if we had different articles for each Menu Item!) The screen should look like the one below: [[Image:submenu_example4.png|frame|center]]

Notice that the Breadcrumbs now shows three levels: Home, Dogs, Collies. Because we used submenus, Joomla! "knows" that Collies is under Dogs.

===Separate Menu Modules===
Now we will change our example to create three separate menus -- one for the top level (Dogs and Cats), one for the Dogs (Collies and Greyhounds), and one for the Cats (Tabbies and Siamese).

<blockquote>''Note: Make sure that your Menu Items each have a unique Alias value. If you use the Copy command in the toolbar of the Menu Item Manager to create these Menu Items, the Alias will be the same as the item being copied. In this case, just edit the Alias value to make it unique (for example, the same as the Title). If you have duplicate Alias values, the menus will not work correctly if the parameter SEF URLs is set to Yes in Global Configuration.''</blockquote>

To do this:
# Open the Pets Menu in the Module Manager and change the Title to "Pets Menu Top Level Only".
# Select the Left Position.
# Under Module Parameters, select the Menu Name "Pets Menu"
# Under Module Parameters, change the Menu Style to "List".
# Set the Start Level to "0" and the End Level to "1".
# ''This is optional. It allows your template to apply special a menu style to the menu (a border, for example).'' In Advanced Module Parameters put "_menu" in Module Class Suffix.
# For submenu Dog, in extensions menu select Module Manager, click New and select Menu, and set the title to "Dogs Submenu".
# Set the Position to "Left".
# ''Now this part is very important.'' We only want this submenu to show when we are in one of the Dogs Menu Items. So, in the Menu Assignment box, select the three items "Dogs", "Collies", and "Greyhounds", as shown below: [[Image:submenu_example5.png|frame|center]]
# Under Module Parameters, select the menu name "Pets Menu" and change the Menu Style to "List".
# Set the Start Level to "1" and End Level "2".
# ''This is optional.'' In Advanced Module Parameters, set Module Class Suffix to "_menu".
# For the "Cats Submenu", repeat steps from 7 to 12 except step 9. In the Menu Assignment box, select the items "Cat", "Tabbies" and "Siamese" (so this menu will only show under these Menu Items).

At this point, we have three menu modules all pointing to the Pets Menu. The only differences between them are (1) the Start and End Levels and (2) the Menu Item Assignment.

Now, in the front end, navigate to the Home page. The "Pets Menu Top Level Only" menu should show. Select the "Dogs" Menu Item. Now, the "Dogs Submenu" should show as a separate menu, as shown below:[[Image:submenu_example7.png|frame|center]]

Click on the Collies Menu Item and notice that again the Breadcrumbs shows the hierarchy of "Home", "Dogs", and "Collies".

Using this same technique, it is easy to create third-level submenus. You just make the Parent Menu Item a second-level submenu. Then you could use the same technique to create a separate Menu Module with Start Level of 2 and End Level of 3. This would show only the third-level Menu Items.

[[Category:Tutorials]]
[[Category:Menu Management]]