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. The code for the standard parameter types is 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[element-name] otherwise the Joomla Framework will not be able to recognise and support the new parameter type.

To create a custom parameter type you need to 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. Since you want to distribute the new parameter type with your template it is recommended that you place it here

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

You will also need to make two specific amendments to your templateDetails.xml 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 html/parameters directory as an extra security precaution to prevent directory listings being returned by the web server.

Alternatively, you can simply include the entire html/parameters directory in the <files> list:

<files>
        ........

        <folder>html/parameters</folder>

        ........
</files>

It is not necessary to do this if this line is already present:

<folder>html</folder>

The second amendment that you need to make to the templateDetails.xml 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=”/templates/[your-template-name]/html/parameters”>
..... list of <param> elements ......
</params>

Notice 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 definition code.

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 parameter in the Template Parameters screen in the Administrator. It takes four arguments:

function 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' );

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 parameter in the Template Parameters screen. In most cases the default code will be entirely suitable and you will not need to override this method. It takes five arguments:

function 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' );