Actions

Difference between revisions of "Creating a custom form field type"

From Joomla! Documentation

(Initial creation)
 
(17 intermediate revisions by 9 users not shown)
Line 1: Line 1:
A new feature in Joomla 1.6 is called JForm which lets you to easily create forms, one part of JForm is JFormFields. JFormFields takes care of all the different fields you can find in a form. JFormFields supports a large selection of fields, see the [[Standard form field types]] for in-depth info.
+
{{version/tutor|1.5,1.6,1.7,2.5}}
  
Joomla 1.6 makes it possible to override and/or extend these field types, here is how to do that.
+
[[JForm]], a feature introduced in Joomla 1.6, lets you easily create HTML forms (<code><form></code>). Forms created using JForm consist of [[Form field|form fields]], implemented as [[JFormField|JFormFields]]. There is a JFormField for each different field type you can find in a form, such as a text field type and a date field type. JForm supports a large selection of standard field types. For a full list, see [[Standard form field types]].
  
== Step 1: Location of files ==
+
Joomla 1.6 makes it possible to extend standard field types or define your own. For example, if your component manages phone book entries, you might want to define a form field type that outputs a select list of cities. There are several advantages to defining a custom form field type:
  
* The default form fields are located in joomla/libraries/joomla/form/fields/
+
* You will be able to mix standard field types with your custom field type in a JForm-based form.
* The override fields are located in administrator/components/<name of your component>/models/fields
+
* You will eventually have a reusable code package that can be used easily throughout your code.
* The XML file with form fields is located in administrator/components/<name of your component>/models/forms
+
* Extensions that collaborate with your extension will be able to create form fields without meddling with your database tables and other internals.
  
== Step 2: Setting up base ==
+
== Form field type class requirements ==
  
The first file to create is your base class. The base class is your starting point for overriding JFormField.
+
A form field type is defined in a [[wikipedia:Class (computer programming)|class]] that must be a (not necessarily direct) subclass of JFormField. To work correctly, the class must define at least two methods:
  
Create a new file called myform.php and place it in the folder administrator/components/<name of your component>/models/fields. Add the following code to the file:
+
* <code>public function getLabel()</code>
<pre><?php  
+
*: This function will be called to create the label that belongs to your field and must return a HTML string containing it. Since JFormField defines a ready-to-use <code>getLabel()</code> implementation, custom form field types usually do not define their own <code>getLabel()</code>. If you leave it out, the inherited method of creating labels will be used. It is recommended to leave out the <code>getLabel()</code> method for consistency and speed unless you actually want to modify the label's HTML.
 +
* <code>public function getInput()</code>
 +
*: This function will be called to create the field itself and must return a HTML string containing it. This is also where most of the processing usually happens. In our phone book City field example, this function will have to retrieve a list of available cities and return a HTML <code><select></code> with the cities inserted as <code><option></code>s.
 +
 
 +
Inside your code, you will have to process the attributes set by the field's user in the XML form definition. Some of those attributes are accessible via protected member variables of JFormField. For example, the <code>name</code> attribute is available in your code as <code>$this->name</code>. Similarly, <code>label</code>, <code>description</code>, <code>default</code>, <code>multiple</code> and <code>class</code> are also available as properties of <code>$this</code>. Other parameters you might have defined can be accessed through the <code>$this->element</code> array: the attribute <code>size</code> will be in <code>$this->element['size']</code>.
 +
 
 +
== Which class to subclass? ==
 +
 
 +
For a form field type to be usable in JForm, it needs do be a subclass of JFormField. However, it does not have to be a direct child of that class: you can also subclass an existing (standard or custom) form field type and thereby inherit useful code.
 +
 
 +
'''If your form field type is quite similar to an existing type,''' you should subclass that type. Especially if your form field type is a '''list''', please subclass [[JFormFieldList]]. You only have to override <code>getOptions()</code> method to return the options to be shown; the <code>getInput()</code> method will convert those options to HTML.
 +
 
 +
To subclass an existing type, for example JFormFieldList, load it by adding the following to after <code>jimport('joomla.form.formfield');</code>:
 +
 
 +
<source lang="php">
 +
jimport('joomla.form.helper');
 +
JFormHelper::loadFieldClass('list');
 +
</source>
 +
 
 +
'''If your form field type is unlike any existing type,''' subclass JFormField directly.
 +
 
 +
== Location of files ==
 +
 
 +
