Actions

J1.5

Difference between revisions of "Creating custom template parameter types"

From Joomla! Documentation

m
Line 1: Line 1:
[[Category:Development]]
+
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
 +
 
 +
<tt>[path-to-Joomla]/libraries/joomla/html/parameter/element/</tt>
 +
 
 +
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
 +
 
 +
<tt>[path-to-Joomla]/libraries/joomla/html/parameter/element/category.php</tt>
 +
 
 +
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
 +
 
 +
<tt>[path-to-Joomla]/templates/[template-name]/elements/newparm.php</tt>
 +
 
 +
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 <tt><files></tt> list:
 +
<source lang="xml">
 +
<files>
 +
        ........
 +
 
 +
        <filename>elements/index.html</filename>
 +
        <filename>elements/newparm.php</filename>
 +
 
 +
        ........
 +
</files>
 +
</source>
 +
 
 +
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 <tt><files></tt> list:
 +
<source lang="xml">
 +
<files>
 +
        ........
 +
 
 +
        <folder>html/parameters</folder>
 +
 
 +
        ........
 +
</files>
 +
</source>
 +
 
 +
It is not necessary to do this if this line is already present:
 +
<source lang="xml">
 +
<folder>html</folder>
 +
</source>
 +
 
 +
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 <tt><params></tt> tag:
 +
<source lang="xml">
 +
<params addpath=”/templates/[your-template-name]/html/parameters”>
 +
..... list of <param> elements ......
 +
</params>
 +
</source>
 +
 
 +
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:
 +
<source lang="php">
 +
function fetchElement( $name, $value, &$node, $control_name )
 +
</source>
 +
 
 +
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 <tt><param></tt> element.
 +
* '''$control_name''' is the parameter type from the type argument (eg. 'category' or 'newparm')
 +
 
 +
To obtain the value of an argument in the <tt><param></tt> 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
 +
<source lang="php">
 +
$class = $node->attributes( 'class' );
 +
</source>
 +
 
 +
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:
 +
<source lang="php">
 +
function fetchTooltip( $label, $description, &$node, $control_name='', $name='' )
 +
</source>
 +
 
 +
where:
 +
 
 +
* '''$label''' is the string given in the label argument of the <tt><param></tt> definition.  It should be passed through the language translation system before being used.
 +
* '''$description''' is the string given in the description argument of the <tt><param></tt> definition.  It should be passed through the language translation system before being used.
 +
* '''$node''' is a '''JSimpleXMLElement''' object representing the <tt><param></tt> 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
 +
<source lang="php">
 +
$output = JText::_( 'string to be translated' );
 +
</source>
 +
[[Category:Development]][[Category:Templates]]

Revision as of 15:50, 16 August 2008

Replacement filing cabinet.png
This Namespace has been archived - Please Do Not Edit or Create Pages in this namespace. Pages contain information for a Joomla! version which is no longer supported. It exists only as a historical reference, will not be improved and its content may be incomplete.

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