View source for Creating a custom form field type/nl

<noinclude><languages /></noinclude>

<noinclude>{{Joomla version|version=3.x|comment=serie}}</noinclude>
{{-}}
{{page|needs review}}

[https://api.joomla.org/cms-3/classes/Joomla.CMS.Form.Form.html JForm], een functie geïntroduceerd in Joomla! 2.5, stelt u in staat eenvoudig HTML-formulieren te maken (<code><form></code>). Formulieren gemaakt met JForm bestaan uit [[S:MyLanguage/Form field|formuliervelden]], geïmplementeerd als [https://api.joomla.org/cms-3/classes/Joomla.CMS.Form.FormField.html JFormField]. 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 [[S:MyLanguage/Standard form field types|Standaard formulierveld typen]].

Joomla! 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.

<div class="mw-translate-fuzzy">
== Formulierveld type class vereisten ==
</div>

Een formulier veldtype is gedefinieerd in een [[wikipedia:Class (computer programming)|class]] die een (niet noodzakelijkerwijs directe) subclass van JFormField moet zijn. Om correct te werken, moet de class tenminste drie methoden definiëren:

* <code>public function getLabel()</code>
<div class="mw-translate-fuzzy">
*: 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  <code>getLabel()</code> implementatie definieert, definieren de aangepaste veldtypes meestal niet hun eigen <code>getLabel()</code>. Als je het leeg laat, zal de overgeërfde methode van het maken van labels worden gebruikt. Het wordt aanbevolen om de <code>getLabel()</code> methode voor consistentie en snelheid weg te laten, tenzij u echt de HTML-code van het label wilt wijzigen.
</div>
* <code>public function getInput()</code>
<div class="mw-translate-fuzzy">
*: 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 <code><select></code> teruggeven met de steden ingevoegd als <code><option></code>.
</div>
* <code>public function getValue()</code>
*: Deze functie zal gebruikt worden om de veldwaarde aan te roepen. De waarde wordt verkregen vanuit de functie LoadFormData in het model.
Binnen uw code, moet u de attributen verwerken van de door de gebruikers van de velden in het XML formulier ingestelde definitie. Sommige van deze attributen zijn toegankelijk via protected member variabelen van JFormField. Het <code>name</code> attribuut is bijvoorbeeld in uw code beschikbaar als <code>$this->name</code>. Net zo zijn <code>label</code>, <code>description</code>, <code>default</code>, <code>multiple</code> en <code>class</code> beschikbaar als eigenschappen van <code>$this</code>. Andere parameters die u heeft gedefinieerd kunnen benaderd worden via de <code>$this->element</code> array: het attribuut <code>size</code> zal zitten in <code>$this->element['size']</code>.

<div class="mw-translate-fuzzy">
== Welke class wordt een subclass? ==
</div>

<div class="mw-translate-fuzzy">
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.
</div>

<div class="mw-translate-fuzzy">
'''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 [[S:MyLanguage/JFormFieldList|JFormFieldList]]. U hoeft alleen een override te maken van de <code>getOptions()</code> method om de opties te laten zien; de <code>getInput()</code> method converteert deze opties naar HTML.
</div>

<div class="mw-translate-fuzzy">
Laad, om een subclass te maken van een bestaand type, bijvoorbeeld JFormFieldList, het dor het volgende toe te voegen na <code>jimport('joomla.form.formfield');</code>:
</div>

<source lang="php">
jimport('joomla.form.helper');
JFormHelper::loadFieldClass('list');
</source>

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

<div class="mw-translate-fuzzy">
== Locatie van bestanden ==
</div>

<div class="mw-translate-fuzzy">
* De standaard formulier veldtypes stan in <code>libraries/joomla/form/fields/</code>. 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.
</div>
* De eigen veldtypes die bij uw component horen staan meestal in <code>administrator/components/<naam van uw component>/models/fields</code>. U kunt dit of een ander pad in uw code opnemen:
<source lang="php">JForm::addFieldPath(JPATH_COMPONENT . '/models/fields');</source>
* De XML bestanden die formulieren definiëren staan meestal in <code>administrator/components/<naam van uw component>/models/forms</code>. Gebruik iets als het volgende fragment om een pad naar uw formulieren te definiëren:
<source lang="php">JForm::addFormPath(JPATH_COMPONENT . '/models/forms');</source>

<div class="mw-translate-fuzzy">
== Naam-afspraken en skelet==
</div>

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

<source lang="php"><?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
	}
} 
</source>

<div class="mw-translate-fuzzy">
=== Het groeperen van eigen veldtypes ===
</div>

'''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 <code>administrator/components/<naam van uw component>/models/fields/my/randomField.php</code>. We kunnen onze formulier veldnamen laten voorafgaan van een  groepsnaam, daarna een underscore en daarna de naam van het veld.

<div class="mw-translate-fuzzy">
== Een voorbeeld van een eigen veldtype ==
</div>

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

<source lang="php"><?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>';
	}
} 
</source>

