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.

Un exemple de définition de champ XML pour le mode unique :

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

Un exemple de définition de champ XML pour le mode multiple :

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

Exemple XML de 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>

Un exemple XML de exampleform.xml avec des 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>

Le sous-formulaire XML peut également être spécifié en ligne au lieu de placer le sous-formulaire XML dans un fichier séparé. L'exemple suivant illustre cela :

<?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 (facultatif) est la valeur par défaut, chaîne JSON.
• formsource (obligatoire) la source du formulaire à inclure. Un chemin relatif vers le fichier xml (relatif au dossier racine du site Joomla installé) ou un nom de formulaire valide qui peut être trouvé par JForm::getInstance().
• multiple (facultatif) si les champs du sous-formulaire sont répétables ou non.
• min (optionnel) compte des répétitions minimales en mode multiple. Par défaut : 0.
• max (optionnel) compte du maximum de répétitions en mode multiple. Par défaut : 1000.
• groupByFieldset (facultatif) permet de regrouper les champs du sous-formulaire en fonction de leur ensemble de champs (true ou false). Valeur par défaut : false.
• buttons (optionnel) les boutons à afficher en mode multiple. Par défaut : add,remove,move.
• layout (facultatif) le nom de la mise en page à utiliser lors de l'affichage des champs subform.
• validate (facultatif) doit être défini comme SubForm (notez que c'est sensible à la casse !) pour s'assurer que les champs du sous-formulaire sont validés individuellement. Valeur par défaut : Les champs du sous-formulaire ne sont pas validés, même si des règles de validation sont spécifiées.

Mises en page disponibles :

• joomla.form.field.subform.default rend le sous-formulaire dans un conteneur div, sans support de répétition. Par défaut pour le mode simple.
• joomla.form.field.subform.repeatable rend le sous-formulaire dans un conteneur div, utilisé pour le mode multiple. Supporte groupByFieldset.
• joomla.form.field.subform.repeatable-table rend le sous-formulaire comme un tableau, utilisé pour le mode multiple. Supporte groupByFieldset. Par défaut, chaque champ est rendu comme une colonne de tableau, mais si groupByFieldset=true, alors chaque ensemble de champs est rendu comme une colonne de tableau.

Attention

Si votre champ dans le sous-formulaire a une logique JavaScript supplémentaire, il peut ne pas fonctionner en mode multiple, car les champs ajoutés par le champ du sous-formulaire ne sont pas visibles dynamiquement. Si c'est le cas, vous devez ajuster votre champ pour le prendre en charge. 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 ...
    })
});

Pour cette raison, certains champs supplémentaires de Joomla ! peuvent ne pas fonctionner pour le moment.

Validation des champs et filtres

Le champ de formulaire du sous-formulaire ne fournit pas la validation et les filtres pour les champs enfants.

Addition: Depuis un correctif de sécurité dans Joomla 3.9.7, les attributs filter="exemple" dans les champs enfants de sous-formulaires sont supportés et les champs seront validés ; 'mais PAS in custom form fields that extend the JFormFieldSubform class. dans les champs de formulaires personnalisés qui étendent le JFormFieldSubform de la classe. Vous devez adapter vous-même ces champs personnalisés !

Attention !

Toutes les extensions qui utilisent des champs de sous-formulaires DOIVENT ajouter un attribut filter à leurs champs enfants de sous-formulaires de type editor, textarea, text (peut-être d'autres, aussi) depuis Joomla 3.9.7 comme c'est le cas pour les champs JForm "normaux", si vous voulez autoriser la saisie HTML. Sinon, la validation revient à STRING, ce qui est le comportement habituel pour les champs JForm "normaux".' Exemples :

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

Exemple

Problème

After adding new rows selects are not "chosen".

Solution

Voici un exemple comment réinitialiser jQuery Chosen sur des lignes répétées nouvellement ajoutées :

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

Ou un extrait PHP à utiliser par exemple dans votre plugin dans la méthode **onBeforeCompileHead** ou dans la vue de votre composant.

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

Ainsi, les lignes nouvellement ajoutées sont maintenant "choisies".

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