Joomla! Documentation - User contributions [en]

J1.5:Adding view layout configuration parameters

2009-02-22T22:42:41Z

Mike dowler: Fixed typo & corrected name->title

{{review}}
==Background==
When creating views for a custom component, you can create a series of .xml files that will both describe the view and allow administrators to configure the view as they require. The .xml files are used by the com_menu core component (ilink.php) to create the menu trees that are shown when an administrator creates a new menu item.

==View title and description==
First give a title and description to your view. This is done by including a metadata.xml file in the view directory:

<source lang="xml"><?xml version="1.0" encoding="utf-8"?>
<metadata>
<view title="CAST_VIEW">
<message><![CDATA[CAST_VIEW_DESC]]></message>
</view>
</metadata>
</source>

The 'title' element is shown as the 1st level entry under your component name when a new menu item is created. The 'message' element is the descriptive tool tip that is shown when the mouse hovers over the 'title' element. The example is using JText placeholders for the title and message. Just add the corresponding tags to your language definition files. You did create them didn't you?

If you don't want this view to be selectable for a new menu item, then add the hidden="true" parameter to the view element (e.g. <view title="CAST_VIEW" hidden="true">). You can also hide a view by using an underscore '_' in the name. Be careful with naming your views or you can spend hours trying to figure out why it doesn't appear in the new menu item tree!

<h2>Template names, description, parameters</h2>
You can also create .xml files for the individual files in the tmpl folders. This is a cool way to have a name other than 'default' show up in the new menu item tree.
Make sure that the name of the .xml file is the same as the name of your template file. I.E. if your file name is default.php, then your xml file name is default.xml. Its probably more productive to name your template files something other than default. That way, when you have 10 of them open in your favorite IDE, you won't get totally confused as to which file you are editing. That also avoids the nightmare of uploading the wrong file to the wrong directory!

The .xml file for the template can be very simple with just a title and message or very complex with basic and/or advanced parameters:

<source lang="xml">
<?xml version="1.0" encoding="utf-8"?>
<metadata>
<layout title="STANDARD_CATEGORY_LAYOUT">
<message>
<![CDATA[STANDARD_CATEGORY_LAYOUT DESC]]>
</message>
</layout>
<state>
<name>STANDARD_CATEGORY_LAYOUT</name>
<description>STANDARD_CATEGORY_LAYOUT_DESC</description>
<url>
</url>
<params>
</params>
<advanced>
</advanced>
</state>
</metadata>
</source>

See components\com_content\views\frontpage\tmpl\default.xml, or components\com_content\views\section\tmpl\default.xml for examples of how to specify both basic and advanced parameters for your views. See also [[Standard parameter types]] for information on defining parameters.

You can also add the hidden="true" to the layout element if you don't want this particular template file to be selected as a new menu item.

==Final touches==
Remember to create JText language definitions for your titles and messages so they can be easily translated. Have fun giving your views cool names and descriptions for that final bit of polish on your custom component!
[[Category:Development]]

J1.5:Components:xml installfile

2009-02-17T21:55:49Z

Mike dowler: Added example folder tag

<source lang="xml">
<?xml version="1.0" encoding="utf-8"?>
<install type="component" version="1.5.0">
<name>hello_world</name>

<creationDate>2007 01 17</creationDate>
<author>John Doe</author>
<authorEmail>john.doe@example.org</authorEmail>
<authorUrl>http://www.example.org</authorUrl>
<copyright>Copyright Info</copyright>
<license>License Info</license>

<version>Component Version String</version>

<description>Description of the component ...</description>


<installfile>install.eventlist.php</installfile>


<uninstallfile>uninstall.eventlist.php</uninstallfile>


<install>
<sql>
<file driver="mysql" charset="utf8">install.mysql.utf8.sql</file>
<file driver="mysql">install.mysql.nonutf8.sql</file>
</sql>
</install>


<uninstall>
<sql>
<file driver="mysql" charset="utf8">uninstall.mysql.utf8.sql</file>
<file driver="mysql">uninstall.mysql.nonutf8.sql</file>
</sql>
</uninstall>