* The standard form field types are located in <code>joomla/libraries/joomla/form/fields/</code>. You should not store custom fields there, nor should you have to use this path in your own code, but the standard types are usually good examples.
 +
* The custom field types that belong to your component are usually located in <code>administrator/components/<name of your component>/models/fields</code>. You can specify this or another path in your code:
 +
<source lang="php">JForm::addFieldPath(JPATH_COMPONENT . '/models/fields');</source>
 +
* The XML files that define forms are usually located in <code>administrator/components/<name of your component>/models/forms</code>. Use something like the following snippet to specify a path to your forms:
 +
<source lang="php">JForm::addFormPath(JPATH_COMPONENT . '/models/forms');</source>
 +
 
 +
== Naming conventions and skeleton ==
 +
 
 +
In this section, <ComponentName> represents the camel-cased name of your component and <TypeName> represents the camel-cased name of your form field type. The field's class should be placed in <code>administrator/components/<name of your component>/models/fields/<name of your field>.php</code>, and look like this:
 +
 
 +
<source lang="php"><?php
 
// Check to ensure this file is included in Joomla!
 
// Check to ensure this file is included in Joomla!
 
defined('_JEXEC') or die('Restricted access');
 
defined('_JEXEC') or die('Restricted access');
  
abstract class JFormFieldMyForm extends JFormField {
+
jimport('joomla.form.formfield');
+
protected $type = 'MyForm';  
+
}
+
?></pre>
+
  
Important lines:
+
// The class name must always be the same as the filename (in camel case)
* abstract class JFormField'''MyForm''' extends JFormField
+
class JFormField<FieldName> extends JFormField {
The name of the file is myform.php this means the name of the class must be the same
+
* protected $type = ''' 'MyForm'''';
+
The $type must also have the same name as your class
+
  
== Step 3: Creating a field override ==
+
//The field class must know its own type through the variable $type.
 +
protected $type = '<FieldName>';
  
With the base class in place we can now create our field overrides.  
+
public function getLabel() {
 +
// code that returns HTML that will be shown as the label
 +
}
 +
 
 +
public function getInput() {
 +
// code that returns HTML that will be shown as the form field
 +
}
 +
}
 +
</source>
 +
 
 +
=== Grouping custom field types ===
 +
 
 +
'''Warning: this information is partially incorrect and needs to be improved.'''
 +
 
 +
Custom field types can be grouped by using an underscore in the field name. A field class with a name for example like "JFormFieldMy_randomField" must be stored in <code>administrator/components/<name of your component>/models/fields/my/randomField.php</code>. We can prefix our form field names with some group name, then we put an underscore and then a name of a field.
 +
 
 +
== An example custom field type ==
 +
 
 +
Suppose you're working on your component named ''com_phonebook'' and you want to define a field that contains cities. Create the file <code>administrator/components/com_phonebook/models/fields/city.php</code> and write something similar to the following:
  
Create a new file called mylist.php and place it in the folder administrator/components/<name of your component>/models/fields. Add the following code to the file:
+
<source lang="php"><?php
<pre><?php
+
 
// Check to ensure this file is included in Joomla!
 
// Check to ensure this file is included in Joomla!
 
defined('_JEXEC') or die('Restricted access');
 
defined('_JEXEC') or die('Restricted access');
  
jimport('joomla.form.helper');
+
jimport('joomla.form.formfield');
JFormHelper::loadFieldClass('MyForm');
+
  
class JFormFieldMyText extends JFormFieldMyForm {
+
class JFormFieldCity extends JFormField {
 
 
protected $type = 'MyText';
+
protected $type = 'City';
  
public function getInput() {
+
// getLabel() left out
$field = JFormHelper::loadFieldType('Text');
+
// Workaround
+
$field->setForm($this->form);
+
$field->setup($this->element, $this->value);
+
  
return $field->getInput();
+
public function getInput() {
 +
return '<select id="'.$this->id.'" name="'.$this->name.'">'.
 +
      '<option value="1" >New York</option>'.
 +
      '<option value="2" >Chicago</option>'.
 +
      '<option value="3" >San Francisco</option>'.
 +
      '</select>';
 
}
 
}
 
}  
 
}  
?></pre>
+
</source>
  
