Using Parameters

This article describes how to use the parameter system in your Mambo Modules and Components.

Parameters provided with components relate to the when they are added to menu items. The parameters will show when you edit the menu item.

XML Definition

The setup file for Modules and Components setup files define the parameters. Parameters are wrapped in a <params> collection tag and then individual parameters are defined in a <param> tag. A typical parameter block may look like:

 <params name="" description="">
 <param name="count" type="text" default="5" label="Number of items"
 description="The number of items to show" />
 </params>

The following attributes are allowed for the <params> tag:

• name: The name of the group of parameters parameter
• description: A description for the group of parameters

Both these attributes are optional.

The following attributes are allowed for the <param> tag:

• name: The name of the parameter
• type: The type of form element.
• default: the default value for the parameter
• label: The text to place to the left of the edit control
• description: The text to place to the right of the edit control

The available types for parameters are as follows:

text
The "text" type provides a simple text box, for example:

<param name="count" type="text" default="5" label="Number of items"
description="The number of items to show" />

list
The "list" type provides for an HTML select list. You provide the necessary HTML options as child elements of this tag in the same way as you would for an HTML select list, for example:

<param name="hide_author" type="list" default="" label="Hide Author"
description="Show/Hide the item author ? only affects this page">
<option value="">Use Global</option>
<option value="1">Hide</option>
<option value="0">Show</option>
</param>

radio
The "radio" type provides for an HTML radio group. You provide the necessary HTML options as child elements of this tag in the same way as you would for an HTML select list, for example:

<param name="show_leading" type="radio" default="1" label="Show Leading"
description="Show leading items">
<option value="0">No</option>
<option value="1">Yes</option>
</param>

Radio list groups are formatted horizontally.

mos_section
The "mos_section" type provides a list of published sections, for example:

<param name="section_id" type="mos_section" default="0" label="Section"
description="A content section" />

The section id (primary key) is returned.

mos_category
The "mos_category" type provides a list of published categories, for example:

<param name="catid" type="mos_category" default="0" label="Category"
description="A content category" />

The lists displays items in "Section?Category" format. The category id (primary key) is returned.

mos_menu
The "mos_menu" type provides a list of the defined menu types used in the site, for example:

<param name="menutype" type="mos_menu" default="mainmenu" label="Menu Type"
description="The name of the menu (default mainmenu)" />

mos_imagelist
The "mos_imagelist" type provides a list of images in the directory defined by the "directory" attribute, for example:

<param name="menu_image" type="imagelist" directory="/images/M_images" default=""
 label="Menu Image"
 description="A small image to be placed to the left or right of your menu item..." />

The directory is relative to the installation directory of Mambo.

textarea
The "textarea" type provides a simple textarea, for example:

<param name="description_text" type="textarea" default="" label="Description Text" rows="30" cols="5
description="Description for page, if left blank it will load \_WEBLINKS_DESC from your language file"/>

Note that rows and cols attributes are available for this parameter type.

The mosParameters Class

A helper class is available for working with parameters called mosParameters. The mosParameters class constructor takes two arguments, the first the textual parameter values retrieved from the database, and the second in the xml setup file where the parameters are defined. See the following example:

global $mainframe;

$option = 'com_content';

// get params definitions
$params =& new mosParameters( $menu?>params,
 $mainframe?>getPath( 'com_xml', $option ), 'component' );

<?php
function displayFoo( &$params ) {

 echo $params?>render();
}
?>

Always pass the params variable by reference as this conserves memory.