<div class="mw-translate-fuzzy">
Een meer geavanceerde aanpak is de <code>JFormFieldList</code> class uitbreiden. Stel u wilt een drop-down lijst maken met steden uit de database gebaseerd op dynamische condities, dan kan dat op de volgende manier:
</div>

<source lang="php"><?php
// Check to ensure this file is included in Joomla!
defined('_JEXEC') or die('Restricted access');

JFormHelper::loadFieldClass('list');

class JFormFieldCity extends JFormFieldList {

	protected $type = 'City';

	public function getOptions() {
                $app = JFactory::getApplication();
                $country = $app->input->get('country'); //country is the dynamic value which is being used in the view
                $db = JFactory::getDbo();
                $query = $db->getQuery(true);
                $query->select('a.cityname')->from('`#__tablename` AS a')->where('a.country = "'.$country.'" ');
		$rows = $db->setQuery($query)->loadObjectlist();
                foreach($rows as $row){
                    $cities[] = $row->cityname;
                }
                // Merge any additional options in the XML definition.
		$options = array_merge(parent::getOptions(), $cities);
                return $options;
	}
}
</source>

Bovenstaande voorbeeld toont een eenvoudige query die een lijst van steden uit een tabel toont waarbij de naam van de stad behoort tot het respectievelijk land. U kunt een drop-down maken op basis van meer complexe query's.

== Setting the Values of a List Option and Using JSON or an API Instead of a Database Call == 
If you want to use an API call instead of a database call to build a custom list item, use the following code.

This field was created in a module. To get it to work it needs to be saved to
*mod_modulename/models/fields/stackexchangesites.php
The naming convention is important as it is used within our function name.
<source lang="php">
<?php
// Check to ensure this file is included in Joomla!
defined('_JEXEC') or die('Restricted access');

// call the list field type
JFormHelper::loadFieldClass('list');

// The class name must always be the same as the filename (in camel case)
// extend the list field type
class JFormFieldStackexchangesites extends JFormFieldList
{
    //The field class must know its own type through the variable $type.
    protected $type = 'Stackexchangesites';

    // get the options for the list field
    public function getOptions()
    {
       // insert your JSON here or else call an API
        $json = {"api_site_parameter":"meta.stackoverflow","site_url":"https://meta.stackoverflow.com"~}
        // decode the JSON
        $sites = json_decode($json, true);
       
        // use a for each to iterate over the JSON
        foreach($sites['items'] as $site)
        {
           // choose the element of the JSON we want, and set it as a variable so we can use it in our array.
            $site = $site['api_site_parameter'];
            $site_url = $site['site_url'];
            // set an array and start adding values to it.  Set another array within our array to set our value / text items.
            $stackExchangesSitesOptions[] = array("value" => $site, "text" => $site_url);
        }

        // Merge any additional options in the XML definition.
        $options = array_merge(parent::getOptions(), $stackExchangesSitesOptions);
        return $options;
    }
}</source>
On the front end simply calling the parameter gets us the value.
<source lang="php">
$stackexchangesites = $params->get('stackexchangesites');
</source>

