Joomla! Documentation™

The "J1.5" namespace is an archived namespace. This page contains information for a Joomla! version which is no longer supported. It exists only as a historical reference, it will not be improved and its content may be incomplete and/or contain broken links.

It is possible to extend the parameter types that Joomla can support beyond the standard types available in a default installation. To understand how to do this, first look at how the standard types are implemented.

Location of standard parameter types code

The code for the standard parameter types can be found in the directory

[path-to-Joomla]/libraries/joomla/html/parameter/element/

Each parameter type is defined in a separate file which must have the same name as the parameter type. For example, the category type is coded in

[path-to-Joomla]/libraries/joomla/html/parameter/element/category.php

This file contains a single class, called JElementCategory which extends JElement. The naming of files and classes used here is not merely convention. The file must have the same name as the parameter type and it must contain a class called JElement<nowiki>[element-name] otherwise the Joomla Framework will not be able to recognise and support the parameter type.

Starting a new custom parameter type

To create a custom parameter type you first need to choose a name for it. Suppose you want to call it newparm. Then you will create a new file called newparm.php containing a single class, called JElementNewparm which extends JElement.

The code for the new parameter can exist almost anywhere but it should always be placed in a sub-directory on its own or with the code for other custom parameter types.

The new parameter type will most likely be associated with a particular extension, in which case you will want to bundle the code for the parameter type with the code for the extension.

Where you put this file is somewhat flexible and depends to some degree on the type of extension you are developing. For templates it is recommended that you place it here

path-to-Joomla]/templates/[template-name]/elements/newparm.php

Changes to the XML file for custom parameter types

You need to make two specific amendments to the XML configuration file. First, you need to ensure that the file is included in the <files> list:

<files>
    ........
    <filename>elements/index.html</filename>
    <filename>elements/newparm.php</filename>
    ........
</files>

Tip: It is good practice to also include an empty index.html file in the elements directory as an extra security precaution to prevent directory listings being returned by the web server.

Alternatively, you can simply include the entire elements directory using a <folders> element:

<files>
    ........
    <folder>elements</folder>
    ........
</files>

The second amendment that you need to make to the XML configuration file is to let the Joomla Framework know that you have added a new parameter type and where to find the code to support it. To do this you add an addpath argument to the <params> tag:

<params addpath=”[path]/elements”>
   ...... list of <param> elements ......
</params>

Notice that you are adding a path to a directory containing the parameter type code, not to the code file itself. Notice also that you only have one addpath argument so if you are adding multiple parameter types you need to gather them into the same sub-directory and that sub-directory must contain only parameter type definition code.

For example, this would be a typical <params> element in a templeDetails.xml file:

<params addpath=”[path-Joomla]/templates/mytemplate/elements”>
    <param type=”newparm” name=”setting1” default=”12” />
    <param type=”text” name=”setting2” value=”Some text” />
</params>

Coding a custom parameter type

The easiest way to write the code for a new parameter type is to take the code for an existing parameter type that is similar to what you want to create and adapt it to suit your requirements. The base JElement class contains most of what you need and for most parameter types you will only need to override the fetchElement method in your extension class.

The fetchElement method returns the HTML code required to render the field that will be used to enter a value for the parameter. It takes four arguments:

fetchElement( $name, $value, &$node, $control_name )

where:

$name	is the unique name of the parameter, from the name argument.
$value	is the current value of the parameter.
$node	is a JSimpleXMLElement object representing the <param> element.
$control_name	is the parameter type from the type argument (eg. 'category' or 'newparm')

To obtain the value of an argument in the <param> element you use the attribute method of the JSimpleXMLElement object passed in $node. For example, to obtain the value of the class argument you could use code like this

$class = $node->attributes( 'class' );

For example, here is the fetchElement method for a simple version of the text parameter type (the actual version is more sophisticated):

function fetchElement( $name, $value, &$node, $control_name )
{ 
    $class = $node->attributes( 'class' ) ? $node->attributes( 'class' ) : "text_area";

    $return = '<input type="text"' .
                     'name="' . $control_name . '[' . $name . ']"' .
                     'id="'   . $control_name . '[' . $name . ']"' .
                     'value="' . $value . '"' .
                     'class="' . $class . '" />'; 
    return $return;
}

Notice that the parameter field must have an id attribute, with the value shown in this example, so that the <label> HTML element produced by the default fetchTooltip method will match with it correctly.

The only other method from JElement that you might conceivably want to override is the fetchTooltip method. This method returns the HTML code required to render a tooltip for the field. In most cases the default code will be entirely suitable and you will not need to override this method. It takes five arguments:

fetchTooltip( $label, $description, &$node, $control_name=,$name= )

where:

$label	is the string given in the label argument of the <param> definition. It should be passed through the language translation system before being used.
$description	is the string given in the description argument of the <param> definition. It should be passed through the language translation system before being used.
$node	is a JSimpleXMLElement object representing the <param> element.
$control_name	is the parameter type from the type argument (eg. 'category' or 'newparm').
$name	is the unique name of the parameter, from the name argument.

To pass a string through the language translation system you just need to use the JText static class like this

$output = JText::_( 'string to be translated' );