Creating a custom form field type/nl

Joomla! 

3.x

serie

This Article Needs Your Help

JForm, een functie geïntroduceerd in Joomla! 2.5, stelt u in staat eenvoudig HTML-formulieren te maken (<form>). Formulieren gemaakt met JForm bestaan uit formulier velden, geïmplementeerd als JFormFields. Er is een JFormField voor elk veldtype in een formulier, zoals een tekstveld en een datumveld. JForm ondersteunt een grote selectie van standaard veldtypen. Voor een volledige lijst, zie Standaard formulier veldtypen.

Joomla! 2.5 maakt het mogelijk om de standaard veldtypen uit te breiden of om uw eigen te definiëren. Bijvoorbeeld, als uw component een telefoonboek beheert, zou u een veldtype kunnen definiëren dat een lijst van steden geeft. Er zijn verschillende voordelen als u een aangepast veldtype definieert:

• U kunt standaard veldtypen samen gebruiken met uw aangepaste veldtype in een JForm-formulier.
• U zult uiteindelijk een herbruikbaar code pakket hebben gecreëerd dat gemakkelijk gebruikt kan worden in de rest van uw code.
• Extensies die samenwerken met uw extensie zullen in staat zijn om formuliervelden te maken zonder zich te bemoeien met uw database tabellen en andere interne zaken.

Formulier veldtype class eisen

Een formulier veldtype is gedefinieerd in een class die een (niet noodzakelijkerwijs directe) subclass van JFormField moet zijn. Om correct te werken, moet de class tenminste twee methoden definiëren:

• public function getLabel()

  Deze functie wordt aangeroepen voor het maken van het label dat bij uw veld hoort en moet een HTML-tekenreeks teruggeven die het veld bevat. Omdat JFormField een klaar-om-te-gebruiken getLabel() implementatie definieert, definieren de aangepaste veldtypes meestal niet hun eigen getLabel(). Als je het leeg laat, zal de overgeërfde methode van het maken van labels worden gebruikt. Het is aanbevolen om de getLabel() methode voor consistentie en snelheid weg te laten, tenzij je echt de HTML-code van het label wilt wijzigen.

• public function getInput()

  Deze functie wordt aangeroepen om het veld zelf te maken en moet een HTML-tekenreeks teruggeven. Dit is ook waar de meeste verwerking plaatsvindt. In ons telefoonboek voorbeeld (veld stad), zal deze functie u een lijst van beschikbare steden moeten opzoeken en de HTML <select> teruggeven met de steden ingevoegd als<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 to 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 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 <FieldName> 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 inside the label.

Adding XML include file functionality

XML form definitions are cumbersome, and maintaining a number of similar forms can be problematic if fieldset and field definitions have only minor differences between forms.

You can alleviate a lot of the drudgery by grouping your fieldset or field definitions in additional files and then include those files in your top level form definition.

This will require you to make a slight modification to the /libraries/joomla/form/form.php file, but this is a small price to pay for flexibility gained.

In method

loadFile($file, $reset = true, $xpath = false)

(line 867 in Joomla 3.1)

change:

$xml = simplexml_load_file($file);

to:

$xml = simplexml_load_file($file, 'SimpleXMLElement', LIBXML_NOENT);

At the top of your master form definition file you would add something like this:

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE form [
    <!ENTITY include1 SYSTEM "includefile1.xml">
    ... 
   <!ENTITY include4 SYSTEM "includefile4.xml">
]>

Then, insert the ENTITY identifier in your master definition file in the following way:

%include1;

So by way of example if your master xml form definition looks like this:

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE form [
    <!ENTITY include1 SYSTEM "includefile1.xml">
    <!ENTITY include2 SYSTEM "includefile2.xml">
]>
<form>
    <fieldset>
      <field name="id" type="hidden" filter="integer"/>
      &include1;
    </fieldset>
    &include2;
</form>

and includefile1.xml looks like this:

<field name="email" type="email" label="COM_USERS_EMAIL_LABEL" required="true"/>

and includefile2.xml looks like this:

<fieldset name="more">
    <field name="first_name" type="text" label="COM_USERS_NAME_LABEL" required="true"/>
</fieldset>

Then the loaded file used by Joomla in evaluating your form will look like this:

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE form [
    <!ENTITY include1 SYSTEM "includefile1.xml">
    <!ENTITY include2 SYSTEM "includefile2.xml">
]>
<form>
    <fieldset>
      <field name="id" type="hidden" filter="integer"/>
      <field name="email" type="email" label="COM_USERS_EMAIL_LABEL" required="true"/>
    </fieldset>
    <fieldset name="more">
        <field name="first_name" type="text" label="COM_USERS_NAME_LABEL" required="true"/>
    </fieldset>
</form>