=== Valkuilen ===
<div class="mw-translate-fuzzy">
Het laden van een extra veld kan resulteren in een Fatal Error, als er een core veld bestaat met dezelfde bestandsnaam en het extra veld het core veld 'uitbreid'.
</div>

Beschouw een bestand <code>testfields/radio.php</code> dat bevat
<source lang="php">
<?php

class TestFormFieldRadio extends JFormFieldRadio {}
</source>

<div class="mw-translate-fuzzy">
Het aanroepen van <code>JFormHelper::loadFieldClass('radio')</code> zal resulteren in een Fatal error: Class 'JFormFieldRadio' not found.
</div>

Er kunnen hier twee redenen voor zijn.

<div class="mw-translate-fuzzy">
# JLoader kan <code>JFormFieldRadio</code> niet automatisch laden, want de class naam (<code>JFormField*</code>) komt niet overeen de padnaam (<code>joomla/form/fields/*</code> - let op het meervoud van fields).
</div>
<div class="mw-translate-fuzzy">
# JFormHelper kan <code>JFormFieldRadio</code> niet laden, want custom paden worden eer gescanned en het gevraagde veldtype ('radio') wordt gevonden voor de core classes worden bereikt
</div>

'''Oplossing'''

Gebruik het core-veld bestand direct:

<source lang="php">
<?php
require_once JPATH_LIBRARIES . '/joomla/form/fields/radio.php';

class TestFormFieldRadio extends JFormFieldRadio {}
</source>

en gebruik <code>JFormHelper::loadFieldClass</code> naar behoren met 'test.radio' in plaats van 'radio'.

<div class="mw-translate-fuzzy">
=== Met behulp van het aangepaste veldtype ===
</div>
<div class="mw-translate-fuzzy">
==== Gelinkt aan een formulier ====
</div>
Om het veldtype te gebruiken, moeten we het XML bestand bijwerken dat het formulierveld bevat. Open uw XML bestand in <code>administrator/components/com_phonebook/models/forms</code> en voeg het veld op de gebruikelijke manier toe:

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

De attribuutnaam is HoOfDlEtTeRgEvOeLiG.

Bovendien moet u misschien het veld-pad naar de bovenliggende <fieldset> toevoegen:

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

<div class="mw-translate-fuzzy">
==== Niet aan een formulier gelinkt ====
</div>
<div class="mw-translate-fuzzy">
Als u bijvoorbeeld het veld nodig heeft als drop-down in een component als admin/site filter.
</div>

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

== Overschrijven (overriden) <code>getLabel()</code> ==

