Joomla! Documentation - User contributions [en]

J2.5:Supporting SEF URLs in your component

2009-09-22T22:18:17Z

JimDeLaHunt: /* A Simple Example */ Clarify that component name prefix is all lower-case

{{incomplete}}
{{RightTOC}}
[[Category:Development]]

== Routing Overview ==

Joomla! 1.5 is capable of creating and parsing URLs in any format, including human readable URL's. Another improvement is that this still works even if Joomla! runs a server other than Apache with the mod_rewrite module.

A good example of this is the "Welcome to Joomla" article. The first link shown was generated without mod_rewrite, and the second link was generated with mod_rewrite:

* <code><nowiki>http://www.example.com/index.php/the-news/1-latest-news/1-welcome-to-joomla</nowiki></code>
* <code><nowiki>http://www.example.com/the-news/1-latest-news/1-welcome-to-joomla</nowiki></code>

== Preparing Your Data for Routing ==

=== The Alias ===

The first step is the generation of the so called alias. The alias is used in the URL instead of the title (the title is the text you want to have in the url). The alias has to be URI safe, which means accented UTF8 characters are replaced by their ASCII7 equivalents, white spaces by hyphens, etc.

The alias can be defined by the user, but you should ensure that the above requirements for a URL safe alias are met. A good way to do so is to use the JTable::check() method during the save process. Have a look at this example code:

<source lang="php">

function check()
{
jimport( 'joomla.filter.output' );
if(empty($this->alias)) {
$this->alias = $this->title;
}
$this->alias = JFilterOutput::stringURLSafe($this->alias);

/* All your other checks */
return true;
}
</source>

If the alias field is empty the title will be used as alias. Then the alias will be made URLSafe using the JFilterOutput::stringURLSafe() method.

=== The Slug ===

Continuing with the same example, the "slug" - "1-welcome-to-joomla" has two parts. The first part is the article identifier (id) and the second is the alias. They are separated by a hyphen. These two elements were combined during the database query in the model:

<pre>$query = 'SELECT a.*,'.
' CASE WHEN CHAR_LENGTH(a.alias) THEN CONCAT_WS(\':\', a.id, a.alias) ELSE a.id END as slug,'.
[...];</pre>

After this step the slug is used instead of the id.

== Routing URL's ==

The <code>JRoute::_</code> method translates the internal Joomla! URL to a custom URL. <code>JRoute</code> has three parameters and its prototype is:

<pre>JRoute::_( $url, $xhtml = true, $ssl=0 );</pre>

Where:

* <code>$url</code> is a string containing the absolute or relative internal Joomla! URL.
* <code>$xhtml</code> is a boolean value that specifies whether or not the output should be in XHTML. This parameter is optional and if omitted defaults to true.
* <code>$ssl</code> is an integer value that specifies whether the URI should be secure. It should be set to 1 to force the URI to be secure using the global secure site URI, 0 to leave it in the same state as when it was passed, and -1 to force the URI to be unsecure using the global unsecure site URI.

The most important parameter is <code>$url</code>. A call to this method might look like:

<pre>JRoute::_( 'index.php?view=article&id='.$row->slug );</pre>

<code>$row->slug</code> is the value that was generated in step 2 from a combination of id and title alias.

Another advantage of using JRoute is that the router now handles $option (the component name) and the $Itemid (the menu item ID). The component itself doesn’t have to know its name ($option) or the active menu item ($Itemid) like it did in previous version of Joomla!.

It is important that you think about the sequence of the URL parameter in this stage. This will be more clear when we have a deeper look at the router.php in the next section.

The building process of JRouter is divided into two steps:

* Create the application route. The application route is fully handled by JRouter and the component developer doesn’t have to do anything to make it work.
* Create the component route. To create the component route, JRouter looks for the router.php in the component directory which is responsible for building the route for the component.

== The Component Router ==

We will have two functions In the router.php. One is responsible for building the URL and the other is responsible for parsing it. In the next examples, a very basic and a more advanced one, we assume that we have three views that links can point to. The first is a categories overview (view=categories), the second is a single category (view=category) and the third is a single article (view=article).

The file router.php should be in the site area of your component. It is not used on admin/backend pages. Don't forget to add it to your installation XML in the site folder.

=== A Simple Example ===

This simple example will illustrate the basics of implementing a router for your component.

<source lang="php">
function [componentname]BuildRoute( &$query )
{
$segments = array();
if(isset($query['view']))
{
$segments[] = $query['view'];
unset( $query['view'] );
}
if(isset($query['id']))
{
$segments[] = $query['id'];
unset( $query['id'] );
};
return $segments;
}

</source>

<code>JRouter</code> passes a $query array to the <code>[''componentname'']BuildRoute</code> function. This function will add the relevant parts of the array to the $segments array in the right order and will return the properly ordered array. The content of the <code>$query</code> array needs to be unset, otherwise <code>JRouter</code> will add it to the URL in the form of a query string (i.e. any variables that are not handled by the router will be passed in the query string).

The prefix ''componentname'' is the name for your component, as found in the directory holding the component's files. For instance, a component "Magic" in directory <code>/components/com_magic/...</code> would use a prefix <code>magic</code> (all lower case).

The next function in the <code>router.php</code> parses the URL:

<source lang="php">
function [componentname]ParseRoute( $segments )
{
$vars = array();
switch($segments[0])
{
case 'categories':
$vars['view'] = 'categories';
break;
case 'category':
$vars['view'] = 'category';
$id = explode( ':', $segments[1] );
$vars['id'] = (int) $id[0];
break;
case 'article':
$vars['view'] = 'article';
$id = explode( ':', $segments[1] );
$vars['id'] = (int) $id[0];
break;
}
return $vars;
}
</source>

What happens here? In the function <code>[''componentname'']BuildRoute</code> we arranged the items in the <code>$query</code> array in a specific sequence. This means that in this example the view is first, the catid is second and the id is third in the array.

By reading <code>$segments[0]</code>, we access the name of the view. We set the right view and/or identifier depending on its value and we return the <code>$vars</code> array to <code>JRouter</code>. $vars should be an associative array similar to the array that was passed to the BuildRoute method.

The above example of the <code>router.php</code> is a very simple way to generate sef URL's but should show how this works quite clearly.

The generated URL in this example contains the name of the view and doesn't reflect the content hierarchy:

<code><nowiki>http://www.example.com/[menualias]/[view]/[slug]</nowiki></code>

=== A More Advanced Example ===

In the next example we will try to get rid of the need for the view and we will try to reflect the current hierarchy level in the URL.

The goal is URL's that look like:

* When viewing an article: <code><nowiki>http://www.example.com/[menualias]/[category]/[article]</nowiki></code>
* When viewing a category: <code><nowiki>http://www.example.com/[menualias]/[category]</nowiki></code>
* When viewing the categories overview: <code><nowiki>http://www.example.com/[menualias]</nowiki></code>

Let's assume we have done step 1 and 2 also for the category.

The link to the article would look like this:

<source lang="php">
JRoute::_( 'index.php?view=article&catid='.$row->catslug .'&id='.$row->slug );
</source>

And the Link to the category would look like this:

<source lang="php">
JRoute::_( 'index.php?view=category&id='.$row->catslug );
</source>

The corresponding <code>router.php</code>:

<source lang="php">

function [''Componentname'']BuildRoute(&$query)
{
$segments = array();
if(isset( $query['catid'] ))
{
$segments[] = $query['catid'];
unset( $query['catid'] );
};
if( isset($query['id']) )
{
$segments[] = $query['id'];
unset( $query['id'] );
};
unset( $query['view'] );
return $segments;
}
</source>

The difference now is that we don’t add the name of the view to the <code>$segments</code> array. We still unset the view key since otherwise, <code>JRouter</code> would add it to the URL as part of the query string. Another new thing here is the additional parameter catid that we push into the <code>$segments</code> array.

<source lang="php">
function [''Componentname'']ParseRoute($segments)
{
$vars = array();
$menu =& JMenu::getInstance();
$item =& $menu->getActive();
// Count segments
$count = count( $segments );
//Handle View and Identifier
switch( $item->query['view'] )
{
case 'categories':
if($count == 1) {
$vars['view'] = 'category';
}
if($count == 2) {
$vars['view'] = 'article';
}
$id = explode( ':', $segments[$count-1] );
$vars['id'] = (int) $id[0];
break;
case 'category':
$id = explode( ':', $segments[$count-1] );
$vars['id'] = (int) $id[0];
$vars['view'] = 'article';
break;
}
return $vars;
}
</source>

You can see that this ParseRoute function has a lot of different code parts in comparison to the previous. The reason for this is simple. We don’t have the name of the view in the <code>$segments</code> array and we need to find another way to determine it.

We need to find out which level of hierarchy we are in by receiving the root element. We do this by looking to the view name of the active menu item:

<source lang="php">
$item->query['view']
</source>

Also we need to know the number of items in the <code>$segments</code> array:

<source lang="php">
$count = count( $segments );
</source>

With this information we can correctly set the view for all possible three cases:

* The menu item is a link to the categories view and the <code>$segments</code> array has two items (<code>$catid</code> and <code>$id</code>). In this case we know that we need to parse a link to an article .
* The menu item is a link to the categories view and the $segments array has one item ($id). In this case we know that we need to parse a link to a category.
* The menu item is a link to a category. In this case, we know that any item in the $segments array is the identifier for an article .

The result of all this code is nice and human readable component URL's.

== Application Route Parsing ==

The [[API Execution Order]] outlines that the route (URL) is parsed immediately after initialisation is complete. Since fancy URL's are not treated (yet) in the Administrator, we will follow the route parsing process in detail when <code>JSite::route</code> in the <code>index.php</code> file.

* Call to <code>JApplication::route</code>
** Clone the URI
** Call to <code>JApplication::getRouter</code>
*** Call to <code>JRouter::getInstance</code> passing the type ("site")
** Call to <code>JRouterSite::parse</code> passing the URI
*** Strip the suffix if applicable (added to $vars['format'])
*** Re-set the route (URI)
*** Call to <code>JRouter::parse</code> passing the URI
**** Call to <code>JRouterSite::_processParseRules</code> passing the URI (this will call custom route rules)
***** Call to <code>JRouter::_processParseRules</code> passing the URI
****** Call any custom routing rules (probably added via a system plugin using the <code>onAfterInitialise</code> event trigger) passing the URI
****** Returns an array of vars
***** If SEF mode, replace <code>start</code> variable with </code>limitstart</code>
**** If raw mode, call to <code>JRouterSite::_parseRawRoute</code> passing the URI
**** If SEF mode, call to <code>JRouterSite::_parseSefRoute</code> passing the URI
***** If the route (the URI path) is empty, load it from the default menu item; set the active menu item as the default
***** If first part is <code>/component/com_content</code>, set the <code>option</code> as the second segement. Null the <code>Itemid</code>.
***** Else, loop through menu alias values and take off segments that match as the menu tree is traversed. Set <code>option</code> and <code>Itemid</code> based on the last menu item found.
***** If the <code>Itemid</code> is set in the URL, set the active menu item based on this value.
***** Push the vars collected so far (eg, <code>option</code>, <code>Itemid</code>, etc) into the router object (<code>$this</code>).
***** If the route and <code>option</code> is set, load the component router;
***** Else, get the active menu item and get the route vars from it

== Application Route Building ==

TODO

== Custom Router Rules ==

TODO

== Additional References ==

There is a useful thread on this subject here: [[jtopic:148632]] (note, may be out of date)

J1.5:Component parameters

2009-09-19T12:23:54Z

JimDeLaHunt: /* 1. Component-wide default parameters */ More on url elements

==Background==
One thing that sets Joomla! Components apart from other types of Extension (i.e. Modules and Plugins) is the ability to store significant quantities of data in the Joomla! MySQL database. Typically, this data will be content for displaying on a page (such as the content of an article, or its title) or data about how that content should be displayed (e.g. a setting specifying whether or not the title should be shown). A Component normally creates at least one table in the database to store this data - for example, data for articles associated with the <code>com_content</code> Component are stored in the <code>jos_content</code> table (where ''jos'' is the table prefix for the site).

However, choosing exactly how to store each item of data requires a little more thought. There are essentially two choices: each data item may be stored in its own field, or a collection of data items may be stored within a single parameters field. (Of course, there is nothing to stop you making use of both methods, for different data items, within the same component). Which approach you use for a given data item is largely a matter of personal choice, although there are some factors to consider:
* Core code included in the Joomla! installation makes it very easy to produce the appropriate form elements for entering data into '''parameters''' in the Back-end. If you choose to save the data in separate fields, you will need to code the appropriate form elements yourself.
* Again, Joomla! core code allows you to set default values for '''parameters''' across the whole component. Individual component items (e.g. individual articles) can then choose to use the default values, or to override them with values specific to that item. See below for details of how to do this.
* It is not possible to extract individual parameter values directly from the database. Instead, the whole parameters field must be extracted and parsed to obtain the different parameter values. This means that it is not very easy, for example, to run MySQL queries that search for a parameter with a particular value. Any data that you want to run queries against should be given its '''own table field'''.
* Similarly, it is not possible to run data validation on parameter fields before saving data.
In general, parameters are conventionally used to store data relating to the ''presentation'' of information. The information itself is generally stored in separate fields.