<files>
<filename>index.html</filename>
<filename>test.php</filename>
<folder>views</folder>
</files>


<languages>
<language tag="en-GB">en-GB.com_test.ini</language>
<language tag="de-DE">de-DE.com_test.ini</language>
<language tag="nl-NL">nl-NL.com_test.ini</language>
</languages>


<media destination="com_test">
<filename>image.png</filename>
<filename>flash.swf</filename>
</media>

<administration>


<menu img="components/com_test/assets/test-16.png">EventList</menu>
<submenu>

<menu link="option=com_helloworld&task=hello&who=world">Hello World!</menu>

<menu img="icon" task="hello" controller="z" view="a" layout="b" sub="c">Hello Again!</menu>
<menu view="test" layout="foo">Testing Foo Layout</menu>
</submenu>



<files folder="admin">
<filename>index.html</filename>
<filename>admin.test.php</filename>
</files>


<languages folder="admin">
<language tag="en-GB">en-GB.com_test.ini</language>
<language tag="de-DE">de-DE.com_test.ini</language>
<language tag="nl-NL">nl-NL.com_test.ini</language>
</languages>


<media folder="admin" destination="com_test">
<filename>admin-image.png</filename>
<filename>admin-flash.swf</filename>
</media>
</administration>
</install>
</source>
[[Category:Development]][[Category:Extensions]]

J1.5 talk:Component parameters

2009-02-17T21:54:45Z

Mike dowler: Explanation for deleting text

I find the terms "frontend" and "backend" confusing when applied in this context.

also, links to the standard parameter types would be extremely useful.
http://docs.joomla.org/Standard_parameter_types

Overall, I found the article extremely useful.

