Joomla! Documentation™

El campo subformulario ofrece una forma de usar formularios XML dentro de otros o reutilizar los formularios existentes dentro de su formulario actual. Si el atributo multiple tiene el valor true, entonces el formulario incluido será repeatable (repetible).

El campo tiene un par de maquetaciones predefinidas para mostrar el subformulario como una tabla o como un contenedor div, y por supuesto te permite usar tu propia maquetación.

Un ejemplo de definición XML de campo para modo single:

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

Un ejemplo de definición de campo XML para modo multiple:

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

Ejemplo 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 ejemplo XML de exampleform.xml con 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>

Atributos del campo:

• type (obligatorio) debe ser subform.
• name (obligatorio) es el nombre único del campo.
• label (obligatorio) (traducible) es el título descriptivo del campo.
• description (opcional) (traducible) es un texto que se mostrará como un tooltip cuando el usuario pasa el mouse sobre el desplegable.
• required (opcional) El campo debe ser llenado antes de enviar el formulario.
• message (opcional) El mensaje de error que se mostrará en vez del mensaje predeterminado.
• default (opcional) es el valor predeterminado, una cadena JSON.
• formsource (obligatorio) el formulario fuente que se incluirá. La ruta relativa al archivo xml (relativa a la carpeta raiz del sitio Joomla) o el nombre de un formulario válido que pueda encontrarse con JForm::getInstance().
• multiple (opcional) determina si el subformulario es repetible o no.
• min (opcional) conteo de repeticiones mínimas en modo múltiple. Predeterminado: 0.
• max (opcional) conteo de repeticiones máximas en modo múltiple. Predeterminado: 1000.
• groupByFieldset (opcional) si se debe agrupar o no los campos de subformulario por sus fieldset (true o false). Predeterminado: false.
• buttons (opcional) qué botones mostrar en el modo múltiple. Predeterminado: add,remove,move.
• layout (opcional) el nombre del layout para renderizar los campos del subformulario.
• 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.

Layouts disponibles:

• joomla.form.field.subform.default renderizar el subformulario en un contenedor div, sin soporte para repetición. Predeterminado para modo simple.
• joomla.form.field.subform.repeatable renderiza el subformulario en un contenedor div, usado para modo múltiple. Soporta groupByFieldset.
• joomla.form.field.subform.repeatable-table renderiza el subformulario como una tabla, puede ser usado en modo múltiple. Soporta groupByFieldset. De forma predeterminada renderiza cada campo como la columna de una tabla, pero si groupByFieldset=true, entonces renderiza cada fieldset como una columna de la tabla.

Ten cuidado

Si tu campo en el subformulario tiene lógica adicional de JavaScript, entonces puede no funcionar en modo multiple, porque no se ven los campos agregados por el campo subformulario de forma dinámica. Si esto ocurre, necesitarás ajustar el campo para que lo soporte. El siguiente ejemplo puede ayudar:

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)

Example

Problem

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.

Ver también

• Lista de los tipos de campo de formulario estándar