==Types of Component parameter==

===1. Component-wide default parameters===

These parameters are set once for the whole Component, and are generally used to provide the 'default' parameter settings for the Component on that particular site.

===2. Menu item specific parameters===

A menu link to an individual Component item (e.g. an article) can also have parameters associated with it, which can affect the way the Component item is displayed ''using that link''. The types of parameters available will depend on the way that the Component item is displayed (the 'view' in MVC terms, but don't worry if this doesn't mean anything to you!). However, the precise values of those parameters can be set for each menu link individually. If there is another menu link to that same Component item, then it is important to realise each menu link may have different parameter values, and so the same article may be displayed differently in the two cases.

A menu link can also override the Component-wide default parameters, so that the override values (if set) are used in place of the default values ''for that Component item when accessed via that menu link''. As you would expect, when no override value is set, the default value is used instead, in the normal manner.

===3. 'Article' specific parameters===

Finally, each Component item (e.g. article) can have parameters which apply to that item, regardless of how it is accessed (i.e. via any available menu link, or even without reference to a menu at all!). If the Component designer wants, the article specific parameters can also be set up to use the 'override' behaviour, so that they default to the current values of the corresponding Component-wide parameters, though this is not essential. Again, this is described further below.

==Storing the parameters and their values.==

In general, a set of parameters is stored within the database in a single <code>text</code> field. Different parameters are separated by <code>newline</code> characters ('<code>\n</code>' in MySQL - each parameter will appear on a different line when you look at the data in something like phpMyAdmin). Each parameter consists of the parameter name and value, separated by an equals sign (=). As an example:

<source lang="text">
parameter1=parameter1value
parameter2=
parameter3=parameter3value
parameter4=parameter4value
</source>

Here, parameter1, parameter3, and parameter4 have all been assigned values, whilst parameter2 has no value. Typically, a parameter will be given no value where it is set up to allow override of a default value, but 'no override is required' - i.e. it is desired to use the default value.

===1. Component-wide default parameters===

These are stored in the <code>params</code> field of the jos_components table, in the row corresponding to the particular component to which they apply.

===2. Menu item specific parameters===

These are stored in the <code>params</code> field of the jos_menu table, in the row corresponding to the particular menu item to which they apply.

===3. 'Article' specific parameters===

These are stored in a text field in the table created by the Component. Whilst there is no strict rule for naming the field, it is common to extend the above pattern using the <code>params</code> name. However, com_content stores article parameters in a field called <code>attribs</code>.

==Accessing the parameters - Back-end==

Joomla! includes some shortcuts to enable component creators to easily add parameter forms to the Back-end of their component. These forms allow a site administrator to enter a parameter value by, for example, entering some text in a box, choosing from a drop-down list, or selecting a radio button. To create these forms, each parameter needs to have an associated <code><param /></code> object in an XML file. The type of <code><nowiki><param /></nowiki></code> object determines the form elements that will be shown in the Back-end. A list of the available form elements is given [[Standard_parameter_types|here]]. More information is given below about the XML file names, structure and location required for each set of parameters.

===1. Component-wide default parameters===

