Joomla! Documentation™

Le type de champ de formulaire de sous-formulaire fournit une méthode pour utiliser des formulaires XML les uns dans les autres ou réutiliser des formulaires dans un formulaire existant. Si l'attribut multiple est défini sur true, le formulaire inclus sera répétable.

Le champ a deux mises en page "prédéfinies" pour afficher le sous-formulaire sous forme de tableau ou de conteneur div, ainsi que la prise en charge des mises en page personnalisées.

An example XML field definition for single mode:

<field name="field-name" type="subform"
    formsource="path/to/exampleform.xml"
    label="Subform Field" description="Subform Field Description" />

An example XML field definition for multiple mode:

<field name="field-name" type="subform"
    formsource="path/to/exampleform.xml" multiple="true"
    label="Subform Field" description="Subform Field Description" />

Example XML of exampleform.xml

<?xml version="1.0" encoding="UTF-8"?>
<form>
    <field name="example_text" type="text" label="Example Text" />
    <field name="example_textarea" type="textarea" label="Example Textarea" cols="40" rows="8" />
</form>

An example XML of exampleform.xml with fieldsets

<?xml version="1.0" encoding="UTF-8"?>
<form>
    <fieldset name="section1" label="Section1">
        <field name="example_text" type="text" label="Example Text" />
        <field name="example_textarea" type="textarea" label="Example Textarea" cols="40" rows="8" />
    </fieldset>
    <fieldset name="section2" label="Section2">
        <field name="example_list" type="list" default="1" class="advancedSelect" label="Example List">
            <option value="1">JYES</option>
            <option value="0">JNO</option>
        </field>
    </fieldset>
</form>

The subform XML may also be specified inline as an alternative to placing the subform XML in a separate file. The following example illustrates this:

<?xml version="1.0" encoding="UTF-8"?>
<field
	name="field-name"
	type="subform"
	label="Subform Field"
	description="Subform Field Description"
	multiple="true"
	min="1"
	max="10"
	>
	<form>
		<field
			name="example_text"
			type="text"
			label="Example Text"
			/>
		<field
			name="example_textarea"
			type="textarea"
			label="Example Textarea"
			cols="40"
			rows="8"
			/>
	</form>
</field>

Attributs de champ :

• type (obligatoire) doit être "subform".
• name (nom) (obligatoire) est le nom unique du champ.
• label (étiquette) (obligatoire) (traduisible) est le titre descriptif du champ.
• description (facultatif) (traduisible) est le texte qui s'affichera dans une info-bulle lorsque l'utilisateur passe sa souris sur la liste déroulante.
• required (requis) (facultatif) le champ doit être complété avant la soumission du formulaire.
• message (facultatif) le message d'erreur qui sera affiché à la place du message par défaut.
• default (optional) is the default value, JSON string.
• formsource (mandatory) the form source to be included. A relative path to the xml file (relative to the root folder for the installed Joomla site) or a valid form name which can be found by JForm::getInstance().
• multiple (optional) whether the subform fields are repeatable or not.
• min (optional) count of minimum repeating in multiple mode. Default: 0.
• max (optional) count of maximum repeating in multiple mode. Default: 1000.
• groupByFieldset (optional) whether to group the subform fields by its fieldset (true or false). Default: false.
• buttons (optional) which buttons to show in multiple mode. Default: add,remove,move.
• layout (optional) the name of the layout to use when displaying subform fields.
• validate (optional) should be set to SubForm (note that this is case-sensitive!) to ensure that fields in the subform are individually validated. Default: Fields in the subform are not validated, even if validation rules are specified.

Mises en page disponibles :

• joomla.form.field.subform.default render the subform in a div container, without support of repeating. Default for single mode.
• joomla.form.field.subform.repeatable render the subform in a div container, used for multiple mode. Support groupByFieldset.
• joomla.form.field.subform.repeatable-table render the subform as a table, used for multiple mode. Supports groupByFieldset. By default each field is rendered as a table column, but if groupByFieldset=true then each fieldset is rendered as a table column.

Attention

If your field in the subform has additional JavaScript logic then it may not work in multiple mode, because do not see the fields which added by the subform field dynamically. If it happened then you need to adjust your field to support it. L'exemple suivant devrait pouvoir vous aider :

jQuery(document).ready(function(){
    ... here the code for setup your field as usual...

    jQuery(document).on('subform-row-add', function(event, row){
        ... here is the code to set up the fields in the new row ...
    })
});

Because of this some extra Joomla! fields may not work for now.

Fields Validation and Filters

The subform form field does not provide the Validation and Filters for child fields.

Addition: Since a security fix in Joomla 3.9.7 the filter="example" attributes in subform child fields are supported and the fields will be validated; but NOT in custom form fields that extend the JFormFieldSubform class. You have to adapt such custom fields yourself!

Beware!

All extensions that use subform fields MUST add an attribute filter to their subform child fields of type editor, textarea, text (maybe others, too) since Joomla 3.9.7 like it's common for "normal" JForm fields, if you want to allow HTML input. Otherwise the validation falls back to STRING, which is the common behavior for "normal" JForm fields. Examples:

filter="safehtml"
filter="JComponentHelper::filterText"
filter="raw" (bad decision in most cases)

Exemple

Problème

After adding new rows selects are not "chosen".

Solution

Here is an example how to reinit jQuery Chosen on newly added repeated rows:

jQuery(document).ready(function(){
    jQuery(document).on('subform-row-add', function(event, row){
        jQuery(row).find('select').chosen();
    })
});

Or a PHP snippet to be used in e.g. your plugin in **onBeforeCompileHead** method or in your component view.

$doc = JFactory::getDocument();
$js = '
	jQuery(document).on(\'subform-row-add\', function(event, row){
		jQuery(row).find(\'select\').chosen();
	})
';
$doc->addScriptDeclaration($js);

So newly added rows now are "chosen" now

Problem

Subform data not getting stored to database on custom component.

Solution

Add the following line to the beginning of your corresponding table class:

protected $_jsonEncode = array('fieldnamehere');

More information Here.

Voir également

• Liste des types de champ de formulaires standards