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 aan 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 wordt aanbevolen om de getLabel() methode voor consistentie en snelheid weg te laten, tenzij u 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 een lijst met beschikbare steden moeten opzoeken en de HTML <select> teruggeven met de steden ingevoegd als <option>.

In uw code, moet u de kenmerken verwerken die worden ingesteld door het veld van de gebruiker in het XML formulier definitie. Sommige van deze kenmerken zijn toegankelijk via protected member variables van JFormField. Bijvoorbeeld, de name attribuut in de code beschikbaar is als $this->name. Evenzo, description, default, multiple en class zijn ook beschikbaar als eigenschappen van $this. Andere parameters die u zou kunnen hebben gedefinieerd kunnen worden benaderd via de $this->element array: het kenmerk size zal in$this->element['size'] zijn.

Welke class wordt een subclass?

Om een formulier veldtype bruikbaar te laten zijn in JForm, moet het een subclass van JFormField zijn. Het hoeft echter geen direct kind van die class te zijn: u kunt ook een subclass maken van een bestaand (standaard of eigen) formulier veldtype en daardoor handige code overerven.

Als uw formulier veldtype ongeveer gelijk is aan een bestaand type, zou u een subclass van dat type moeten maken. Maak, vooral als uw formulier veldtype een list is, dan een subclass JFormFieldList. U hoeft alleen een override te maken van de getOptions() method om de opties te laten zien; de getInput() method converteert deze opties naar HTML.

Laad, om een subclass te maken van een bestaand type, bijvoorbeeld JFormFieldList, het dor het volgende toe te voegen na jimport('joomla.form.formfield');:

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

Als uw formulier veldtype ongelijk elk ander bestaand type is, maak dan een subclass direct van JFormField aan.

Locatie van bestanden

• De standaard formulier veldtypes stan in libraries/joomla/form/fields/. U moet hier geen eigen velden opslaan. U hoeft dit pad ook niet in uw code te gebruiken, maar de standaard types zijn in het algemeen goed voorbeelden.
• De eigen veldtypes die bij uw component horen staan meestal in administrator/components/<naam van uw component>/models/fields. U kunt dit of een ander pad in uw code opnemen:

JForm::addFieldPath(JPATH_COMPONENT . '/models/fields');

• De XML bestanden die formulieren definiëren staan meestal in administrator/components/<naam van uw component>/models/forms. Gebruik iets als het volgende fragment om een pad naar uw formulieren te definiëren:

JForm::addFormPath(JPATH_COMPONENT . '/models/forms');

Naam-afspraken en skelet

In deze sectie, <ComponentName> vertegenwoordigt de MetHoofdletters geschreven naam van uw component en <FieldName> vertegenwoordigd de MetHoofdletters geschreven naam van uw formulier veldtype. De class van het veld class moet staan in administrator/components/<NaamVanUwComponent>/models/fields/<naam van uw veld>.php en ziet er zo uit:

<?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
	}
}

Het groeperen van eigen veldtypes

Waarschuwing: deze informatie is gedeeltelijk onjuist en moet verbeterd worden.

Eigen veldtypes kunnen gegroepeerd worden door een underscore in de veldnaam te gebruiken. Een veld class met bijvoorbeeld als naam "JFormFieldMy_randomField" moet opgeslagen worden in administrator/components/<naam van uw component>/models/fields/my/randomField.php. We kunnen onze formulier veldnamen laten voorafgaan van een groepsnaam, daarna een underscore en daarna de naam van het veld.

Een voorbeeld van een eigen veldtype

Stel dat u werkt aan uw component genaamd com_phonebook en u wilt een veld definiëren dat steden bevat. Maak het bestand administrator/components/com_phonebook/models/fields/city.php en schrijf iets als het volgende:

<?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>';
	}
}

Met behulp van het aangepaste veldtype

Gelinkt aan een formulier

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.