These can be created at installation of the Component, by including <code><param /></code> elements in the installation XML file (typically called COMPONENT_NAME.xml, and located in the root folder of the Component package. As far as the parameters are concerned, this XML file has the following structure:
<source lang="xml">
<install>
...
<params>
<param />


<param name="font_size" default="16" />

...
</params>
<url addpath="....">
<param />
</url>
...
</install>
</source>
Each <code><param /></code> element must be given the attributes <code>name</code> and <code>default</code>, which define the parameter name and value respectively. These values are then copied to the jos_components table in the database.

However, on its own this is not very useful, as it doesn't allow users to change the values of the parameters. To do this, parameter form elements need to be defined in a file named <code>config.xml</code> which is located in <code>/PATH_TO_JOOMLA/administrator/components/com_COMPONENT_NAME/</code>. The file should have the following structure:
<source lang="xml">
<root>
<params>
<url addpath="/administrator/components/com_COMPONENT_NAME/elements">
<param name="cid" type="JELEMENT_TYPE_NAME" scope="com_COMPONENT_NAME" default="0" label="LABEL" description="DESCRIPTION" />
</url>
<param type="type" name="name" description="description" />



<param type="text" name="font_size" size="3" label="Font size:" description="Please enter the required font size" />

...
</params>
</root>
</source>
Note that the <code><root></code> element can have any name you wish, but there must be one element at the root of the document (this is a requirement for a well-formed XML document). You can have more than one <code><params></code> element, but only the first one will be considered. It is not currently possible to group certain parameter form elements together.

The <code><url></code> section contains parameters which are added to the URL of the menu item. To enable this functionality, the <code>type</code> attribute of the <code><param></code> elements must specify the name of a class which extends JElement, and is able to generate HTML forms to display and set the parameter. You can use one of the [[Standard parameter types]]. Or, you can create your own subclass of JElement. Put the class definition file in your component's <code>/administrator/components/com_COMPONENT_NAME/</code> directory, and refer to this path in the <code>addpath</code> attribute of the <code><URL></code> element. More information here: http://forum.joomla.org/viewtopic.php?f=476&t=206062.

So that administrators to access these parameters, you will need to add a button to the toolbar in the Back-end of your component. This can be done using the code:
<source lang="php">
JToolBarHelper::preferences( 'com_COMPONENT_NAME' );
// e.g. for the core Content component, you would use JToolBarHelper::preferences( 'com_content' );
</source>
which is typically placed in the PHP file responsible for the Back-end output. (For example, using an MVC structure, you might place this code at the top of <code>/PATH_TO_JOOMLA/administrator/components/com_COMPONENT_NAME/views/VIEW_NAME/tmpl/default.php</code>.

This adds a <code>Parameters</code> button to the toolbar:

[[Image:Toolbar_newsfeed.png]]

Clicking on the toolbar button produces a pop-up window containing the form fields for each parameter defined in <code>config.xml</code>.

Note that there is no need to define <code>default</code> attributes for the <code><param /></code> elements in the <code>config.xml</code> file, since the default values will already have been saved in the installation of the Component.

===2. Menu item specific parameters===

A menu item is associated with a particular view from your Component's Front-end - following the menu link in the Front-end will display that view. Joomla! 1.5 allows you to define parameters for a particular view, so that a copy of those parameters can be associated with each menu item using the view. In addition, you can also choose to override the Component-wide default parameters defined as above, so that the override values will apply to the particular menu item.

The view parameters are defined in an XML file stored in the ''Front-end'' view output template directory. (This is not to be confused with the site Template directory, which is different!). The XML file has the same name as the layout used with the template. For must applications you will be using the default layout. Thus the path the XML file is something like: <code>/PATH_TO_JOOMLA/components/com_COMPONENT_NAME/views/VIEW_NAME/tmpl/default.xml</code>. The structure of the file is:
<source lang="xml">
<metadata>
...
<state>
...
<params>
<param />
...
</params>
<url>
<param />
...
</url>
<advanced>
<param />
...
</advanced>
</state>
</metadata>
</source>

See [[Standard parameter types]] for a full list of the core parameter types. (You can use these types within a <code><url></code> section without needing to supply an <code>addpath</code> attribute.)

Displaying the forms for these parameters is handled automatically by the core <code>com_menus</code> component, which creates a number of slider panes on the right hand side (at least when viewed using the default Khepri backend site Template) of the menu item edit screen. Any parameters defined within the <code><params></code> or <code><url></code> tags will appear in the <code>Parameters - Basic</code> slider pane. Any parameters defined within the <code><advanced></code> tag will appear in the <code>Parameters - Advanced</code> slider pane.

The following screenshot shows the menu admin page for the Category 'List' layout. You can see that the <code>Parameters - Basic</code> slider pane is open, and contains form elements for five parameters. There are no 'Advanced' parameters for this view, and so the <code>Parameters - Advanced</code> slider pane is not shown:

[[Image:Menu items edit.png]]

For the override of the Component-wide default parameters, <code>com_menus</code> uses the same <code>config.xml</code> file as above, so there is no need to define these parameters again. The override forms are automatically added to a slider pane named <code>Parameters - Component</code>. However, there are a number of changes from the forms used in the Preferences pop-up window (despite being based on the same <code>config.xml</code> file):
* Any <code><param type="radio" /></code> parameter is shown not as a radio button form field, but by a drop-down list.
* All drop-down lists (both those defined as such in <code>config.xml</code>, and those defined as radio buttons) are given an extra option. This extra option displays the text "Use Global" but has an associated value of an empty string. The "Use Global" option is set as the default option for the list. Thus, by default, these parameters will use the Component-wide default values, rather than overriding them. (However, note that any text box fields defined with a default value in <code>config.xml</code> retain that default value, and so will override the component-wide default value if that is different).

===3. 'Article' specific parameters===

These are defined in an XML file which can be stored anywhere you like, but is typically placed within the <code>models</code> folder of the Component Back-end (if you are using an MVC structure) and named according to the model to which they apply, i.e. <code>PATH_TO_JOOMLA/administrator/components/com_COMPONENT_NAME/models/MODEL_NAME.xml</code>. The XML file has the following structure:

<source lang="xml">
<root>
<params>
<param />
...
</params>
<params group="GROUP_NAME">
<param />
...
</params>
...
</root>
</source>

As above, you can give the <code><root></code> element whatever name you wish. You can also have as many <code><params></code> groups as you like, though each group must have a <code>group</code> attribute with a different <code>GROUP_NAME</code>. If there are two or more <code><params></code> groups with the same <code>GROUP_NAME</code>, only the last one in the list will be considered.

To display the forms for these parameters in the Back-end of your Component, you will need to do a little work yourself. Firstly, you need to access the saved parameter data from the database. For this, you will need to identify both the location of the stored parameters data in the database, and the XML file that you are using to define the parameter form fields. Assuming that you have already created a <code>$row</code> variable to hold your component item (i.e. 'article') data, that the parameters data is stored in the <code>params</code> field of the <code>$row</code>, and that the XML file is located in the models folder as specified above, you could use the following code:
<source lang="php">
$paramsdata = $row->params;
$paramsdefs = JPATH_COMPONENT.DS.'models'.DS.'MODEL_NAME.xml';
$params = new JParameter( $paramsdata, $paramsdefs );

$this->assignRef('params', $params);
</source>
This code is typically placed in the View file (e.g. view.html.php) within the corresponding folder.

To display the parameters forms in slider panes (in the same way that they are displayed in the menu item Back-end), you should use the following code in the template file (e.g. <code>PATH_TO_JOOMLA/administrator/com_COMPONENT_NAME/views/VIEW_NAME/tmpl/default.php</code>):
<source lang="php">
$pane =& JPane::getInstance( 'sliders' );

echo $pane->startPane( 'content-pane' );

// First slider panel
// Create a slider panel with a title of SLIDER_PANEL_1_TITLE and a title id attribute of SLIDER_PANEL_1_NAME
echo $pane->startPanel( JText::_( 'SLIDER_PANEL_1_TITLE' ), 'SLIDER_PANEL_1_NAME' );
// Display the parameters defined in the <params> group with no 'group' attribute
echo $this->params->render( 'params' );
echo $pane->endPanel();

//Second slider panel
// Create a slider panel with a title of SLIDER_PANEL_2_TITLE and a title id attribute of SLIDER_PANEL_2_NAME
echo $pane->startPanel( JText::_( 'SLIDER_PANEL_2_TITLE' ), 'SLIDER_PANEL_2_NAME' );
// Display the parameters defined in the <params> group with the 'group' attribute of 'GROUP_NAME'
echo $this->params->render( 'params', 'GROUP_NAME' );
echo $pane->endPanel();

// Repeat for each additional slider panel required

echo $pane->endPane();
</source>
In order to save the parameters to the database you have to overload the bind() function which can be found in
<code>PATH_TO_JOOMLA/administrator/com_COMPONENT_NAME/tables/COMPONENT_NAME.php</code>
<source lang="php">
function bind($array, $ignore = '')
{
if (key_exists( 'params', $array ) && is_array( $array['params'] ))
{
$registry = new JRegistry();
$registry->loadArray($array['params']);
$array['params'] = $registry->toString();
}
return parent::bind($array, $ignore);
}
</source>

==Accessing the parameters - frontend==

The Front-end situation is a bit more complex than the Back-end. The 'standard' way to deal with parameters in the Front-end is to set up a cascade of overrides, as described above:
<blockquote>Item-specific ''overrides'' Menu-specific ''overrides'' Component-default</blockquote>
If you '''don't''' want to do this, then a little extra work is required

===With overrides===

The following code will access the Component-wide default parameters, ''already overridden'' with those for the menu item (if applicable):

<source lang="php">
<?php
$params = &JComponentHelper::getParams( 'COMPONENT_NAME' );

// e.g. for the com_weblinks component, you would use:
// $params = &JComponentHelper::getParams( 'com_weblinks' )
?>
</source>

In an MVC structure, this code would be placed in the <code>view.html.php</code> file for the particular view required.

Assuming that the item parameters are stored in the <code>params</code> field, and that the particular item has been loaded into the <code>$row</code> object by the method, you would then add in the item parameters to the <code>$params</code> object using:

<source lang="php">
<?php
$params->merge( new JParameter( &$row->params ) );
?>
</source>

Note that, in both cases (i.e. overrides by menu-specific parameters, and overrides by item-specific parameters), we aren't ''just'' doing overrides - we also add in any new parameters that weren't found in the defaults. In other words, the <code>$params</code> object ends up with all the parameters we need!

To access the value of a specific parameter, we would use:

<source lang="php">
<?php
$params->get( 'PARAMETER_NAME' );

// e.g. to obtain the value of 'parameter1', we use:
// $params->get( 'parameter1' );
?>
</source>

It is important to realise that any <code>merge</code> carried out is persistent, so the following code (where for example you have an array containing the parameters sets for several items, and you want the parameters for each item to individually override the defaults) would not produce the result you might expect:

<source lang="php">
<?php
foreach ($itemparamsgroup as $itemparams)
{
$params = &JComponentHelper::getParams( 'COMPONENT_NAME' );
$params->merge( $itemparams );
echo $params->get( 'PARAMETER_NAME' );
}
?>
</source>

In such cases, you will need to use the non-override method, and then force the overrides manually, as described below.

===Without overrides===

There will be cases where you don't want to use the default override pattern. For example, you may want to ignore the menu-specific parameters, and have only the item-specific parameters overriding the defaults. This is a little more difficult to accomplish, although it can still be done.

You can access the Component-wide default parameter values, ''without the menu overrides'', as follows:

<source lang="php">
<?php
$component = JComponentHelper::getComponent( 'COMPONENT_NAME' );
$params = new JParameter( $component->params );
?>
</source>

If you want to override these with the menu parameters, but ''without'' the 'persistence' effect described above, you can:

<source lang="php">
<?php
$menuitemid = JRequest::getInt( 'Itemid' );
if ($menuitemid)
{
$menu = JSite::getMenu();
$menuparams = $menu->getParams( $menuitemid );
$params->merge( $menuparams );
}
?>
</source>

You can access the item parameters as before, and choose whether to merge them in using the code above, or simply store them in a separate object:

<source lang="php">
<?php
$itemparams = new JParameter( $row->params );
?>
</source>

You can combine this code to achieve the effect that you want. For example, you could override the Component-wide defaults with the item-specific parameters, but ignore those for the menu. Or you could use the menu-specific parameters in some circumstances, and the item-specific ones in others. [Whenever you depart from the standard approach, though, you should be careful that you inform your users how your Component works. Users will expect your component to work the same way as those from the Joomla! core, so you should have a good reason for departing from this approach.]

Accessing the value of a particular parameter is done in the same way as described above.

<noinclude>[[Category:Development]][[Category:Components]][[Category:Parameters]]</noinclude>

J1.5:Component parameters

2009-09-19T12:15:03Z

JimDeLaHunt: /* 2. Menu item specific parameters */ Clarify addpath attribute rules.

==Background==
One thing that sets Joomla! Components apart from other types of Extension (i.e. Modules and Plugins) is the ability to store significant quantities of data in the Joomla! MySQL database. Typically, this data will be content for displaying on a page (such as the content of an article, or its title) or data about how that content should be displayed (e.g. a setting specifying whether or not the title should be shown). A Component normally creates at least one table in the database to store this data - for example, data for articles associated with the <code>com_content</code> Component are stored in the <code>jos_content</code> table (where ''jos'' is the table prefix for the site).

However, choosing exactly how to store each item of data requires a little more thought. There are essentially two choices: each data item may be stored in its own field, or a collection of data items may be stored within a single parameters field. (Of course, there is nothing to stop you making use of both methods, for different data items, within the same component). Which approach you use for a given data item is largely a matter of personal choice, although there are some factors to consider:
* Core code included in the Joomla! installation makes it very easy to produce the appropriate form elements for entering data into '''parameters''' in the Back-end. If you choose to save the data in separate fields, you will need to code the appropriate form elements yourself.
* Again, Joomla! core code allows you to set default values for '''parameters''' across the whole component. Individual component items (e.g. individual articles) can then choose to use the default values, or to override them with values specific to that item. See below for details of how to do this.
* It is not possible to extract individual parameter values directly from the database. Instead, the whole parameters field must be extracted and parsed to obtain the different parameter values. This means that it is not very easy, for example, to run MySQL queries that search for a parameter with a particular value. Any data that you want to run queries against should be given its '''own table field'''.
* Similarly, it is not possible to run data validation on parameter fields before saving data.
In general, parameters are conventionally used to store data relating to the ''presentation'' of information. The information itself is generally stored in separate fields.

==Types of Component parameter==

===1. Component-wide default parameters===

These parameters are set once for the whole Component, and are generally used to provide the 'default' parameter settings for the Component on that particular site.

===2. Menu item specific parameters===

A menu link to an individual Component item (e.g. an article) can also have parameters associated with it, which can affect the way the Component item is displayed ''using that link''. The types of parameters available will depend on the way that the Component item is displayed (the 'view' in MVC terms, but don't worry if this doesn't mean anything to you!). However, the precise values of those parameters can be set for each menu link individually. If there is another menu link to that same Component item, then it is important to realise each menu link may have different parameter values, and so the same article may be displayed differently in the two cases.

A menu link can also override the Component-wide default parameters, so that the override values (if set) are used in place of the default values ''for that Component item when accessed via that menu link''. As you would expect, when no override value is set, the default value is used instead, in the normal manner.

===3. 'Article' specific parameters===

Finally, each Component item (e.g. article) can have parameters which apply to that item, regardless of how it is accessed (i.e. via any available menu link, or even without reference to a menu at all!). If the Component designer wants, the article specific parameters can also be set up to use the 'override' behaviour, so that they default to the current values of the corresponding Component-wide parameters, though this is not essential. Again, this is described further below.

==Storing the parameters and their values.==

In general, a set of parameters is stored within the database in a single <code>text</code> field. Different parameters are separated by <code>newline</code> characters ('<code>\n</code>' in MySQL - each parameter will appear on a different line when you look at the data in something like phpMyAdmin). Each parameter consists of the parameter name and value, separated by an equals sign (=). As an example:

<source lang="text">
parameter1=parameter1value
parameter2=
parameter3=parameter3value
parameter4=parameter4value
</source>

Here, parameter1, parameter3, and parameter4 have all been assigned values, whilst parameter2 has no value. Typically, a parameter will be given no value where it is set up to allow override of a default value, but 'no override is required' - i.e. it is desired to use the default value.

===1. Component-wide default parameters===

These are stored in the <code>params</code> field of the jos_components table, in the row corresponding to the particular component to which they apply.

===2. Menu item specific parameters===

These are stored in the <code>params</code> field of the jos_menu table, in the row corresponding to the particular menu item to which they apply.

===3. 'Article' specific parameters===

These are stored in a text field in the table created by the Component. Whilst there is no strict rule for naming the field, it is common to extend the above pattern using the <code>params</code> name. However, com_content stores article parameters in a field called <code>attribs</code>.

==Accessing the parameters - Back-end==

Joomla! includes some shortcuts to enable component creators to easily add parameter forms to the Back-end of their component. These forms allow a site administrator to enter a parameter value by, for example, entering some text in a box, choosing from a drop-down list, or selecting a radio button. To create these forms, each parameter needs to have an associated <code><param /></code> object in an XML file. The type of <code><nowiki><param /></nowiki></code> object determines the form elements that will be shown in the Back-end. A list of the available form elements is given [[Standard_parameter_types|here]]. More information is given below about the XML file names, structure and location required for each set of parameters.

===1. Component-wide default parameters===

These can be created at installation of the Component, by including <code><param /></code> elements in the installation XML file (typically called COMPONENT_NAME.xml, and located in the root folder of the Component package. As far as the parameters are concerned, this XML file has the following structure:
<source lang="xml">
<install>
...
<params>
<param />


<param name="font_size" default="16" />

...
</params>
...
</install>
</source>
Each <code><param /></code> element must be given the attributes <code>name</code> and <code>default</code>, which define the parameter name and value respectively. These values are then copied to the jos_components table in the database.

However, on its own this is not very useful, as it doesn't allow users to change the values of the parameters. To do this, parameter form elements need to be defined in a file named <code>config.xml</code> which is located in <code>/PATH_TO_JOOMLA/administrator/components/com_COMPONENT_NAME/</code>. The file should have the following structure:
<source lang="xml">
<root>
<params>
<url addpath="/administrator/components/com_COMPONENT_NAME/elements">
<param name="cid" type="JELEMENT_TYPE_NAME" scope="com_COMPONENT_NAME" default="0" label="LABEL" description="DESCRIPTION" />
</url>
<param type="type" name="name" description="description" />



<param type="text" name="font_size" size="3" label="Font size:" description="Please enter the required font size" />

...
</params>
</root>
</source>
Note that the <code><root></code> element can have any name you wish, but there must be one element at the root of the document (this is a requirement for a well-formed XML document). You can have more than one <code><params></code> element, but only the first one will be considered. It is not currently possible to group certain parameter form elements together.

The url parameter specifies a parameter which is added to the URL of the menu item. To enable this functionality, you must create a new class which extends JElement and put it in the administrator/components/com_COMPONENT_NAME directory. More information here: http://forum.joomla.org/viewtopic.php?f=476&t=206062.

So that administrators to access these parameters, you will need to add a button to the toolbar in the Back-end of your component. This can be done using the code:
<source lang="php">
JToolBarHelper::preferences( 'com_COMPONENT_NAME' );
// e.g. for the core Content component, you would use JToolBarHelper::preferences( 'com_content' );
</source>
which is typically placed in the PHP file responsible for the Back-end output. (For example, using an MVC structure, you might place this code at the top of <code>/PATH_TO_JOOMLA/administrator/components/com_COMPONENT_NAME/views/VIEW_NAME/tmpl/default.php</code>.

This adds a <code>Parameters</code> button to the toolbar:

[[Image:Toolbar_newsfeed.png]]

Clicking on the toolbar button produces a pop-up window containing the form fields for each parameter defined in <code>config.xml</code>.

Note that there is no need to define <code>default</code> attributes for the <code><param /></code> elements in the <code>config.xml</code> file, since the default values will already have been saved in the installation of the Component.

===2. Menu item specific parameters===

A menu item is associated with a particular view from your Component's Front-end - following the menu link in the Front-end will display that view. Joomla! 1.5 allows you to define parameters for a particular view, so that a copy of those parameters can be associated with each menu item using the view. In addition, you can also choose to override the Component-wide default parameters defined as above, so that the override values will apply to the particular menu item.

The view parameters are defined in an XML file stored in the ''Front-end'' view output template directory. (This is not to be confused with the site Template directory, which is different!). The XML file has the same name as the layout used with the template. For must applications you will be using the default layout. Thus the path the XML file is something like: <code>/PATH_TO_JOOMLA/components/com_COMPONENT_NAME/views/VIEW_NAME/tmpl/default.xml</code>. The structure of the file is:
<source lang="xml">
<metadata>
...
<state>
...
<params>
<param />
...
</params>
<url>
<param />
...
</url>
<advanced>
<param />
...
</advanced>
</state>
</metadata>
</source>

See [[Standard parameter types]] for a full list of the core parameter types. (You can use these types within a <code><url></code> section without needing to supply an <code>addpath</code> attribute.)

Displaying the forms for these parameters is handled automatically by the core <code>com_menus</code> component, which creates a number of slider panes on the right hand side (at least when viewed using the default Khepri backend site Template) of the menu item edit screen. Any parameters defined within the <code><params></code> or <code><url></code> tags will appear in the <code>Parameters - Basic</code> slider pane. Any parameters defined within the <code><advanced></code> tag will appear in the <code>Parameters - Advanced</code> slider pane.

The following screenshot shows the menu admin page for the Category 'List' layout. You can see that the <code>Parameters - Basic</code> slider pane is open, and contains form elements for five parameters. There are no 'Advanced' parameters for this view, and so the <code>Parameters - Advanced</code> slider pane is not shown:

[[Image:Menu items edit.png]]

For the override of the Component-wide default parameters, <code>com_menus</code> uses the same <code>config.xml</code> file as above, so there is no need to define these parameters again. The override forms are automatically added to a slider pane named <code>Parameters - Component</code>. However, there are a number of changes from the forms used in the Preferences pop-up window (despite being based on the same <code>config.xml</code> file):
* Any <code><param type="radio" /></code> parameter is shown not as a radio button form field, but by a drop-down list.
* All drop-down lists (both those defined as such in <code>config.xml</code>, and those defined as radio buttons) are given an extra option. This extra option displays the text "Use Global" but has an associated value of an empty string. The "Use Global" option is set as the default option for the list. Thus, by default, these parameters will use the Component-wide default values, rather than overriding them. (However, note that any text box fields defined with a default value in <code>config.xml</code> retain that default value, and so will override the component-wide default value if that is different).

===3. 'Article' specific parameters===

These are defined in an XML file which can be stored anywhere you like, but is typically placed within the <code>models</code> folder of the Component Back-end (if you are using an MVC structure) and named according to the model to which they apply, i.e. <code>PATH_TO_JOOMLA/administrator/components/com_COMPONENT_NAME/models/MODEL_NAME.xml</code>. The XML file has the following structure:

<source lang="xml">
<root>
<params>
<param />
...
</params>
<params group="GROUP_NAME">
<param />
...
</params>
...
</root>
</source>

As above, you can give the <code><root></code> element whatever name you wish. You can also have as many <code><params></code> groups as you like, though each group must have a <code>group</code> attribute with a different <code>GROUP_NAME</code>. If there are two or more <code><params></code> groups with the same <code>GROUP_NAME</code>, only the last one in the list will be considered.

To display the forms for these parameters in the Back-end of your Component, you will need to do a little work yourself. Firstly, you need to access the saved parameter data from the database. For this, you will need to identify both the location of the stored parameters data in the database, and the XML file that you are using to define the parameter form fields. Assuming that you have already created a <code>$row</code> variable to hold your component item (i.e. 'article') data, that the parameters data is stored in the <code>params</code> field of the <code>$row</code>, and that the XML file is located in the models folder as specified above, you could use the following code:
<source lang="php">
$paramsdata = $row->params;
$paramsdefs = JPATH_COMPONENT.DS.'models'.DS.'MODEL_NAME.xml';
$params = new JParameter( $paramsdata, $paramsdefs );

$this->assignRef('params', $params);
</source>
This code is typically placed in the View file (e.g. view.html.php) within the corresponding folder.

To display the parameters forms in slider panes (in the same way that they are displayed in the menu item Back-end), you should use the following code in the template file (e.g. <code>PATH_TO_JOOMLA/administrator/com_COMPONENT_NAME/views/VIEW_NAME/tmpl/default.php</code>):
<source lang="php">
$pane =& JPane::getInstance( 'sliders' );

echo $pane->startPane( 'content-pane' );

// First slider panel
// Create a slider panel with a title of SLIDER_PANEL_1_TITLE and a title id attribute of SLIDER_PANEL_1_NAME
echo $pane->startPanel( JText::_( 'SLIDER_PANEL_1_TITLE' ), 'SLIDER_PANEL_1_NAME' );
// Display the parameters defined in the <params> group with no 'group' attribute
echo $this->params->render( 'params' );
echo $pane->endPanel();

//Second slider panel
// Create a slider panel with a title of SLIDER_PANEL_2_TITLE and a title id attribute of SLIDER_PANEL_2_NAME
echo $pane->startPanel( JText::_( 'SLIDER_PANEL_2_TITLE' ), 'SLIDER_PANEL_2_NAME' );
// Display the parameters defined in the <params> group with the 'group' attribute of 'GROUP_NAME'
echo $this->params->render( 'params', 'GROUP_NAME' );
echo $pane->endPanel();

// Repeat for each additional slider panel required

echo $pane->endPane();
</source>
In order to save the parameters to the database you have to overload the bind() function which can be found in
<code>PATH_TO_JOOMLA/administrator/com_COMPONENT_NAME/tables/COMPONENT_NAME.php</code>
<source lang="php">
function bind($array, $ignore = '')
{
if (key_exists( 'params', $array ) && is_array( $array['params'] ))
{
$registry = new JRegistry();
$registry->loadArray($array['params']);
$array['params'] = $registry->toString();
}
return parent::bind($array, $ignore);
}
</source>

==Accessing the parameters - frontend==

The Front-end situation is a bit more complex than the Back-end. The 'standard' way to deal with parameters in the Front-end is to set up a cascade of overrides, as described above:
<blockquote>Item-specific ''overrides'' Menu-specific ''overrides'' Component-default</blockquote>
If you '''don't''' want to do this, then a little extra work is required

===With overrides===

The following code will access the Component-wide default parameters, ''already overridden'' with those for the menu item (if applicable):

<source lang="php">
<?php
$params = &JComponentHelper::getParams( 'COMPONENT_NAME' );

// e.g. for the com_weblinks component, you would use:
// $params = &JComponentHelper::getParams( 'com_weblinks' )
?>
</source>

In an MVC structure, this code would be placed in the <code>view.html.php</code> file for the particular view required.

Assuming that the item parameters are stored in the <code>params</code> field, and that the particular item has been loaded into the <code>$row</code> object by the method, you would then add in the item parameters to the <code>$params</code> object using:

<source lang="php">
<?php
$params->merge( new JParameter( &$row->params ) );
?>
</source>

Note that, in both cases (i.e. overrides by menu-specific parameters, and overrides by item-specific parameters), we aren't ''just'' doing overrides - we also add in any new parameters that weren't found in the defaults. In other words, the <code>$params</code> object ends up with all the parameters we need!

To access the value of a specific parameter, we would use:

<source lang="php">
<?php
$params->get( 'PARAMETER_NAME' );

// e.g. to obtain the value of 'parameter1', we use:
// $params->get( 'parameter1' );
?>
</source>

It is important to realise that any <code>merge</code> carried out is persistent, so the following code (where for example you have an array containing the parameters sets for several items, and you want the parameters for each item to individually override the defaults) would not produce the result you might expect:

<source lang="php">
<?php
foreach ($itemparamsgroup as $itemparams)
{
$params = &JComponentHelper::getParams( 'COMPONENT_NAME' );
$params->merge( $itemparams );
echo $params->get( 'PARAMETER_NAME' );
}
?>
</source>

In such cases, you will need to use the non-override method, and then force the overrides manually, as described below.

===Without overrides===

There will be cases where you don't want to use the default override pattern. For example, you may want to ignore the menu-specific parameters, and have only the item-specific parameters overriding the defaults. This is a little more difficult to accomplish, although it can still be done.

You can access the Component-wide default parameter values, ''without the menu overrides'', as follows:

<source lang="php">
<?php
$component = JComponentHelper::getComponent( 'COMPONENT_NAME' );
$params = new JParameter( $component->params );
?>
</source>

If you want to override these with the menu parameters, but ''without'' the 'persistence' effect described above, you can:

<source lang="php">
<?php
$menuitemid = JRequest::getInt( 'Itemid' );
if ($menuitemid)
{
$menu = JSite::getMenu();
$menuparams = $menu->getParams( $menuitemid );
$params->merge( $menuparams );
}
?>
</source>

You can access the item parameters as before, and choose whether to merge them in using the code above, or simply store them in a separate object:

<source lang="php">
<?php
$itemparams = new JParameter( $row->params );
?>
</source>

You can combine this code to achieve the effect that you want. For example, you could override the Component-wide defaults with the item-specific parameters, but ignore those for the menu. Or you could use the menu-specific parameters in some circumstances, and the item-specific ones in others. [Whenever you depart from the standard approach, though, you should be careful that you inform your users how your Component works. Users will expect your component to work the same way as those from the Joomla! core, so you should have a good reason for departing from this approach.]

Accessing the value of a particular parameter is done in the same way as described above.

<noinclude>[[Category:Development]][[Category:Components]][[Category:Parameters]]</noinclude>

J1.5:Component parameters

2009-09-19T10:18:09Z

JimDeLaHunt: /* 2. Menu item specific parameters */ Clarify that <url> is peer to <params> and also contains <param ... /> elements.

==Background==
One thing that sets Joomla! Components apart from other types of Extension (i.e. Modules and Plugins) is the ability to store significant quantities of data in the Joomla! MySQL database. Typically, this data will be content for displaying on a page (such as the content of an article, or its title) or data about how that content should be displayed (e.g. a setting specifying whether or not the title should be shown). A Component normally creates at least one table in the database to store this data - for example, data for articles associated with the <code>com_content</code> Component are stored in the <code>jos_content</code> table (where ''jos'' is the table prefix for the site).

However, choosing exactly how to store each item of data requires a little more thought. There are essentially two choices: each data item may be stored in its own field, or a collection of data items may be stored within a single parameters field. (Of course, there is nothing to stop you making use of both methods, for different data items, within the same component). Which approach you use for a given data item is largely a matter of personal choice, although there are some factors to consider:
* Core code included in the Joomla! installation makes it very easy to produce the appropriate form elements for entering data into '''parameters''' in the Back-end. If you choose to save the data in separate fields, you will need to code the appropriate form elements yourself.
* Again, Joomla! core code allows you to set default values for '''parameters''' across the whole component. Individual component items (e.g. individual articles) can then choose to use the default values, or to override them with values specific to that item. See below for details of how to do this.
* It is not possible to extract individual parameter values directly from the database. Instead, the whole parameters field must be extracted and parsed to obtain the different parameter values. This means that it is not very easy, for example, to run MySQL queries that search for a parameter with a particular value. Any data that you want to run queries against should be given its '''own table field'''.
* Similarly, it is not possible to run data validation on parameter fields before saving data.
In general, parameters are conventionally used to store data relating to the ''presentation'' of information. The information itself is generally stored in separate fields.

==Types of Component parameter==

===1. Component-wide default parameters===

These parameters are set once for the whole Component, and are generally used to provide the 'default' parameter settings for the Component on that particular site.

===2. Menu item specific parameters===

A menu link to an individual Component item (e.g. an article) can also have parameters associated with it, which can affect the way the Component item is displayed ''using that link''. The types of parameters available will depend on the way that the Component item is displayed (the 'view' in MVC terms, but don't worry if this doesn't mean anything to you!). However, the precise values of those parameters can be set for each menu link individually. If there is another menu link to that same Component item, then it is important to realise each menu link may have different parameter values, and so the same article may be displayed differently in the two cases.

A menu link can also override the Component-wide default parameters, so that the override values (if set) are used in place of the default values ''for that Component item when accessed via that menu link''. As you would expect, when no override value is set, the default value is used instead, in the normal manner.

===3. 'Article' specific parameters===

Finally, each Component item (e.g. article) can have parameters which apply to that item, regardless of how it is accessed (i.e. via any available menu link, or even without reference to a menu at all!). If the Component designer wants, the article specific parameters can also be set up to use the 'override' behaviour, so that they default to the current values of the corresponding Component-wide parameters, though this is not essential. Again, this is described further below.

==Storing the parameters and their values.==

In general, a set of parameters is stored within the database in a single <code>text</code> field. Different parameters are separated by <code>newline</code> characters ('<code>\n</code>' in MySQL - each parameter will appear on a different line when you look at the data in something like phpMyAdmin). Each parameter consists of the parameter name and value, separated by an equals sign (=). As an example:

<source lang="text">
parameter1=parameter1value
parameter2=
parameter3=parameter3value
parameter4=parameter4value
</source>

Here, parameter1, parameter3, and parameter4 have all been assigned values, whilst parameter2 has no value. Typically, a parameter will be given no value where it is set up to allow override of a default value, but 'no override is required' - i.e. it is desired to use the default value.

===1. Component-wide default parameters===

These are stored in the <code>params</code> field of the jos_components table, in the row corresponding to the particular component to which they apply.

===2. Menu item specific parameters===

These are stored in the <code>params</code> field of the jos_menu table, in the row corresponding to the particular menu item to which they apply.

===3. 'Article' specific parameters===

These are stored in a text field in the table created by the Component. Whilst there is no strict rule for naming the field, it is common to extend the above pattern using the <code>params</code> name. However, com_content stores article parameters in a field called <code>attribs</code>.

==Accessing the parameters - Back-end==

Joomla! includes some shortcuts to enable component creators to easily add parameter forms to the Back-end of their component. These forms allow a site administrator to enter a parameter value by, for example, entering some text in a box, choosing from a drop-down list, or selecting a radio button. To create these forms, each parameter needs to have an associated <code><param /></code> object in an XML file. The type of <code><nowiki><param /></nowiki></code> object determines the form elements that will be shown in the Back-end. A list of the available form elements is given [[Standard_parameter_types|here]]. More information is given below about the XML file names, structure and location required for each set of parameters.

===1. Component-wide default parameters===

These can be created at installation of the Component, by including <code><param /></code> elements in the installation XML file (typically called COMPONENT_NAME.xml, and located in the root folder of the Component package. As far as the parameters are concerned, this XML file has the following structure:
<source lang="xml">
<install>
...
<params>
<param />


<param name="font_size" default="16" />

...
</params>
...
</install>
</source>
Each <code><param /></code> element must be given the attributes <code>name</code> and <code>default</code>, which define the parameter name and value respectively. These values are then copied to the jos_components table in the database.

However, on its own this is not very useful, as it doesn't allow users to change the values of the parameters. To do this, parameter form elements need to be defined in a file named <code>config.xml</code> which is located in <code>/PATH_TO_JOOMLA/administrator/components/com_COMPONENT_NAME/</code>. The file should have the following structure:
<source lang="xml">
<root>
<params>
<url addpath="/administrator/components/com_COMPONENT_NAME/elements">
<param name="cid" type="JELEMENT_TYPE_NAME" scope="com_COMPONENT_NAME" default="0" label="LABEL" description="DESCRIPTION" />
</url>
<param type="type" name="name" description="description" />



<param type="text" name="font_size" size="3" label="Font size:" description="Please enter the required font size" />

...
</params>
</root>
</source>
Note that the <code><root></code> element can have any name you wish, but there must be one element at the root of the document (this is a requirement for a well-formed XML document). You can have more than one <code><params></code> element, but only the first one will be considered. It is not currently possible to group certain parameter form elements together.

The url parameter specifies a parameter which is added to the URL of the menu item. To enable this functionality, you must create a new class which extends JElement and put it in the administrator/components/com_COMPONENT_NAME directory. More information here: http://forum.joomla.org/viewtopic.php?f=476&t=206062.

So that administrators to access these parameters, you will need to add a button to the toolbar in the Back-end of your component. This can be done using the code:
<source lang="php">
JToolBarHelper::preferences( 'com_COMPONENT_NAME' );
// e.g. for the core Content component, you would use JToolBarHelper::preferences( 'com_content' );
</source>
which is typically placed in the PHP file responsible for the Back-end output. (For example, using an MVC structure, you might place this code at the top of <code>/PATH_TO_JOOMLA/administrator/components/com_COMPONENT_NAME/views/VIEW_NAME/tmpl/default.php</code>.

This adds a <code>Parameters</code> button to the toolbar:

[[Image:Toolbar_newsfeed.png]]

Clicking on the toolbar button produces a pop-up window containing the form fields for each parameter defined in <code>config.xml</code>.

Note that there is no need to define <code>default</code> attributes for the <code><param /></code> elements in the <code>config.xml</code> file, since the default values will already have been saved in the installation of the Component.

===2. Menu item specific parameters===

A menu item is associated with a particular view from your Component's Front-end - following the menu link in the Front-end will display that view. Joomla! 1.5 allows you to define parameters for a particular view, so that a copy of those parameters can be associated with each menu item using the view. In addition, you can also choose to override the Component-wide default parameters defined as above, so that the override values will apply to the particular menu item.

The view parameters are defined in an XML file stored in the ''Front-end'' view output template directory. (This is not to be confused with the site Template directory, which is different!). The XML file has the same name as the layout used with the template. For must applications you will be using the default layout. Thus the path the XML file is something like: <code>/PATH_TO_JOOMLA/components/com_COMPONENT_NAME/views/VIEW_NAME/tmpl/default.xml</code>. The structure of the file is:
<source lang="xml">
<metadata>
...
<state>
...
<params>
<param />
...
</params>
<url>
<param />
...
</url>
<advanced>
<param />
...
</advanced>
</state>
</metadata>
</source>

See [[Standard parameter types]] for a full list of the core parameter types.

Displaying the forms for these parameters is handled automatically by the core <code>com_menus</code> component, which creates a number of slider panes on the right hand side (at least when viewed using the default Khepri backend site Template) of the menu item edit screen. Any parameters defined within the <code><params></code> or <code><params></code> tags will appear in the <code>Parameters - Basic</code> slider pane. Any parameters defined within the <code><advanced></code> tag will appear in the <code>Parameters - Advanced</code> slider pane.

The following screenshot shows the menu admin page for the Category 'List' layout. You can see that the <code>Parameters - Basic</code> slider pane is open, and contains form elements for five parameters. There are no 'Advanced' parameters for this view, and so the <code>Parameters - Advanced</code> slider pane is not shown:

[[Image:Menu items edit.png]]

For the override of the Component-wide default parameters, <code>com_menus</code> uses the same <code>config.xml</code> file as above, so there is no need to define these parameters again. The override forms are automatically added to a slider pane named <code>Parameters - Component</code>. However, there are a number of changes from the forms used in the Preferences pop-up window (despite being based on the same <code>config.xml</code> file):
* Any <code><param type="radio" /></code> parameter is shown not as a radio button form field, but by a drop-down list.
* All drop-down lists (both those defined as such in <code>config.xml</code>, and those defined as radio buttons) are given an extra option. This extra option displays the text "Use Global" but has an associated value of an empty string. The "Use Global" option is set as the default option for the list. Thus, by default, these parameters will use the Component-wide default values, rather than overriding them. (However, note that any text box fields defined with a default value in <code>config.xml</code> retain that default value, and so will override the component-wide default value if that is different).

===3. 'Article' specific parameters===

These are defined in an XML file which can be stored anywhere you like, but is typically placed within the <code>models</code> folder of the Component Back-end (if you are using an MVC structure) and named according to the model to which they apply, i.e. <code>PATH_TO_JOOMLA/administrator/components/com_COMPONENT_NAME/models/MODEL_NAME.xml</code>. The XML file has the following structure:

<source lang="xml">
<root>
<params>
<param />
...
</params>
<params group="GROUP_NAME">
<param />
...
</params>
...
</root>
</source>

As above, you can give the <code><root></code> element whatever name you wish. You can also have as many <code><params></code> groups as you like, though each group must have a <code>group</code> attribute with a different <code>GROUP_NAME</code>. If there are two or more <code><params></code> groups with the same <code>GROUP_NAME</code>, only the last one in the list will be considered.

To display the forms for these parameters in the Back-end of your Component, you will need to do a little work yourself. Firstly, you need to access the saved parameter data from the database. For this, you will need to identify both the location of the stored parameters data in the database, and the XML file that you are using to define the parameter form fields. Assuming that you have already created a <code>$row</code> variable to hold your component item (i.e. 'article') data, that the parameters data is stored in the <code>params</code> field of the <code>$row</code>, and that the XML file is located in the models folder as specified above, you could use the following code:
<source lang="php">
$paramsdata = $row->params;
$paramsdefs = JPATH_COMPONENT.DS.'models'.DS.'MODEL_NAME.xml';
$params = new JParameter( $paramsdata, $paramsdefs );

$this->assignRef('params', $params);
</source>
This code is typically placed in the View file (e.g. view.html.php) within the corresponding folder.

To display the parameters forms in slider panes (in the same way that they are displayed in the menu item Back-end), you should use the following code in the template file (e.g. <code>PATH_TO_JOOMLA/administrator/com_COMPONENT_NAME/views/VIEW_NAME/tmpl/default.php</code>):
<source lang="php">
$pane =& JPane::getInstance( 'sliders' );

echo $pane->startPane( 'content-pane' );

// First slider panel
// Create a slider panel with a title of SLIDER_PANEL_1_TITLE and a title id attribute of SLIDER_PANEL_1_NAME
echo $pane->startPanel( JText::_( 'SLIDER_PANEL_1_TITLE' ), 'SLIDER_PANEL_1_NAME' );
// Display the parameters defined in the <params> group with no 'group' attribute
echo $this->params->render( 'params' );
echo $pane->endPanel();

//Second slider panel
// Create a slider panel with a title of SLIDER_PANEL_2_TITLE and a title id attribute of SLIDER_PANEL_2_NAME
echo $pane->startPanel( JText::_( 'SLIDER_PANEL_2_TITLE' ), 'SLIDER_PANEL_2_NAME' );
// Display the parameters defined in the <params> group with the 'group' attribute of 'GROUP_NAME'
echo $this->params->render( 'params', 'GROUP_NAME' );
echo $pane->endPanel();

// Repeat for each additional slider panel required

echo $pane->endPane();
</source>
In order to save the parameters to the database you have to overload the bind() function which can be found in
<code>PATH_TO_JOOMLA/administrator/com_COMPONENT_NAME/tables/COMPONENT_NAME.php</code>
<source lang="php">
function bind($array, $ignore = '')
{
if (key_exists( 'params', $array ) && is_array( $array['params'] ))
{
$registry = new JRegistry();
$registry->loadArray($array['params']);
$array['params'] = $registry->toString();
}
return parent::bind($array, $ignore);
}
</source>

==Accessing the parameters - frontend==

The Front-end situation is a bit more complex than the Back-end. The 'standard' way to deal with parameters in the Front-end is to set up a cascade of overrides, as described above:
<blockquote>Item-specific ''overrides'' Menu-specific ''overrides'' Component-default</blockquote>
If you '''don't''' want to do this, then a little extra work is required

===With overrides===

The following code will access the Component-wide default parameters, ''already overridden'' with those for the menu item (if applicable):

<source lang="php">
<?php
$params = &JComponentHelper::getParams( 'COMPONENT_NAME' );

// e.g. for the com_weblinks component, you would use:
// $params = &JComponentHelper::getParams( 'com_weblinks' )
?>
</source>

In an MVC structure, this code would be placed in the <code>view.html.php</code> file for the particular view required.

Assuming that the item parameters are stored in the <code>params</code> field, and that the particular item has been loaded into the <code>$row</code> object by the method, you would then add in the item parameters to the <code>$params</code> object using:

<source lang="php">
<?php
$params->merge( new JParameter( &$row->params ) );
?>
</source>

Note that, in both cases (i.e. overrides by menu-specific parameters, and overrides by item-specific parameters), we aren't ''just'' doing overrides - we also add in any new parameters that weren't found in the defaults. In other words, the <code>$params</code> object ends up with all the parameters we need!

To access the value of a specific parameter, we would use:

<source lang="php">
<?php
$params->get( 'PARAMETER_NAME' );

// e.g. to obtain the value of 'parameter1', we use:
// $params->get( 'parameter1' );
?>
</source>

It is important to realise that any <code>merge</code> carried out is persistent, so the following code (where for example you have an array containing the parameters sets for several items, and you want the parameters for each item to individually override the defaults) would not produce the result you might expect:

<source lang="php">
<?php
foreach ($itemparamsgroup as $itemparams)
{
$params = &JComponentHelper::getParams( 'COMPONENT_NAME' );
$params->merge( $itemparams );
echo $params->get( 'PARAMETER_NAME' );
}
?>
</source>

In such cases, you will need to use the non-override method, and then force the overrides manually, as described below.

===Without overrides===

There will be cases where you don't want to use the default override pattern. For example, you may want to ignore the menu-specific parameters, and have only the item-specific parameters overriding the defaults. This is a little more difficult to accomplish, although it can still be done.

You can access the Component-wide default parameter values, ''without the menu overrides'', as follows:

<source lang="php">
<?php
$component = JComponentHelper::getComponent( 'COMPONENT_NAME' );
$params = new JParameter( $component->params );
?>
</source>

If you want to override these with the menu parameters, but ''without'' the 'persistence' effect described above, you can:

<source lang="php">
<?php
$menuitemid = JRequest::getInt( 'Itemid' );
if ($menuitemid)
{
$menu = JSite::getMenu();
$menuparams = $menu->getParams( $menuitemid );
$params->merge( $menuparams );
}
?>
</source>

You can access the item parameters as before, and choose whether to merge them in using the code above, or simply store them in a separate object:

<source lang="php">
<?php
$itemparams = new JParameter( $row->params );
?>
</source>

You can combine this code to achieve the effect that you want. For example, you could override the Component-wide defaults with the item-specific parameters, but ignore those for the menu. Or you could use the menu-specific parameters in some circumstances, and the item-specific ones in others. [Whenever you depart from the standard approach, though, you should be careful that you inform your users how your Component works. Users will expect your component to work the same way as those from the Joomla! core, so you should have a good reason for departing from this approach.]

Accessing the value of a particular parameter is done in the same way as described above.

<noinclude>[[Category:Development]][[Category:Components]][[Category:Parameters]]</noinclude>

J1.5:Component parameters

2009-09-19T08:49:30Z

JimDeLaHunt: /* 2. Menu item specific parameters */ Clarified path of the XML file.

==Background==
One thing that sets Joomla! Components apart from other types of Extension (i.e. Modules and Plugins) is the ability to store significant quantities of data in the Joomla! MySQL database. Typically, this data will be content for displaying on a page (such as the content of an article, or its title) or data about how that content should be displayed (e.g. a setting specifying whether or not the title should be shown). A Component normally creates at least one table in the database to store this data - for example, data for articles associated with the <code>com_content</code> Component are stored in the <code>jos_content</code> table (where ''jos'' is the table prefix for the site).

However, choosing exactly how to store each item of data requires a little more thought. There are essentially two choices: each data item may be stored in its own field, or a collection of data items may be stored within a single parameters field. (Of course, there is nothing to stop you making use of both methods, for different data items, within the same component). Which approach you use for a given data item is largely a matter of personal choice, although there are some factors to consider:
* Core code included in the Joomla! installation makes it very easy to produce the appropriate form elements for entering data into '''parameters''' in the Back-end. If you choose to save the data in separate fields, you will need to code the appropriate form elements yourself.
* Again, Joomla! core code allows you to set default values for '''parameters''' across the whole component. Individual component items (e.g. individual articles) can then choose to use the default values, or to override them with values specific to that item. See below for details of how to do this.
* It is not possible to extract individual parameter values directly from the database. Instead, the whole parameters field must be extracted and parsed to obtain the different parameter values. This means that it is not very easy, for example, to run MySQL queries that search for a parameter with a particular value. Any data that you want to run queries against should be given its '''own table field'''.
* Similarly, it is not possible to run data validation on parameter fields before saving data.
In general, parameters are conventionally used to store data relating to the ''presentation'' of information. The information itself is generally stored in separate fields.

==Types of Component parameter==

===1. Component-wide default parameters===

These parameters are set once for the whole Component, and are generally used to provide the 'default' parameter settings for the Component on that particular site.

===2. Menu item specific parameters===

A menu link to an individual Component item (e.g. an article) can also have parameters associated with it, which can affect the way the Component item is displayed ''using that link''. The types of parameters available will depend on the way that the Component item is displayed (the 'view' in MVC terms, but don't worry if this doesn't mean anything to you!). However, the precise values of those parameters can be set for each menu link individually. If there is another menu link to that same Component item, then it is important to realise each menu link may have different parameter values, and so the same article may be displayed differently in the two cases.

A menu link can also override the Component-wide default parameters, so that the override values (if set) are used in place of the default values ''for that Component item when accessed via that menu link''. As you would expect, when no override value is set, the default value is used instead, in the normal manner.

===3. 'Article' specific parameters===

Finally, each Component item (e.g. article) can have parameters which apply to that item, regardless of how it is accessed (i.e. via any available menu link, or even without reference to a menu at all!). If the Component designer wants, the article specific parameters can also be set up to use the 'override' behaviour, so that they default to the current values of the corresponding Component-wide parameters, though this is not essential. Again, this is described further below.

==Storing the parameters and their values.==

In general, a set of parameters is stored within the database in a single <code>text</code> field. Different parameters are separated by <code>newline</code> characters ('<code>\n</code>' in MySQL - each parameter will appear on a different line when you look at the data in something like phpMyAdmin). Each parameter consists of the parameter name and value, separated by an equals sign (=). As an example:

<source lang="text">
parameter1=parameter1value
parameter2=
parameter3=parameter3value
parameter4=parameter4value
</source>

Here, parameter1, parameter3, and parameter4 have all been assigned values, whilst parameter2 has no value. Typically, a parameter will be given no value where it is set up to allow override of a default value, but 'no override is required' - i.e. it is desired to use the default value.

===1. Component-wide default parameters===

These are stored in the <code>params</code> field of the jos_components table, in the row corresponding to the particular component to which they apply.

===2. Menu item specific parameters===

These are stored in the <code>params</code> field of the jos_menu table, in the row corresponding to the particular menu item to which they apply.

===3. 'Article' specific parameters===

These are stored in a text field in the table created by the Component. Whilst there is no strict rule for naming the field, it is common to extend the above pattern using the <code>params</code> name. However, com_content stores article parameters in a field called <code>attribs</code>.

==Accessing the parameters - Back-end==

Joomla! includes some shortcuts to enable component creators to easily add parameter forms to the Back-end of their component. These forms allow a site administrator to enter a parameter value by, for example, entering some text in a box, choosing from a drop-down list, or selecting a radio button. To create these forms, each parameter needs to have an associated <code><param /></code> object in an XML file. The type of <code><nowiki><param /></nowiki></code> object determines the form elements that will be shown in the Back-end. A list of the available form elements is given [[Standard_parameter_types|here]]. More information is given below about the XML file names, structure and location required for each set of parameters.

===1. Component-wide default parameters===

These can be created at installation of the Component, by including <code><param /></code> elements in the installation XML file (typically called COMPONENT_NAME.xml, and located in the root folder of the Component package. As far as the parameters are concerned, this XML file has the following structure:
<source lang="xml">
<install>
...
<params>
<param />


<param name="font_size" default="16" />

...
</params>
...
</install>
</source>
Each <code><param /></code> element must be given the attributes <code>name</code> and <code>default</code>, which define the parameter name and value respectively. These values are then copied to the jos_components table in the database.

However, on its own this is not very useful, as it doesn't allow users to change the values of the parameters. To do this, parameter form elements need to be defined in a file named <code>config.xml</code> which is located in <code>/PATH_TO_JOOMLA/administrator/components/com_COMPONENT_NAME/</code>. The file should have the following structure:
<source lang="xml">
<root>
<params>
<url addpath="/administrator/components/com_COMPONENT_NAME/elements">
<param name="cid" type="JELEMENT_TYPE_NAME" scope="com_COMPONENT_NAME" default="0" label="LABEL" description="DESCRIPTION" />
</url>
<param type="type" name="name" description="description" />



<param type="text" name="font_size" size="3" label="Font size:" description="Please enter the required font size" />

...
</params>
</root>
</source>
Note that the <code><root></code> element can have any name you wish, but there must be one element at the root of the document (this is a requirement for a well-formed XML document). You can have more than one <code><params></code> element, but only the first one will be considered. It is not currently possible to group certain parameter form elements together.

The url parameter specifies a parameter which is added to the URL of the menu item. To enable this functionality, you must create a new class which extends JElement and put it in the administrator/components/com_COMPONENT_NAME directory. More information here: http://forum.joomla.org/viewtopic.php?f=476&t=206062.

So that administrators to access these parameters, you will need to add a button to the toolbar in the Back-end of your component. This can be done using the code:
<source lang="php">
JToolBarHelper::preferences( 'com_COMPONENT_NAME' );
// e.g. for the core Content component, you would use JToolBarHelper::preferences( 'com_content' );
</source>
which is typically placed in the PHP file responsible for the Back-end output. (For example, using an MVC structure, you might place this code at the top of <code>/PATH_TO_JOOMLA/administrator/components/com_COMPONENT_NAME/views/VIEW_NAME/tmpl/default.php</code>.

This adds a <code>Parameters</code> button to the toolbar:

[[Image:Toolbar_newsfeed.png]]

Clicking on the toolbar button produces a pop-up window containing the form fields for each parameter defined in <code>config.xml</code>.

Note that there is no need to define <code>default</code> attributes for the <code><param /></code> elements in the <code>config.xml</code> file, since the default values will already have been saved in the installation of the Component.

===2. Menu item specific parameters===

A menu item is associated with a particular view from your Component's Front-end - following the menu link in the Front-end will display that view. Joomla! 1.5 allows you to define parameters for a particular view, so that a copy of those parameters can be associated with each menu item using the view. In addition, you can also choose to override the Component-wide default parameters defined as above, so that the override values will apply to the particular menu item.

The view parameters are defined in an XML file stored in the ''Front-end'' view output template directory. (This is not to be confused with the site Template directory, which is different!). The XML file has the same name as the layout used with the template. For must applications you will be using the default layout. Thus the path the XML file is something like: <code>/PATH_TO_JOOMLA/components/com_COMPONENT_NAME/views/VIEW_NAME/tmpl/default.xml</code>. The structure of the file is:
<source lang="xml">
<metadata>
...
<state>
...
<params>
<param />
...
</params>
<advanced>
<param />
...
</advanced>
</state>
</metadata>
</source>

See [[Standard parameter types]] for a full list of the core parameter types.

Displaying the forms for these parameters is handled automatically by the core <code>com_menus</code> component, which creates a number of slider panes on the right hand side (at least when viewed using the default Khepri backend site Template) of the menu item edit screen. Any parameters defined within the <code><params></code> tag will appear in the <code>Parameters - Basic</code> slider pane. Any parameters defined within the <code><advanced></code> tag will appear in the <code>Parameters - Advanced</code> slider pane.

The following screenshot shows the menu admin page for the Category 'List' layout. You can see that the <code>Parameters - Basic</code> slider pane is open, and contains form elements for five parameters. There are no 'Advanced' parameters for this view, and so the <code>Parameters - Advanced</code> slider pane is not shown:

[[Image:Menu items edit.png]]

For the override of the Component-wide default parameters, <code>com_menus</code> uses the same <code>config.xml</code> file as above, so there is no need to define these parameters again. The override forms are automatically added to a slider pane named <code>Parameters - Component</code>. However, there are a number of changes from the forms used in the Preferences pop-up window (despite being based on the same <code>config.xml</code> file):
* Any <code><param type="radio" /></code> parameter is shown not as a radio button form field, but by a drop-down list.
* All drop-down lists (both those defined as such in <code>config.xml</code>, and those defined as radio buttons) are given an extra option. This extra option displays the text "Use Global" but has an associated value of an empty string. The "Use Global" option is set as the default option for the list. Thus, by default, these parameters will use the Component-wide default values, rather than overriding them. (However, note that any text box fields defined with a default value in <code>config.xml</code> retain that default value, and so will override the component-wide default value if that is different).

===3. 'Article' specific parameters===

These are defined in an XML file which can be stored anywhere you like, but is typically placed within the <code>models</code> folder of the Component Back-end (if you are using an MVC structure) and named according to the model to which they apply, i.e. <code>PATH_TO_JOOMLA/administrator/components/com_COMPONENT_NAME/models/MODEL_NAME.xml</code>. The XML file has the following structure:

<source lang="xml">
<root>
<params>
<param />
...
</params>
<params group="GROUP_NAME">
<param />
...
</params>
...
</root>
</source>

As above, you can give the <code><root></code> element whatever name you wish. You can also have as many <code><params></code> groups as you like, though each group must have a <code>group</code> attribute with a different <code>GROUP_NAME</code>. If there are two or more <code><params></code> groups with the same <code>GROUP_NAME</code>, only the last one in the list will be considered.

To display the forms for these parameters in the Back-end of your Component, you will need to do a little work yourself. Firstly, you need to access the saved parameter data from the database. For this, you will need to identify both the location of the stored parameters data in the database, and the XML file that you are using to define the parameter form fields. Assuming that you have already created a <code>$row</code> variable to hold your component item (i.e. 'article') data, that the parameters data is stored in the <code>params</code> field of the <code>$row</code>, and that the XML file is located in the models folder as specified above, you could use the following code:
<source lang="php">
$paramsdata = $row->params;
$paramsdefs = JPATH_COMPONENT.DS.'models'.DS.'MODEL_NAME.xml';
$params = new JParameter( $paramsdata, $paramsdefs );

$this->assignRef('params', $params);
</source>
This code is typically placed in the View file (e.g. view.html.php) within the corresponding folder.

To display the parameters forms in slider panes (in the same way that they are displayed in the menu item Back-end), you should use the following code in the template file (e.g. <code>PATH_TO_JOOMLA/administrator/com_COMPONENT_NAME/views/VIEW_NAME/tmpl/default.php</code>):
<source lang="php">
$pane =& JPane::getInstance( 'sliders' );

echo $pane->startPane( 'content-pane' );

// First slider panel
// Create a slider panel with a title of SLIDER_PANEL_1_TITLE and a title id attribute of SLIDER_PANEL_1_NAME
echo $pane->startPanel( JText::_( 'SLIDER_PANEL_1_TITLE' ), 'SLIDER_PANEL_1_NAME' );
// Display the parameters defined in the <params> group with no 'group' attribute
echo $this->params->render( 'params' );
echo $pane->endPanel();

//Second slider panel
// Create a slider panel with a title of SLIDER_PANEL_2_TITLE and a title id attribute of SLIDER_PANEL_2_NAME
echo $pane->startPanel( JText::_( 'SLIDER_PANEL_2_TITLE' ), 'SLIDER_PANEL_2_NAME' );
// Display the parameters defined in the <params> group with the 'group' attribute of 'GROUP_NAME'
echo $this->params->render( 'params', 'GROUP_NAME' );
echo $pane->endPanel();

// Repeat for each additional slider panel required

echo $pane->endPane();
</source>
In order to save the parameters to the database you have to overload the bind() function which can be found in
<code>PATH_TO_JOOMLA/administrator/com_COMPONENT_NAME/tables/COMPONENT_NAME.php</code>
<source lang="php">
function bind($array, $ignore = '')
{
if (key_exists( 'params', $array ) && is_array( $array['params'] ))
{
$registry = new JRegistry();
$registry->loadArray($array['params']);
$array['params'] = $registry->toString();
}
return parent::bind($array, $ignore);
}
</source>

==Accessing the parameters - frontend==

The Front-end situation is a bit more complex than the Back-end. The 'standard' way to deal with parameters in the Front-end is to set up a cascade of overrides, as described above:
<blockquote>Item-specific ''overrides'' Menu-specific ''overrides'' Component-default</blockquote>
If you '''don't''' want to do this, then a little extra work is required

===With overrides===

The following code will access the Component-wide default parameters, ''already overridden'' with those for the menu item (if applicable):

<source lang="php">
<?php
$params = &JComponentHelper::getParams( 'COMPONENT_NAME' );

// e.g. for the com_weblinks component, you would use:
// $params = &JComponentHelper::getParams( 'com_weblinks' )
?>
</source>

In an MVC structure, this code would be placed in the <code>view.html.php</code> file for the particular view required.

Assuming that the item parameters are stored in the <code>params</code> field, and that the particular item has been loaded into the <code>$row</code> object by the method, you would then add in the item parameters to the <code>$params</code> object using:

<source lang="php">
<?php
$params->merge( new JParameter( &$row->params ) );
?>
</source>

Note that, in both cases (i.e. overrides by menu-specific parameters, and overrides by item-specific parameters), we aren't ''just'' doing overrides - we also add in any new parameters that weren't found in the defaults. In other words, the <code>$params</code> object ends up with all the parameters we need!

To access the value of a specific parameter, we would use:

<source lang="php">
<?php
$params->get( 'PARAMETER_NAME' );

// e.g. to obtain the value of 'parameter1', we use:
// $params->get( 'parameter1' );
?>
</source>

It is important to realise that any <code>merge</code> carried out is persistent, so the following code (where for example you have an array containing the parameters sets for several items, and you want the parameters for each item to individually override the defaults) would not produce the result you might expect:

<source lang="php">
<?php
foreach ($itemparamsgroup as $itemparams)
{
$params = &JComponentHelper::getParams( 'COMPONENT_NAME' );
$params->merge( $itemparams );
echo $params->get( 'PARAMETER_NAME' );
}
?>
</source>

In such cases, you will need to use the non-override method, and then force the overrides manually, as described below.

===Without overrides===

There will be cases where you don't want to use the default override pattern. For example, you may want to ignore the menu-specific parameters, and have only the item-specific parameters overriding the defaults. This is a little more difficult to accomplish, although it can still be done.

You can access the Component-wide default parameter values, ''without the menu overrides'', as follows:

<source lang="php">
<?php
$component = JComponentHelper::getComponent( 'COMPONENT_NAME' );
$params = new JParameter( $component->params );
?>
</source>

If you want to override these with the menu parameters, but ''without'' the 'persistence' effect described above, you can:

<source lang="php">
<?php
$menuitemid = JRequest::getInt( 'Itemid' );
if ($menuitemid)
{
$menu = JSite::getMenu();
$menuparams = $menu->getParams( $menuitemid );
$params->merge( $menuparams );
}
?>
</source>

You can access the item parameters as before, and choose whether to merge them in using the code above, or simply store them in a separate object:

<source lang="php">
<?php
$itemparams = new JParameter( $row->params );
?>
</source>

You can combine this code to achieve the effect that you want. For example, you could override the Component-wide defaults with the item-specific parameters, but ignore those for the menu. Or you could use the menu-specific parameters in some circumstances, and the item-specific ones in others. [Whenever you depart from the standard approach, though, you should be careful that you inform your users how your Component works. Users will expect your component to work the same way as those from the Joomla! core, so you should have a good reason for departing from this approach.]

Accessing the value of a particular parameter is done in the same way as described above.

<noinclude>[[Category:Development]][[Category:Components]][[Category:Parameters]]</noinclude>

J1.5:Component parameters

2009-09-19T08:09:15Z

JimDeLaHunt: /* 2. Menu item specific parameters */ Change instructions for xml file name from TEMPLATE_NAME.xml to default.xml

==Background==
One thing that sets Joomla! Components apart from other types of Extension (i.e. Modules and Plugins) is the ability to store significant quantities of data in the Joomla! MySQL database. Typically, this data will be content for displaying on a page (such as the content of an article, or its title) or data about how that content should be displayed (e.g. a setting specifying whether or not the title should be shown). A Component normally creates at least one table in the database to store this data - for example, data for articles associated with the <code>com_content</code> Component are stored in the <code>jos_content</code> table (where ''jos'' is the table prefix for the site).

However, choosing exactly how to store each item of data requires a little more thought. There are essentially two choices: each data item may be stored in its own field, or a collection of data items may be stored within a single parameters field. (Of course, there is nothing to stop you making use of both methods, for different data items, within the same component). Which approach you use for a given data item is largely a matter of personal choice, although there are some factors to consider:
* Core code included in the Joomla! installation makes it very easy to produce the appropriate form elements for entering data into '''parameters''' in the Back-end. If you choose to save the data in separate fields, you will need to code the appropriate form elements yourself.
* Again, Joomla! core code allows you to set default values for '''parameters''' across the whole component. Individual component items (e.g. individual articles) can then choose to use the default values, or to override them with values specific to that item. See below for details of how to do this.
* It is not possible to extract individual parameter values directly from the database. Instead, the whole parameters field must be extracted and parsed to obtain the different parameter values. This means that it is not very easy, for example, to run MySQL queries that search for a parameter with a particular value. Any data that you want to run queries against should be given its '''own table field'''.
* Similarly, it is not possible to run data validation on parameter fields before saving data.
In general, parameters are conventionally used to store data relating to the ''presentation'' of information. The information itself is generally stored in separate fields.

==Types of Component parameter==

===1. Component-wide default parameters===

These parameters are set once for the whole Component, and are generally used to provide the 'default' parameter settings for the Component on that particular site.

===2. Menu item specific parameters===

A menu link to an individual Component item (e.g. an article) can also have parameters associated with it, which can affect the way the Component item is displayed ''using that link''. The types of parameters available will depend on the way that the Component item is displayed (the 'view' in MVC terms, but don't worry if this doesn't mean anything to you!). However, the precise values of those parameters can be set for each menu link individually. If there is another menu link to that same Component item, then it is important to realise each menu link may have different parameter values, and so the same article may be displayed differently in the two cases.

A menu link can also override the Component-wide default parameters, so that the override values (if set) are used in place of the default values ''for that Component item when accessed via that menu link''. As you would expect, when no override value is set, the default value is used instead, in the normal manner.

===3. 'Article' specific parameters===

Finally, each Component item (e.g. article) can have parameters which apply to that item, regardless of how it is accessed (i.e. via any available menu link, or even without reference to a menu at all!). If the Component designer wants, the article specific parameters can also be set up to use the 'override' behaviour, so that they default to the current values of the corresponding Component-wide parameters, though this is not essential. Again, this is described further below.

==Storing the parameters and their values.==

In general, a set of parameters is stored within the database in a single <code>text</code> field. Different parameters are separated by <code>newline</code> characters ('<code>\n</code>' in MySQL - each parameter will appear on a different line when you look at the data in something like phpMyAdmin). Each parameter consists of the parameter name and value, separated by an equals sign (=). As an example:

<source lang="text">
parameter1=parameter1value
parameter2=
parameter3=parameter3value
parameter4=parameter4value
</source>

Here, parameter1, parameter3, and parameter4 have all been assigned values, whilst parameter2 has no value. Typically, a parameter will be given no value where it is set up to allow override of a default value, but 'no override is required' - i.e. it is desired to use the default value.

===1. Component-wide default parameters===

These are stored in the <code>params</code> field of the jos_components table, in the row corresponding to the particular component to which they apply.

===2. Menu item specific parameters===

These are stored in the <code>params</code> field of the jos_menu table, in the row corresponding to the particular menu item to which they apply.

===3. 'Article' specific parameters===

These are stored in a text field in the table created by the Component. Whilst there is no strict rule for naming the field, it is common to extend the above pattern using the <code>params</code> name. However, com_content stores article parameters in a field called <code>attribs</code>.

==Accessing the parameters - Back-end==

Joomla! includes some shortcuts to enable component creators to easily add parameter forms to the Back-end of their component. These forms allow a site administrator to enter a parameter value by, for example, entering some text in a box, choosing from a drop-down list, or selecting a radio button. To create these forms, each parameter needs to have an associated <code><param /></code> object in an XML file. The type of <code><nowiki><param /></nowiki></code> object determines the form elements that will be shown in the Back-end. A list of the available form elements is given [[Standard_parameter_types|here]]. More information is given below about the XML file names, structure and location required for each set of parameters.

===1. Component-wide default parameters===

These can be created at installation of the Component, by including <code><param /></code> elements in the installation XML file (typically called COMPONENT_NAME.xml, and located in the root folder of the Component package. As far as the parameters are concerned, this XML file has the following structure:
<source lang="xml">
<install>
...
<params>
<param />


<param name="font_size" default="16" />

...
</params>
...
</install>
</source>
Each <code><param /></code> element must be given the attributes <code>name</code> and <code>default</code>, which define the parameter name and value respectively. These values are then copied to the jos_components table in the database.

However, on its own this is not very useful, as it doesn't allow users to change the values of the parameters. To do this, parameter form elements need to be defined in a file named <code>config.xml</code> which is located in <code>/PATH_TO_JOOMLA/administrator/components/com_COMPONENT_NAME/</code>. The file should have the following structure:
<source lang="xml">
<root>
<params>
<url addpath="/administrator/components/com_COMPONENT_NAME/elements">
<param name="cid" type="JELEMENT_TYPE_NAME" scope="com_COMPONENT_NAME" default="0" label="LABEL" description="DESCRIPTION" />
</url>
<param type="type" name="name" description="description" />



<param type="text" name="font_size" size="3" label="Font size:" description="Please enter the required font size" />

...
</params>
</root>
</source>
Note that the <code><root></code> element can have any name you wish, but there must be one element at the root of the document (this is a requirement for a well-formed XML document). You can have more than one <code><params></code> element, but only the first one will be considered. It is not currently possible to group certain parameter form elements together.

The url parameter specifies a parameter which is added to the URL of the menu item. To enable this functionality, you must create a new class which extends JElement and put it in the administrator/components/com_COMPONENT_NAME directory. More information here: http://forum.joomla.org/viewtopic.php?f=476&t=206062.

So that administrators to access these parameters, you will need to add a button to the toolbar in the Back-end of your component. This can be done using the code:
<source lang="php">
JToolBarHelper::preferences( 'com_COMPONENT_NAME' );
// e.g. for the core Content component, you would use JToolBarHelper::preferences( 'com_content' );
</source>
which is typically placed in the PHP file responsible for the Back-end output. (For example, using an MVC structure, you might place this code at the top of <code>/PATH_TO_JOOMLA/administrator/components/com_COMPONENT_NAME/views/VIEW_NAME/tmpl/default.php</code>.

This adds a <code>Parameters</code> button to the toolbar:

[[Image:Toolbar_newsfeed.png]]

Clicking on the toolbar button produces a pop-up window containing the form fields for each parameter defined in <code>config.xml</code>.

Note that there is no need to define <code>default</code> attributes for the <code><param /></code> elements in the <code>config.xml</code> file, since the default values will already have been saved in the installation of the Component.

===2. Menu item specific parameters===

A menu item is associated with a particular view from your Component's Front-end - following the menu link in the Front-end will display that view. Joomla! 1.5 allows you to define parameters for a particular view, so that a copy of those parameters can be associated with each menu item using the view. In addition, you can also choose to override the Component-wide default parameters defined as above, so that the override values will apply to the particular menu item.

The view parameters are defined in an XML file stored in the ''Front-end'' view output template (not to be confused with the site Template, which is different!) directory and with the same name as the template, i.e. <code>/PATH_TO_JOOMLA/components/com_COMPONENT_NAME/views/VIEW_NAME/tmpl/default.xml</code>. The structure of the file is:
<source lang="xml">
<metadata>
...
<state>
...
<params>
<param />
...
</params>
<advanced>
<param />
...
</advanced>
</state>
</metadata>
</source>

See [[Standard parameter types]] for a full list of the core parameter types.

Displaying the forms for these parameters is handled automatically by the core <code>com_menus</code> component, which creates a number of slider panes on the right hand side (at least when viewed using the default Khepri backend site Template) of the menu item edit screen. Any parameters defined within the <code><params></code> tag will appear in the <code>Parameters - Basic</code> slider pane. Any parameters defined within the <code><advanced></code> tag will appear in the <code>Parameters - Advanced</code> slider pane.

The following screenshot shows the menu admin page for the Category 'List' layout. You can see that the <code>Parameters - Basic</code> slider pane is open, and contains form elements for five parameters. There are no 'Advanced' parameters for this view, and so the <code>Parameters - Advanced</code> slider pane is not shown:

[[Image:Menu items edit.png]]

For the override of the Component-wide default parameters, <code>com_menus</code> uses the same <code>config.xml</code> file as above, so there is no need to define these parameters again. The override forms are automatically added to a slider pane named <code>Parameters - Component</code>. However, there are a number of changes from the forms used in the Preferences pop-up window (despite being based on the same <code>config.xml</code> file):
* Any <code><param type="radio" /></code> parameter is shown not as a radio button form field, but by a drop-down list.
* All drop-down lists (both those defined as such in <code>config.xml</code>, and those defined as radio buttons) are given an extra option. This extra option displays the text "Use Global" but has an associated value of an empty string. The "Use Global" option is set as the default option for the list. Thus, by default, these parameters will use the Component-wide default values, rather than overriding them. (However, note that any text box fields defined with a default value in <code>config.xml</code> retain that default value, and so will override the component-wide default value if that is different).

===3. 'Article' specific parameters===

These are defined in an XML file which can be stored anywhere you like, but is typically placed within the <code>models</code> folder of the Component Back-end (if you are using an MVC structure) and named according to the model to which they apply, i.e. <code>PATH_TO_JOOMLA/administrator/components/com_COMPONENT_NAME/models/MODEL_NAME.xml</code>. The XML file has the following structure:

<source lang="xml">
<root>
<params>
<param />
...
</params>
<params group="GROUP_NAME">
<param />
...
</params>
...
</root>
</source>

As above, you can give the <code><root></code> element whatever name you wish. You can also have as many <code><params></code> groups as you like, though each group must have a <code>group</code> attribute with a different <code>GROUP_NAME</code>. If there are two or more <code><params></code> groups with the same <code>GROUP_NAME</code>, only the last one in the list will be considered.

To display the forms for these parameters in the Back-end of your Component, you will need to do a little work yourself. Firstly, you need to access the saved parameter data from the database. For this, you will need to identify both the location of the stored parameters data in the database, and the XML file that you are using to define the parameter form fields. Assuming that you have already created a <code>$row</code> variable to hold your component item (i.e. 'article') data, that the parameters data is stored in the <code>params</code> field of the <code>$row</code>, and that the XML file is located in the models folder as specified above, you could use the following code:
<source lang="php">
$paramsdata = $row->params;
$paramsdefs = JPATH_COMPONENT.DS.'models'.DS.'MODEL_NAME.xml';
$params = new JParameter( $paramsdata, $paramsdefs );

$this->assignRef('params', $params);
</source>
This code is typically placed in the View file (e.g. view.html.php) within the corresponding folder.

To display the parameters forms in slider panes (in the same way that they are displayed in the menu item Back-end), you should use the following code in the template file (e.g. <code>PATH_TO_JOOMLA/administrator/com_COMPONENT_NAME/views/VIEW_NAME/tmpl/default.php</code>):
<source lang="php">
$pane =& JPane::getInstance( 'sliders' );

echo $pane->startPane( 'content-pane' );

// First slider panel
// Create a slider panel with a title of SLIDER_PANEL_1_TITLE and a title id attribute of SLIDER_PANEL_1_NAME
echo $pane->startPanel( JText::_( 'SLIDER_PANEL_1_TITLE' ), 'SLIDER_PANEL_1_NAME' );
// Display the parameters defined in the <params> group with no 'group' attribute
echo $this->params->render( 'params' );
echo $pane->endPanel();

//Second slider panel
// Create a slider panel with a title of SLIDER_PANEL_2_TITLE and a title id attribute of SLIDER_PANEL_2_NAME
echo $pane->startPanel( JText::_( 'SLIDER_PANEL_2_TITLE' ), 'SLIDER_PANEL_2_NAME' );
// Display the parameters defined in the <params> group with the 'group' attribute of 'GROUP_NAME'
echo $this->params->render( 'params', 'GROUP_NAME' );
echo $pane->endPanel();

// Repeat for each additional slider panel required

echo $pane->endPane();
</source>
In order to save the parameters to the database you have to overload the bind() function which can be found in
<code>PATH_TO_JOOMLA/administrator/com_COMPONENT_NAME/tables/COMPONENT_NAME.php</code>
<source lang="php">
function bind($array, $ignore = '')
{
if (key_exists( 'params', $array ) && is_array( $array['params'] ))
{
$registry = new JRegistry();
$registry->loadArray($array['params']);
$array['params'] = $registry->toString();
}
return parent::bind($array, $ignore);
}
</source>

==Accessing the parameters - frontend==

The Front-end situation is a bit more complex than the Back-end. The 'standard' way to deal with parameters in the Front-end is to set up a cascade of overrides, as described above:
<blockquote>Item-specific ''overrides'' Menu-specific ''overrides'' Component-default</blockquote>
If you '''don't''' want to do this, then a little extra work is required

===With overrides===

The following code will access the Component-wide default parameters, ''already overridden'' with those for the menu item (if applicable):

<source lang="php">
<?php
$params = &JComponentHelper::getParams( 'COMPONENT_NAME' );

// e.g. for the com_weblinks component, you would use:
// $params = &JComponentHelper::getParams( 'com_weblinks' )
?>
</source>

In an MVC structure, this code would be placed in the <code>view.html.php</code> file for the particular view required.

Assuming that the item parameters are stored in the <code>params</code> field, and that the particular item has been loaded into the <code>$row</code> object by the method, you would then add in the item parameters to the <code>$params</code> object using:

<source lang="php">
<?php
$params->merge( new JParameter( &$row->params ) );
?>
</source>

Note that, in both cases (i.e. overrides by menu-specific parameters, and overrides by item-specific parameters), we aren't ''just'' doing overrides - we also add in any new parameters that weren't found in the defaults. In other words, the <code>$params</code> object ends up with all the parameters we need!

To access the value of a specific parameter, we would use:

<source lang="php">
<?php
$params->get( 'PARAMETER_NAME' );

// e.g. to obtain the value of 'parameter1', we use:
// $params->get( 'parameter1' );
?>
</source>

It is important to realise that any <code>merge</code> carried out is persistent, so the following code (where for example you have an array containing the parameters sets for several items, and you want the parameters for each item to individually override the defaults) would not produce the result you might expect:

<source lang="php">
<?php
foreach ($itemparamsgroup as $itemparams)
{
$params = &JComponentHelper::getParams( 'COMPONENT_NAME' );
$params->merge( $itemparams );
echo $params->get( 'PARAMETER_NAME' );
}
?>
</source>

In such cases, you will need to use the non-override method, and then force the overrides manually, as described below.

===Without overrides===

There will be cases where you don't want to use the default override pattern. For example, you may want to ignore the menu-specific parameters, and have only the item-specific parameters overriding the defaults. This is a little more difficult to accomplish, although it can still be done.

You can access the Component-wide default parameter values, ''without the menu overrides'', as follows:

<source lang="php">
<?php
$component = JComponentHelper::getComponent( 'COMPONENT_NAME' );
$params = new JParameter( $component->params );
?>
</source>

If you want to override these with the menu parameters, but ''without'' the 'persistence' effect described above, you can:

<source lang="php">
<?php
$menuitemid = JRequest::getInt( 'Itemid' );
if ($menuitemid)
{
$menu = JSite::getMenu();
$menuparams = $menu->getParams( $menuitemid );
$params->merge( $menuparams );
}
?>
</source>

You can access the item parameters as before, and choose whether to merge them in using the code above, or simply store them in a separate object:

<source lang="php">
<?php
$itemparams = new JParameter( $row->params );
?>
</source>

You can combine this code to achieve the effect that you want. For example, you could override the Component-wide defaults with the item-specific parameters, but ignore those for the menu. Or you could use the menu-specific parameters in some circumstances, and the item-specific ones in others. [Whenever you depart from the standard approach, though, you should be careful that you inform your users how your Component works. Users will expect your component to work the same way as those from the Joomla! core, so you should have a good reason for departing from this approach.]

Accessing the value of a particular parameter is done in the same way as described above.

<noinclude>[[Category:Development]][[Category:Components]][[Category:Parameters]]</noinclude>

Jdoc statements

2009-02-10T23:08:19Z

JimDeLaHunt: /* The type attribute */ Note about require double quotes

{{DISPLAYTITLE:jdoc statements}}
{{jdoc}}
== jdoc:include ==
The <code><jdoc:include /></code> statement is a Joomla! template's method of displaying content specific to the page being viewed. There are various <code><jdoc:include /></code> statements, each returning a different part of a Joomla! page.

== The type attribute ==
The <tt>type</tt> attribute specifies the type of content to be rendered in place of the <code><jdoc:include /></code> element. For example, the <code><jdoc:include '''''type="head"''''' /></code> statement uses the <code>type</code> attribute <code>head</code> (<code>type="head"</code>). (''Note: Jdoc expressions require double quotes around attributes, and won't work with single quotes.'')

=== Component ===
<source lang="html4strict">
<jdoc:include type="component" />
</source>

This element should only appear once in the <body> element of the Template to render the main content of the page with respect to the current page being viewed.

=== Head ===
<source lang="html4strict">
<jdoc:include type="head" />
</source>

This element should only appear once in the <head> element of the Template to render the content of the style, script and meta elements associated with the current page.

=== Installation ===
<source lang="html4strict">
<jdoc:include type="installation" />
</source>

This element is only used within the Joomla! Installer template and of no particular use in a Front-end or Back-end template. It's somewhat the equivalent to the 'component' type, rendering the main content of an installation step.

=== Message ===
<source lang="html4strict">
<jdoc:include type="message" />
</source>

This element should only appear once in the <body> element of the Template to render system and error messages that occurred in the request.

CSS styles for system messages can be found in templates\system\css\system.css

=== Module ===
<source lang="html4strict">
<jdoc:include type="module" name="breadcrumbs" />
<jdoc:include type="module" name="menu" />
<jdoc:include type="module" name="submenu" style="rounded" id="submenu-box" />
</source>

This element renders a single module given by the <tt>name</tt> attribute. The module in question must be published and accessible by the current user in order to become visible. Additional attributes can be provided to control the layout and appearance of the module, if supported.

=== Modules ===
Modules are rendered on a page using one of the following code examples. The modules are separated into different areas of a template using template positions set in the <code>templatedetails.xml</code> file. Using the <code>jdoc:include</code>'s <code>name="''[template position name]''"</code> attribute, the various modules in their respective positions can be called, rendered, and styled separately. Additional attributes can be provided to control the layout and appearance of modules, if supported.

Below are some examples of module statements with module positions used frequently by Joomla! theme developers.

<source lang="html4strict">
<jdoc:include type="modules" name="debug" />
<jdoc:include type="modules" name="icon" />
<jdoc:include type="modules" name="left" style="rounded" />
<jdoc:include type="modules" name="left" style="xhtml" />
<jdoc:include type="modules" name="right" style="xhtml" />
<jdoc:include type="modules" name="status" />
<jdoc:include type="modules" name="syndicate" />
<jdoc:include type="modules" name="title" />
<jdoc:include type="modules" name="toolbar" />
<jdoc:include type="modules" name="top" />
<jdoc:include type="modules" name="top" style="xhtml" />
<jdoc:include type="modules" name="user1" style="xhtml" />
<jdoc:include type="modules" name="user2" style="xhtml" />
<jdoc:include type="modules" name="user3" />
<jdoc:include type="modules" name="user4" />
</source>
'''Note:''' The <code>name="user3"</code> module position is normally (by default) used for the top menu.

==== The style attribute ====
The optional <code>style=""</code> attribute is available for the <code>module</code> and <code>modules</code> types of <code><jdoc:include /></code> statements. The attribute value refers to the [[What is module chrome?|chrome]] style used to wrap the output generated by the Module. If no style is provided, a value of "<code>none</code>" is used by default.

Template designers may add additional chrome names as described in [[Applying custom module chrome]].
[[Category:Templates]]

J1.5:Upgrading your template index file

2009-02-10T23:06:22Z

JimDeLaHunt: Add caution about double quotes in JDoc statements.

===Upgrading your index.php file===

# Replace '''_VALID_MOS''' with '''_JEXEC'''
# Replace '''$mosConfig_absolute_path''' with '''$this->baseUrl'''
# Replace '''$mosConfig_live_site''' with '''$mainframe->getCfg( 'live_site' )'''
# Replace fixed strings with translatable strings. For example, replace '''echo 'Hello'''' with '''echo JText::_( 'Hello' )'''
# Replace calls to mosGetParam with calls to JRequest::getVar. For example, replace '''$id = mosGetParam( $_REQUEST, 'id', 0 );''' with '''$id = JRequest::getVar( 'id', 0 );'''
# Replace '''mosShowHead();''' with '''<jdoc:include type="head" />'''
# Replace '''mosMainBody()''' with '''<jdoc:include type="component" />'''
# Replace '''mosLoadModules( $position_name, $style );''' with '''<jdoc:include type="modules" name=$position_name style=$style />'''. (''Note: the 1.0 template's PHP syntax may use single or double quotes. Jdoc expressions require double quotes, and won't work with single quotes.'')

====Module Chrome/Style Conversion Chart====
{| class="wikitable"
|-
!Joomla! 1.0
!Joomla! 1.5
|-
| -3
|rounded
|-
| -2
|xhtml
|-
| -1
|raw
|-
|0 or empty
|table
|}
<noinclude>[[Category:Reference]][[Category:Templates]][[Category:Topics]]</noinclude>

Creating a basic Joomla! template

2009-02-10T22:25:43Z

JimDeLaHunt: /* Packaging the template for installation */ new section, not yet broken off into a template.

== Introduction ==

The purpose of this tutorial is to serve as an introduction to creating Joomla! templates. It will cover the essential files and code needed to create a basic template. The code is presented so it can be cut and pasted with very little modification needed.

== Setting up a directory structure ==
{{:Setting up a directory structure|Setting up a directory structure}}
{{:How to edit the files|How to edit the files}}
== Creating a basic templateDetails.xml file ==
{{:Creating a basic templateDetails.xml file}}

== Creating a basic index.php file ==
{{:Creating a basic index file}}
{{:Testing the template}}

== Packaging the template for installation ==

A directory with several loose files is not a convenient package for distribution. So the final step is to make a ''package''. This is a compressed archive containing the directory structure and all the files. The package can be in '''ZIP''' format (with a <tt>.zip</tt> extension), in '''TAR-gzip''' format (with a <tt>.tar.gz</tt> extension), or in '''TAR-bz2''' format (with a <tt>.tar.bz2</tt> extension).

If your template is in a directory <tt>mytemplate/</tt> then to make the package you can connect to that directory and use commands like:
* <tt>tar cvvzf ../mytemplate.tar.gz *</tt>
* <tt>zip -a -r ..\mytemplate.zip *.*</tt>

Note to template developers using Mac OS X systems: the Finder's "compress" menu item produces a usable ZIP format package, but with one catch. It stores the files in [[AppleDouble]] format, adding extra files with names beginning with "<tt>._</tt>". Thus it adds a file named "<tt>._templateDetails.xml</tt>, which Joomla 1.5.x can sometimes misinterpret. The symptom is an error message, "XML Parsing Error at 1:1. Error 4: Empty document". The workaround is to compress from the command line, and set a shell environment variable "COPYFILE_DISABLE" to "true" before using "compress" or "tar". See the [[AppleDouble]] article for more information.

== Conclusion ==

You should now have created a template that works. It won't look like much yet. The best thing to do now is start experimenting with the layout.

<noinclude>
[[Category:Templates]]
[[Category:Tutorials]]
</noinclude>

User:JimDeLaHunt

2009-02-10T21:59:15Z

JimDeLaHunt: Stub content.

Jim DeLaHunt, [http://jdlh.com/ consultant in multilingual websites], blog at http://blog.jdlh.com/ . Based in Vancouver, Canada.

Part of my practice is helping with extension development and administration of Joomla sites. I specialise in [http://jdlh.com multilingual Joomla] sites.