<div class="mw-translate-fuzzy">
Zoals genoemd in de sectie [[#Form field type class requirements|Formulierveld type class eisen]], definiëren eigen formulier veldtypes in het algemeen hun eigen <code>getLabel()</code>. Als u een eigen label wilt aanmaken, kunt u toch gebruik maken van de <code>getLabel()</code> dat ieder veldtype class overerft van JFormField, door het bijvoorbeeld als volgt te definiëren:
</div>

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

Deze code zal uw formulierlabels onderstrepen. (Let op: Als uw doel is om formulierlabels te onderstrepen is het gebruik van  [[CSS]] de aanbevolen manier.)

Als u iets compleet anders wilt doen, kunt u het ook volledig overriden:

<source lang="php">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; 
}</source>

Dit voorbeeld zal een keuzevakje in het label toevoegen.

== Sample Component Code ==
Below is the code for a small component which you can install and run and can adapt to experiment further with custom fields. The component includes two custom fields
# A "City" field as described above (except that the options are hard-coded rather than being selected from a database). We'll also allow multiple Cities to be selected and pre-select two of them as default.
# A custom "time" field which maps to the HTML "time" input type and includes underlining the label and support for setting a minimum and maximum time.

Create the following five files in a folder called com_custom_fields. Then zip up this folder to create com_custom_fields.zip. Install this component on your Joomla instance. Once installed, navigate on your browser to your Joomla site and add to the URL the parameter <tt>&option=com_custom_fields</tt>. This should display the form with the two custom fields. You can submit the form and see the HTTP POST parameters using the browser development tools but the component doesn't contain any code which handles those parameters.

(As described in [[Basic_form_guide#MVC_and_other_considerations|Basic form guide]], the approach below isn't the recommended way to design Joomla components but it's written in this minimalist fashion to focus on the custom fields aspects).

<tt>com_custom_fields.xml</tt> Manifest file for the component
<source lang="xml">
<?xml version="1.0" encoding="utf-8"?>
<extension type="component" version="3.1.0" method="upgrade">

	<name>com_custom_fields</name>
	<version>1.0.0</version>
	<description>Custom Fields demo component</description>
	
	<administration>
	</administration>

	<files folder="site">
		<filename>custom_fields.php</filename>
		<filename>form_definition.xml</filename>
		<filename>City.php</filename>
		<filename>Time.php</filename>
	</files>
</extension>
</source>

<tt>custom_fields.php</tt> The main code file which is run when an HTTP GET or POST is directed towards this component. 
<source lang="php">
<?php
defined('_JEXEC') or die('Restricted Access');

use Joomla\CMS\Form\Form;

$form = Form::getInstance("sample", __DIR__ . "/form_definition.xml", array("control" => "jform"));
Form::addFieldPath(__DIR__);
?>
<form action="<?php echo JRoute::_('index.php?option=com_custom_fields'); ?>"
    method="post" name="adminForm" id="adminForm" enctype="multipart/form-data">

	<?php echo $form->renderField('mytime');  ?>
	
	<?php echo $form->renderField('mycity');  ?>

	<button type="submit">Submit</button>
</form>
</source>

<tt>form_definition.xml</tt> File containing the XML for the form definition, basically the two custom fields.
<source lang="xml">
<?xml version="1.0" encoding="utf-8"?>
<form name="myForm">
	<field
		name="mytime"
		type="time"
		label="Time:"
		class="inputbox"
		min="09:00"
		max="17:30"
		required="true" />
	<field name="mycity" 
		type="City"
		label="City:"
		required="true"
		multiple="true"
		class="inputbox" />
</form>
</source>

<tt>City.php</tt> PHP code for the City custom field.
<source lang="php">
<?php
defined('_JEXEC') or die('Restricted access');
use Joomla\CMS\Form\FormHelper;

FormHelper::loadFieldClass('list');

class JFormFieldCity extends JFormFieldList {

	protected $type = 'City';

	public function getOptions() {
		$cities = array(
					array('value' => 1, 'text' => 'New York'),
					array('value' => 2, 'text' => 'Chicago'),
					array('value' => 3, 'text' => 'San Francisco'),
					);
		// Merge any additional options in the XML definition.
		$options = array_merge(parent::getOptions(), $cities);

		// pre-select values 2 and 3 by setting the protected $value property
		$this->value = array(2, 3);

		return $options;
	}
}
</source>

<tt>Time.php</tt> PHP code for the time custom field.
<source lang="php">
<?php
defined('JPATH_PLATFORM') or die;

use Joomla\CMS\Factory;
use Joomla\CMS\Form\FormField;

class JFormFieldTime extends FormField
{
	protected $type = 'time';

	protected function getInput()
	{
		// get relevant attributes which were defined in the XML form definition
		$attr = !empty($this->class) ? ' class="' . $this->class . '"' : '';
		$attr .= !empty($this->element['min']) ? ' min="' . $this->element['min'] . '"' : '';
		$attr .= !empty($this->element['max']) ? ' max="' . $this->element['max'] . '"' : '';

		// set up html, including the value and other attributes
		$html = '<input type="time" name="' . $this->name . '" value="' . $this->value . '"' . $attr . '/>';

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

<noinclude>
[[Category:Development/nl|Ontwikkeling]]
[[Category:Extension development/nl|Extensie ontwikkeling]]
[[Category:Form fields/nl|Formuliervelden]]
[[Category:Joomla! 2.5/nl|Joomla! 2.5]]
[[Category:Joomla! 3.x/nl|Joomla! 3.x]]
</noinclude>