Commercemeister, thanks for your comments. Could you please explain what you find confusing about frontend and backend? They are commonly used to refer to the main site and the administration parts of a Joomla! website, respectively. It would be helpful to know how you think they should be clarified (or you could even just do it yourself - that's the beauty of a wiki!). Thanks too for the note about parameter types - the article did originally link to a page with this information, but then that page was changed. I will update it.

One final point - please sign your comments using the four tildes at the end (<nowiki>~~~~</nowiki>). Thanks, [[User:Mike dowler|Mike]] 16:18, 3 September 2008 (EDT)

I'm confused about the differences between the types of parameters.
So you've got Parameters (Basic), (Advanced), (Component) and (System).

Now what kind of parameters would you put in (basic) and what in (component) if both can be overriden in the menu you create for the component ?
I just don't see the distinction between the two...
[[User:Alfred|Alfred]] 14:12, 25 September 2008 (EDT)

Alfred, 'Basic' and 'Advanced' parameters are just 'article-specific' parameters - the only difference between 'basic' and 'advanced' is in how they are displayed in the back end. 'Article-specific' parameters are those that are only ever going to apply to that article, whereas 'Component' parameters are set for the component as a whole. As you point out, both types can be overridden for a particular menu link; administrators using your component will thank you if such overrides are the exception rather than the rule!

So, in the screenshot shown, there is the basic parameter 'Description text' field which (IIRC) provides a description of the article. It would make no sense to have this as a component parameter, since you would need to override it almost every time you use it. Note that there is no 'right' or 'wrong' here, just common sense. If a parameter is likely to be the same across the site (e.g. choosing whether or not to display the name of the author, which is likely to be fixed to maintain a consistent feel to a site), then put it in the component params. If it's likely to change in each case, make it an article param. If both would be useful, then use both. (Just make sure that you give the article param a 'Use global' (i.e. empty string) option as default, so that the component parameter works as expected.) [[User:Mike dowler|Mike]] 18:23, 28 October 2008 (EDT)

== Component level params must be saved before they show up ==

I've seen this effect in several extensions, and it was very confusing and not obvious at first. Perhaps a note can be added. The issue is that the default params for the component, usually accessed by "Preferences" may not have been actually entered into the database.

It would be nice to just have a note, especially in the overrides section, that you need to make sure the component params are actually saved. It would also be nice if 3rd party components that use these config params either place a notice to the user that params must be saved, or make sure that the default params are entered into the database during the installation process, if these params do not yet exist.

Hope this makes some sense. I'm not really sure the best solution to this problem, but more documentation about this potential pitfall I'm sure would be helpful.

Snellcode, good point. Tbh, I think the whole parameters subject is a little difficult to get hold of - my main reason for writing this was so that I could get everything straight in my own head. The way it ''should'' work is that the <code>COMPONENT_NAME.xml</code> installation file creates the parameters in the database, so that the component defaults are already set. If this is '''not''' done, then you are right - it is necessary to open the 'parameters' window, choose the values, and save, so that the parameters are created. The wrong way to do things, which may be what is going on, is to try to combine both steps (ignoring the installation file) and give the <code><param /></code> elements in the <code>config.xml</code> file <code>default</code> values. These will show up in the parameters window, but do not appear in the database until they are saved. The article does kind of refer to this, but I will think about how to make it more explicit.

You could try point the 3PDs to this article, or simply vote with your feet and use a different extension! [[User:Mike dowler|Mike]] 21:36, 17 February 2009 (UTC)

== Referencing the parameters XML file in the install file ==
I have deleted Jmgonet's paragraph about adding a reference to the install file, as I think it is outside the scope of this article (which tbh is already complicated enough!) The article is aimed at those developing components, who should be aware of the need to ensure that all necessary files are installed (covered adequately elsewhere). In any case, the best option is to use a <code><folder /></code> tag in the install file, rather than lots of <code><filename /></code> tags; that way, there is no need to list every single file, and less risk of a file being missed. Hope that's ok! [[User:Mike dowler|Mike]] 21:54, 17 February 2009 (UTC)

J1.5:Component parameters

2009-02-17T21:41:13Z

Mike dowler: Removed paragraph re file reference in install file - see talk page

{{review}}

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

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/TEMPLATE_NAME.xml</code>. The structure of the file is:
<source lang="xml">
<metadata>
...
<state>
...
<params>
<param />
...
</params>
<advanced>
<param />
...
</advanced>
</state>
</metadata>
</source>

A list of parameter types can be found here: [http://help.joomla.org/content/view/28/125/]

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( &$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.

[[Category:Development]]

J1.5 talk:Component parameters

2009-02-17T21:37:08Z

Mike dowler:

2008-11-15T19:36:16Z

Mike dowler:

J1.5 talk:Component parameters

2008-10-28T22:23:25Z

Mike dowler:

J1.5:Component parameters

2008-09-03T20:33:40Z

Mike dowler: Changed capitalisation in line with policy doc (I hope!)

{{review}}

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

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/TEMPLATE_NAME.xml</code>. The structure of the file is:
<source lang="xml">
<metadata>
...
<state>
...
<params>
<param />
...
</params>
<advanced>
<param />
...
</advanced>
</state>
</metadata>
</source>

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 = 'PATH_TO_JOOMLA/administrator/components/com_COMPONENT_NAME/models/MODEL_NAME.xml';
$params = new JParameter( $paramsdata, $paramsdefs );
</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>

==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( &$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.

[[Category:Development]]

J1.5:Component parameters

2008-09-03T20:21:59Z

Mike dowler: Updated link

{{review}}

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

Joomla! includes some shortcuts to enable component creators to easily add parameter forms to the backend 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 backend. 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>
<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.

So that administrators to access these parameters, you will need to add a button to the toolbar in the backend 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 backend 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 frontend - following the menu link in the frontend 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 ''frontend'' 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/TEMPLATE_NAME.xml</code>. The structure of the file is:
<source lang="xml">
<metadata>
...
<state>
...
<params>
<param />
...
</params>
<advanced>
<param />
...
</advanced>
</state>
</metadata>
</source>

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 backend (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 backend 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 = 'PATH_TO_JOOMLA/administrator/components/com_COMPONENT_NAME/models/MODEL_NAME.xml';
$params = new JParameter( $paramsdata, $paramsdefs );
</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 backend), 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>

==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 frontend 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( &$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.

[[Category:Development]]

J1.5 talk:Component parameters

2008-09-03T20:18:31Z

Mike dowler:

J1.5 talk:Storing template parameter values

2008-08-19T21:01:59Z

Mike dowler: New page: Chris, again, this page is template-specific but the title isn't. I suspect this one ''really'' is template-specific, and it is the title that needs to change. :-) ~~~~

Chris, again, this page is template-specific but the title isn't. I suspect this one ''really'' is template-specific, and it is the title that needs to change. :-) [[User:Mike dowler|Mike]] 17:01, 19 August 2008 (EDT)

J1.5 talk:Creating custom template parameter types

2008-08-19T19:41:52Z

Mike dowler: New page: Chris, this page seems to be template-specific, but this is not clear from the title. Parameters can also be used with other extensions. Would you object to mentioning templates in the t...

Chris, this page seems to be template-specific, but this is not clear from the title. Parameters can also be used with other extensions. Would you object to mentioning templates in the title?

Also, I am not entirely clear where the files should be stored - you seem to mention both <code>elements</code> and <code>html/parameters</code> folders. I think that the references to <code>templateDetails.xml</code> may be a bit of a red herring. Could we perhaps just remind people that they need to consider this when creating new files for a template, and link to another page specifying how this can be done (i.e. using <code><file></code> or <code><folder></code>)? [[User:Mike dowler|Mike]] 15:41, 19 August 2008 (EDT)

J1.5:User Group Access levels explained in simple terms

2008-08-19T19:30:05Z

Mike dowler: Fixed typo

== Foreword ==

I've never been able to locate a "Plain Talk" version of how Joomla's access groups work, so I thought I'd attempt to create one myself. I created this in the process of doing training documentation for a client. I hope this helps out those of you who have had a hard time finding resources to explain the concept, and I'd appreciate comments and corrections. Note: I am NOT a core dev, just a developer who wants to give something back to the community.

== Audience ==

This document is targeted at new users who have successfully completed a Joomla install and have accessed the Admin Backend, and upon creating their first, users wondered what the heck those Group levels mean!

== Access Levels ==

Joomla controls access to certain areas and features of a site through use of a basic ACL, or Access Control Level mechanism called Groups. Certain groups have certain access level features and they are directly related to the creation, editing and publishing of content (through the Frontend and Backend interfaces) as well as to access to the Administrative (Backend) interface.

Each group has different levels of access control and once a user is made a member of that group, they inherit those rights. Note that the 'Public Front-end' and 'Public Back-end' groups are merely placeholders at this point in time. They are not valid group selections at this time, but in the future, they will define the default access levels for anonymous users in the Front-end and Back-end systems. The Joomla ACL is currently undergoing further development to allow greater control over aspects and access to the site. Future ACL enhancements are outlined in the “Joomla Roadmap”, (among other future plans) and is available at http://www.joomla.org/content/view/14/28/.

There are four (4) Front-end groups available:

'''Registered''' - This group allows the user to login to the Frontend interface. Registered users can't contribute content, but this may allow them access to other areas, like a forum or download section if your site has one.

'''Author''' - This group allows a user to post content, usually via a link in the User Menu. They can submit new content, select options to show the item on the front page and select dates for publishing but they cannot directly publish any content. When content is submitted by an Author level user, they receive the message, “Thanks for your submission. Your submission will now be reviewed before being posted to the site.” They can edit only their own articles but only when that article has been published and is visible.

'''Editor''' - This group allows a user to post and edit any (not just their own) content item from the Frontend. They can also edit content that has not been published. If your site uses the default installation’s menu option “News”, which is a Table List – Content Section type, Editors will see unpublished articles in the list that they can select for editing, where as an Author or Public (unregistered) user will not even see the unpublished items in the list. Still, Editor users cannot, publish or change the publishing status of any articles, even their own.

'''Publisher''' - This group allows a user to post, edit and publish any (not just their own) content item from the Front-end. Publishers can review all articles, edit and change publishing options but the can also determine when an article is ready for publication, making it visible to Registered, Author and the Unregistered Public (depending on what visibility was chosen in the article, of course!)

There are three (3) Administration section groups that allow access to Joomla:

'''Manager''' - This group allows access to content creation and other system information from the Backend. Think of Manager users as Publishers, with Backend access. They can log in through the Administrator interface, but their rights and access are generally restricted to content management. They can create or edit any content, access to some Backend only features like adding, deleting and editing Sections and Categories, editing the Front Page and Menus, but they don’t have any access to the “Mechanics” of Joomla, like user management or the ability to install components or modules. Note that if a Manager logs in through the Frontend interface, they’re treated just like a Publisher, with the same rights and access.

'''Administrator''' - This group allows access to most administration functions. An Administrator user has all the privileges on the back end of a Manager, but they also have access to set options on, and install/delete components, modules and bots, User Manager access and can view the site statistics. What they cannot do however is change, edit or install Site Templates or make any changes to the sites Global configuration options. On login through the Frontend, they are treated as Publishers, just like the Manger users. Interesting to note; when an Administrator accesses the User Manager list, they will see all users at their access level or below; in other words they can modify any user EXCEPT a Super Administrator – in fact, they will not even see Super Administrator accounts in the list! Also, they cannot create additional Super Administrator level accounts, only a Super Admin can do that.

'''Super Administrator''' - This group allows access to all administration functions. Only another Super Administrator can create or edit a Super Administrator user account. Full access to ALL AREAS is given to Super Administrators, and once created they cannot be deleted – EVEN BY ANOTHER SUPER ADMIN! (Users with access directly to the MySQL database may be able to manually delete these users, but it is not for the timid and can result in a full lockout!)

Because of this, give a bit of thought to who you need to grant this highest level of access to. Super Admins, while they cannot delete another SA can block the user from logging in or change the password on another SA account. Like the other Backend user accounts, SA’s are treated as Publishers when they login through the Frontend interface.

== Summation ==

As mentioned previously, the Joomla ACL is currently in further development as of the writing of this document and will provide new features and greater control. However these enhancements won’t be seen until Joomla 1.2, currently expected sometime in Q3 2006, so the previous overview will be what most users and administrators will see for the foreseeable future.

Components have recently been made available to extend the Joomla ACL, including JACLPlus by BYOSTECH (http://www.byostech.com) which seems to be the most complete and popular, but due diligence should be exercised with ANY ACL extension – not only in how it affects currently available add ons for Joomla, but also how it may affect any new core versions that will be released in the future. This is not an endorsement of any specific project or an indictment; merely a bit of advice to use common sense. There are other posts in the forum that deal with ACL extensions, and it would be a good idea to read them and ask questions before embarking on any changes.

[[Category:Tips and tricks]]
[[Category:Tips and tricks 1.0]]
[[Category:Tips and tricks 1.5]]

J1.5:Regular expressions in parameter arguments

2008-08-19T11:46:24Z

Mike dowler: Fixed typo in source tag

Some parameter arguments take regular expressions as values. For example, the '''filter''' and '''exclude''' arguments for the '''filelist''' and '''imagelist''' parameter types. This is enormously powerful, but it requires you to know at least a little regular expression syntax to be able to use it effectively.

Described here are some examples of simple regular expressions that you might want to use in the context of template parameters. A complete reference to regular expression syntax is beyond the scope of this book, but can be found online at http://www.php.net/manual/en/book.pcre.php

=== Simple filter string ===
Suppose you want to use the '''filelist''' parameter type to list the files in a given directory. There are many files in the directory but you only want those with a '.php' extension to be listed. Then you would use this argument in the <tt><param></tt> element
<source lang="xml">
filter = “\.php”
</source>

The first thing to note is the leading backslash character. This is needed because the “.” character has a special meaning in regular expressions and that is not what is intended here. The backslash character tells the regular expression parser to treat the next character (which is the “.”) as just an ordinary character and not to give it the special meaning that it normally does.

The effect of this filter string is to only include those files that have the characters “.”, “p”, “h” and “p”, in that order, anywhere in the file name.

=== Anchoring to the end of the string ===
In the above example, if there is a file called ''configuration.php-dist'' then it would be included in the list because “.php” occurs in the middle of the string. Perhaps you don't want that, in which case you can use this instead
<source lang="xml">
filter = “\.php$”
</source>

The “$” tells the regular expression parser that the string “.php” must occur at the end of the file name. So ''configuration.php'' will be included, but ''configuration.php-dist'' will not.

=== Anchoring to the start of the string ===
Suppose you want to list those files which start with the string “joomla” then you would use
<source lang="xml">
filter = “^joomla”
</source>

The “^” tells the regular expression parser that the string following must occur at the start of the file name.

=== Anchoring to both ends of the string ===
Suppose you want to list all those files whose names begin with “joomla” and end with “.php”, but you don't care about what is in between. Then you can use
<source lang="xml">
filter = “^joomla(.*)\.php$”
</source>

Here you will recognise the “^” character as anchoring the start of the string, and the “$” as anchoring the end of the string. The “(.*)” indicates that any number of characters, including no characters at all, are acceptable in that position. Breaking this down a little, the “.” will match any single character; the “*” indicates that the preceding character (in this the “.”) can occur any number of times, including zero; and the brackets serve to separate the substring from the rest of the string.

=== Case sensitivity ===
It is important to note that regular expression strings are case sensitive. Suppose you have some file names that begin with “Joomla” instead of “joomla”. These would not be included if you used the string in the previous example. To allow for the first character of the file name to be either upper or lower case you can use
<source lang="xml">
filter = “^[Jj]oomla”
</source>

Here the “[Jj]” indicates that either “J” or “j” should be matched. The brackets (“[]”) indicate a “character class” and should contain list of characters that are to be matched. If you want to include all filenames beginning with the letters “s”, “t”, “u” or “v” then you could use
<source lang="xml">
filter = “^[stuv]”
</source>

Actually you can shorten this a little by using a range specification
<source lang="xml">
filter = “^[s-v]”
</source>

If you want to make this case insensitive then use
<source lang="xml">
filter = “^[s-vS-V]”
</source>

=== Filtering a list of extensions ===
Suppose you want to filter your list of files so that only those files with specific extensions are included. For a single extension you can just use
<source lang="xml">
filter = “\.php$”
</source>

But what if you want to filter several different extensions? For example, to only include file names ending in “.php”, “.html” or “.txt” you can use
<source lang="xml">
filter = “\.php$|\.html$|\.txt$”
</source>

The “|” character indicates an alternative, so “this|that” will match with “this” or “that”.

You might notice that the '''imagelist''' parameter type is exactly the same as the '''filelist''' parameter type with this filter string
<source lang="xml">
filter = “\.png$|\.gif$|\.jpg$|\.bmp$|\.ico$”
</source>
[[Category:Templates]]

J1.5 talk:Usergroup parameter type

2008-08-18T20:21:54Z

Mike dowler: New page: Is the required type "usergroups" (with 's') or "usergroup" (without 's')? The text says one thing, but the XML example code says the other. ~~~~

Is the required type "usergroups" (with 's') or "usergroup" (without 's')? The text says one thing, but the XML example code says the other. [[User:Mike dowler|Mike]] 16:21, 18 August 2008 (EDT)

J1.5:Component parameters

2008-05-26T21:40:51Z

Mike dowler: Added review tag

{{review}}

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

Joomla! includes some shortcuts to enable component creators to easily add parameter forms to the backend 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 backend. A list of the available form elements is given [[Using_the_core_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 />


...
</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>
<param type="type" name="name" description="description" />


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

So that administrators to access these parameters, you will need to add a button to the toolbar in the backend 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 backend 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 frontend - following the menu link in the frontend 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 ''frontend'' 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/TEMPLATE_NAME.xml</code>. The structure of the file is:
<source lang="xml">
<metadata>
...
<state>
...
<params>
<param />
...
</params>
<advanced>
<param />
...
</advanced>
</state>
</metadata>
</source>

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 backend (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 backend 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 = 'PATH_TO_JOOMLA/administrator/components/com_COMPONENT_NAME/models/MODEL_NAME.xml';
$params = new JParameter( $paramsdata, $paramsdefs );
</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 backend), 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>

==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 frontend 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( &$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.

2008-04-26T09:21:25Z

Mike dowler: /* 3. 'Article' specific parameters */