Important lines:
+
=== Using the custom field type ===
* JFormHelper::loadFieldClass('MyForm');
+
==== Linked with a form ====
Here we load our base class
+
To use the field type City, we need to update the XML file that contains the form fields. Open your XML file located in <code>administrator/components/com_phonebook/models/forms</code> and add the field in the usual way:
* class JFormField'''MyText''' extends JFormField'''MyForm''' {
+
Here we create our override called MyText and make it extend MyForm, our base class. The class name must always be the same as the filename
+
* protected $type = ''' 'MyText'''';
+
Same as the base class the field class also needs a $type set, this is the same name as your class name
+
* public function getInput() {
+
A field override class must always have the public function getInput()
+
  
Notice: This example contains a workaround until bug 21644 (http://joomlacode.org/gf/project/joomla/tracker/?action=TrackerItemEdit&tracker_item_id=21644) has been fixed.
+
<source lang="xml"><field name="title" type="City" label="JGLOBAL_TITLE"
 +
description="JFIELD_TITLE_DESC"
 +
required="true" /></source>
 +
The type name is cAsE-sEnSiTiVe.
  
== Step 4: Using the override field ==
 
  
To use the override field MyText, we need to update the XML file that contains the form fields. Open your XML file located in administrator/components/<name of your component>/models/forms and find a field that is of the type text. This example is from article.xml:
+
In addition, you may need to add the field path to the parent <fieldset>:
<pre><field name="title" type="text" label="JGLOBAL_TITLE"
+
description="JFIELD_TITLE_DESC" class="inputbox" size="30"
+
required="true" /></pre>
+
  
We change this field to look like this:
+
<source lang="xml">
<pre><field name="title" type="MyText" label="JGLOBAL_TITLE"
+
<fieldset addfieldpath="/administrator/components/<component name>/models/fields">
description="JFIELD_TITLE_DESC" class="inputbox" size="30"
+
</source>
required="true" /></pre>
+
Notice how type="text" changed to type="'''MyText'''". The MyText here refers to the class made in step 3. The type name is cAsE-sEnSiTiVe.
+
  
With these changes in place, your override is done and ready to use.
+
==== Not linked with a form ====
 +
E.g. when you need the field as a dropdown in a component as admin/site filter.
 +
<source lang="php">
 +
//Get custom field
 +
JFormHelper::addFieldPath(JPATH_COMPONENT . '/models/fields');
 +
$cities = JFormHelper::loadFieldType('City', false);
 +
$cityOptions=$cities->getOptions(); // works only if you set your field getOptions on public!!
 +
</source>
  
== Overriding getLabel() ==
+
== Overriding <code>getLabel()</code> ==
  
There are 2 ways of overriding the getLabel() method:
+
As mentioned in the section [[#Form field type class requirements|Form field type class requirements]], custom form field types usually do not define their own <code>getLabel()</code>. If you do want to create a custom label, you can still make use of the <code>getLabel()</code> that every field type class inherits from JFormField, for example by defining it as follows:
# Wrap it in your own tags
+
# Modify it completely
+
  
=== Wrapping the label ===
+
<source lang="php">public function getLabel() {
 
+
To wrap a form label you can add the following function to your myform.php file:
+
<pre>public function getLabel() {
+
 
     return '<span style="text-decoration: underline;">' . parent::getLabel() . '</span>';
 
     return '<span style="text-decoration: underline;">' . parent::getLabel() . '</span>';
} </pre>
+
} </source>
This code will underline your form labels.
+
  
=== Writing your own label ===
+
This code will underline your form labels. (Please note that if your goal is to underline form labels, using [[CSS]] is the preferred way.)
  
To write your own label you can add the following function to your myform.php file:
+
If you want to do something completely different, you can of course also override it completely:
<pre>public function getLabel() {
+
// Initialize variables.
+
$label = '';
+
$replace = '';
+
  
// Get the label text from the XML element, defaulting to the element name.
+
<source lang="php">public function getLabel() {
$text = $this->element['label'] ? (string) $this->element['label'] : (string) $this->element['name'];
+
// Initialize variables.
 +
$label = '';
 +
$replace = '';
  
// Build the class for the label.
+
// Get the label text from the XML element, defaulting to the element name.
$class = !empty($this->description) ? 'hasTip' : '';
+
$text = $this->element['label'] ? (string) $this->element['label'] : (string) $this->element['name'];
$class = $this->required == true ? $class.' required' : $class;
+
 
 +
// Build the class for the label.
 +
$class = !empty($this->description) ? 'hasTip' : '';
 +
$class = $this->required == true ? $class.' required' : $class;
 
 
// Add replace checkbox
+
// Add replace checkbox
$replace = '<input type="checkbox" name="update['.$this->name.']" value="1" />';
+
$replace = '<input type="checkbox" name="update['.$this->name.']" value="1" />';
 
 
// Add the opening label tag and main attributes attributes.
+
// Add the opening label tag and main attributes attributes.
$label .= '<label id="'.$this->id.'-lbl" for="'.$this->id.'" class="'.$class.'"';
+
$label .= '<label id="'.$this->id.'-lbl" for="'.$this->id.'" class="'.$class.'"';
  
// If a description is specified, use it to build a tooltip.
+
// If a description is specified, use it to build a tooltip.
if (!empty($this->description)) {
+
if (!empty($this->description)) {
$label .= ' title="'.htmlspecialchars(trim(JText::_($text), ':').'::' .
+
$label .= ' title="'.htmlspecialchars(trim(JText::_($text), ':').'::' .
JText::_($this->description), ENT_COMPAT, 'UTF-8').'"';
+
JText::_($this->description), ENT_COMPAT, 'UTF-8').'"';
}
+
}
  
// Add the label text and closing tag.
+
// Add the label text and closing tag.
$label .= '>'.$replace.JText::_($text).'</label>';
+
$label .= '>'.$replace.JText::_($text).'</label>';
+
return $label;  
+
return $label;  
}</pre>
+
}</source>
  
 
This example will add a checkbox before the label.
 
This example will add a checkbox before the label.
 +
 +
<noinclude>[[Category:Development]][[Category:Form fields]][[Category:Joomla! 1.6]][[Category:Joomla! 1.7]][[Category:Joomla! 2.5]]</noinclude>

Revision as of 07:49, 20 February 2013

JForm, a feature introduced in Joomla 1.6, lets you easily create HTML forms (<form>). Forms created using JForm consist of form fields, implemented as JFormFields. There is a JFormField for each different field type you can find in a form, such as a text field type and a date field type. JForm supports a large selection of standard field types. For a full list, see Standard form field types.

Joomla 1.6 makes it possible to extend standard field types or define your own. For example, if your component manages phone book entries, you might want to define a form field type that outputs a select list of cities. There are several advantages to defining a custom form field type:

  • You will be able to mix standard field types with your custom field type in a JForm-based form.
  • You will eventually have a reusable code package that can be used easily throughout your code.
  • Extensions that collaborate with your extension will be able to create form fields without meddling with your database tables and other internals.

Contents

Form field type class requirements

A form field type is defined in a class that must be a (not necessarily direct) subclass of JFormField. To work correctly, the class must define at least two methods:

  • public function getLabel()
    This function will be called to create the label that belongs to your field and must return a HTML string containing it. Since JFormField defines a ready-to-use getLabel() implementation, custom form field types usually do not define their own getLabel(). If you leave it out, the inherited method of creating labels will be used. It is recommended to leave out the getLabel() method for consistency and speed unless you actually want to modify the label's HTML.
  • public function getInput()
    This function will be called to create the field itself and must return a HTML string containing it. This is also where most of the processing usually happens. In our phone book City field example, this function will have to retrieve a list of available cities and return a HTML <select> with the cities inserted as <option>s.

Inside your code, you will have to process the attributes set by the field's user in the XML form definition. Some of those attributes are accessible via protected member variables of JFormField. For example, the name attribute is available in your code as $this->name. Similarly, label, description, default, multiple and class are also available as properties of $this. Other parameters you might have defined can be accessed through the $this->element array: the attribute size will be in $this->element['size'].

Which class to subclass?

For a form field type to be usable in JForm, it needs do be a subclass of JFormField. However, it does not have to be a direct child of that class: you can also subclass an existing (standard or custom) form field type and thereby inherit useful code.

If your form field type is quite similar to an existing type, you should subclass that type. Especially if your form field type is a list, please subclass JFormFieldList. You only have to override getOptions() method to return the options to be shown; the getInput() method will convert those options to HTML.

To subclass an existing type, for example JFormFieldList, load it by adding the following to after jimport('joomla.form.formfield');:

jimport('joomla.form.helper');
JFormHelper::loadFieldClass('list');

If your form field type is unlike any existing type, subclass JFormField directly.

Location of files

  • The standard form field types are located in joomla/libraries/joomla/form/fields/. You should not store custom fields there, nor should you have to use this path in your own code, but the standard types are usually good examples.
  • The custom field types that belong to your component are usually located in administrator/components/<name of your component>/models/fields. You can specify this or another path in your code:
JForm::addFieldPath(JPATH_COMPONENT . '/models/fields');
  • The XML files that define forms are usually located in administrator/components/<name of your component>/models/forms. Use something like the following snippet to specify a path to your forms:
JForm::addFormPath(JPATH_COMPONENT . '/models/forms');

Naming conventions and skeleton

In this section, <ComponentName> represents the camel-cased name of your component and <TypeName> represents the camel-cased name of your form field type. The field's class should be placed in administrator/components/<name of your component>/models/fields/<name of your field>.php, and look like this:

<?php
// Check to ensure this file is included in Joomla!
defined('_JEXEC') or die('Restricted access');
 
jimport('joomla.form.formfield');
 
// The class name must always be the same as the filename (in camel case)
class JFormField<FieldName> extends JFormField {
 
        //The field class must know its own type through the variable $type.
        protected $type = '<FieldName>';
 
        public function getLabel() {
                // code that returns HTML that will be shown as the label
        }
 
        public function getInput() {
                // code that returns HTML that will be shown as the form field
        }
}

Grouping custom field types

Warning: this information is partially incorrect and needs to be improved.

Custom field types can be grouped by using an underscore in the field name. A field class with a name for example like "JFormFieldMy_randomField" must be stored in administrator/components/<name of your component>/models/fields/my/randomField.php. We can prefix our form field names with some group name, then we put an underscore and then a name of a field.

An example custom field type

Suppose you're working on your component named com_phonebook and you want to define a field that contains cities. Create the file administrator/components/com_phonebook/models/fields/city.php and write something similar to the following:

<?php
// Check to ensure this file is included in Joomla!
defined('_JEXEC') or die('Restricted access');
 
jimport('joomla.form.formfield');
 
class JFormFieldCity extends JFormField {
 
        protected $type = 'City';
 
        // getLabel() left out
 
        public function getInput() {
                return '<select id="'.$this->id.'" name="'.$this->name.'">'.
                       '<option value="1" >New York</option>'.
                       '<option value="2" >Chicago</option>'.
                       '<option value="3" >San Francisco</option>'.
                       '</select>';
        }
}

Using the custom field type

Linked with a form

To use the field type City, we need to update the XML file that contains the form fields. Open your XML file located in administrator/components/com_phonebook/models/forms and add the field in the usual way:

<field name="title" type="City" label="JGLOBAL_TITLE"
        description="JFIELD_TITLE_DESC"
        required="true" />

The type name is cAsE-sEnSiTiVe.


In addition, you may need to add the field path to the parent <fieldset>:

<fieldset addfieldpath="/administrator/components/<component name>/models/fields">

Not linked with a form

E.g. when you need the field as a dropdown in a component as admin/site filter.

//Get custom field
JFormHelper::addFieldPath(JPATH_COMPONENT . '/models/fields');
$cities = JFormHelper::loadFieldType('City', false);
$cityOptions=$cities->getOptions(); // works only if you set your field getOptions on public!!

Overriding getLabel()

As mentioned in the section Form field type class requirements, custom form field types usually do not define their own getLabel(). If you do want to create a custom label, you can still make use of the getLabel() that every field type class inherits from JFormField, for example by defining it as follows:

public function getLabel() {
     return '<span style="text-decoration: underline;">' . parent::getLabel() . '</span>';
}

This code will underline your form labels. (Please note that if your goal is to underline form labels, using CSS is the preferred way.)

If you want to do something completely different, you can of course also override it completely:

public function getLabel() {
        // Initialize variables.
        $label = '';
        $replace = '';
 
        // Get the label text from the XML element, defaulting to the element name.
        $text = $this->element['label'] ? (string) $this->element['label'] : (string) $this->element['name'];
 
        // Build the class for the label.
        $class = !empty($this->description) ? 'hasTip' : '';
        $class = $this->required == true ? $class.' required' : $class;
 
        // Add replace checkbox
        $replace = '<input type="checkbox" name="update['.$this->name.']" value="1" />';
 
        // Add the opening label tag and main attributes attributes.
        $label .= '<label id="'.$this->id.'-lbl" for="'.$this->id.'" class="'.$class.'"';
 
        // If a description is specified, use it to build a tooltip.
        if (!empty($this->description)) {
                $label .= ' title="'.htmlspecialchars(trim(JText::_($text), ':').'::' .
                                JText::_($this->description), ENT_COMPAT, 'UTF-8').'"';
        }
 
        // Add the label text and closing tag.
        $label .= '>'.$replace.JText::_($text).'</label>';
 
        return $label; 
}

This example will add a checkbox before the label.