Joomla! Documentation™

Please someone, copy this to the docs.joomla.org/index.php?title=Subform_form_field_type thanks!

The subform form field type provides a way to use XML forms inside each other or reuse your existing forms inside your current form. The field allow to include any existing form into the current form. If attribute multiple set to true then the included form will be repeatable.

The Field have a couple "predefined" layouts for display the subform as table or as div container, and of course it allow to use your own layout.

Field support Default values from the included form, and from json string in default attribute. Last have higher priority.

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

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>

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>

Field attributes:

• type (mandatory) must be subform.
• name (mandatory) is the unique name of the field.
• label (mandatory) (translatable) is the descriptive title of the field.
• description (optional) (translatable) is text that will be shown as a tooltip when the user moves the mouse over the drop-down box.
• required (optional) The field must be filled before submitting the form.
• message (optional) The error message that will be displayed instead of the default message.
• default (optional) is the default value, JSON string.
• formsource (mandatory) the form source to be included. Path to xml file or the form name to search by JForm::getInstance().
• multiple (optional) the multiple state for the form field. Whether the subform will 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 group the subform fields by it`s fieldset (true or false). Default: false.
• buttons (optional) which buttons to show in multiple mode. Default: add,remove,move.
• layout (optional) the layout name for render the subform inputs.

Available layouts:

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

Be aware

If your field in the subform has addittional 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. Next example may help:

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.

See also

• List of standard form field types