Difference between revisions of "Repeatable form field type"
From Joomla! Documentation
(Save progress on repeatable form fields) |
m (Fix syntax error and add highlighting) |
||
(23 intermediate revisions by 9 users not shown) | |||
Line 1: | Line 1: | ||
− | + | <noinclude><languages /></noinclude> | |
− | + | {{tip|<translate><!--T:28--> | |
− | + | Please use the [[S:MyLanguage/Subform form field type|Subform form field type]] (in multiple mode) instead.</translate>|title=<translate><!--T:29--> | |
− | + | This field is '''deprecated'''</translate>}} | |
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | Example XML Definition | + | <translate><!--T:1--> |
− | <source | + | Provides a modal with rows of formfields that you specify. As many options can be added as desired. Note this form field has a jQuery based javascript file as a dependency.</translate> |
− | + | ||
− | type=" | + | <translate><!--T:2--> |
− | icon="list" | + | * '''name''' (mandatory) is the unique name of the parameter.</translate> |
− | description="PLG_TINY_FIELD_TEMPLATE_FIELD_ELEMENTS_DESC" | + | <translate><!--T:3--> |
− | label="PLG_TINY_FIELD_TEMPLATE_FIELD_ELEMENTS_LABEL" | + | * '''type''' (mandatory) must be ''repeatable''.</translate> |
− | default=" | + | <translate><!--T:4--> |
− | + | * '''label''' (mandatory) (translatable) is the descriptive title of the field.</translate> | |
− | <fieldset hidden="true" name="list_templates_modal" repeat="true"> | + | <translate><!--T:5--> |
− | <field name="template" | + | * '''description''' description text for the form field. Displays at the top of the modal with the name as well as in the usual position in the form.</translate> |
− | label="PLG_TINY_FIELD_TEMPLATE_FIELD_NAME_LABEL" | + | <translate><!--T:6--> |
− | size="30" | + | * '''default''' The default value for the form field if the field is left empty. Note this has to be a json string compatible with the contents of the form field.</translate> |
− | type="text"/> | + | <translate><!--T:7--> |
− | <field name="location" | + | * '''id''' id of the hidden form field. (the modal will have this id with an added suffix of "_modal" and the table within the modal will have this id with a suffix of "_modal_table").</translate> |
− | label="PLG_TINY_FIELD_TEMPLATE_FIELD_LOCATION_LABEL" | + | <translate><!--T:8--> |
− | description="PLG_TINY_FIELD_TEMPLATE_LOCATION_DESC" | + | * '''class''' class of the table.</translate> |
− | size="30" | + | <translate><!--T:9--> |
− | type="filelist" | + | * '''select''' (translatable) The text to show on the modal button.</translate> |
− | directory="media/editors/tinymce/templates" | + | <translate><!--T:10--> |
− | exclude="index.html" | + | * '''icon''' the icon to show on the select button (is prefixed with "icon-").</translate> |
− | hide_default="true" | + | <translate><!--T:11--> |
− | hide_none="true"/> | + | * '''maximum''' the maximum number of rows of fields allowed (by default 999 to be effectively infinite).</translate> |
− | <field name="description" | + | |
− | label="PLG_TINY_FIELD_TEMPLATE_FIELD_DESCRIPTION_LABEL" | + | <translate><!--T:18--> |
− | size="30" | + | To create a form field you must first of all create a repeatable form field as usual.</translate> |
− | type="textarea" | + | <source lang="php"> |
− | /> | + | <fields></source> |
− | </fieldset | + | <translate><!--T:19--> |
− | + | Within this you place open and close tag (if not already in one - if there is an existing fields tag for params etc. this is not needed.) and within this a tag.</translate> | |
+ | <source lang="php"> | ||
+ | <fieldset></source> | ||
+ | <translate><!--T:20--> | ||
+ | The fieldset tag MUST have a name the same as your repeatable field name with "_modal" appended to the end of it - it should also have the in the fieldset tag.</translate> | ||
+ | <source lang="php"> | ||
+ | repeat="true"</source> | ||
+ | <translate><!--T:21--> | ||
+ | Within this fieldset you then include the form fields that you wish to have repeating (as with any form field).</translate> | ||
+ | |||
+ | <translate><!--T:16--> | ||
+ | Example XML Definition</translate> | ||
+ | <source lang="xml"> | ||
+ | <field name="list_templates" | ||
+ | type="repeatable" | ||
+ | icon="list" | ||
+ | description="PLG_TINY_FIELD_TEMPLATE_FIELD_ELEMENTS_DESC" | ||
+ | label="PLG_TINY_FIELD_TEMPLATE_FIELD_ELEMENTS_LABEL" | ||
+ | default='{"template":["Layout","Simple snippet"], | ||
+ | "location":["layout1.html","snippet1.html"], | ||
+ | "description":["HTMLLayout","Simple HTML snippet"]}'> | ||
+ | <fieldset hidden="true" name="list_templates_modal" repeat="true"> | ||
+ | <field name="template" | ||
+ | label="PLG_TINY_FIELD_TEMPLATE_FIELD_NAME_LABEL" | ||
+ | size="30" | ||
+ | type="text" /> | ||
+ | <field name="location" | ||
+ | label="PLG_TINY_FIELD_TEMPLATE_FIELD_LOCATION_LABEL" | ||
+ | description="PLG_TINY_FIELD_TEMPLATE_LOCATION_DESC" | ||
+ | size="30" | ||
+ | type="filelist" | ||
+ | directory="media/editors/tinymce/templates" | ||
+ | exclude="index.html" | ||
+ | hide_default="true" | ||
+ | hide_none="true" /> | ||
+ | <field name="description" | ||
+ | label="PLG_TINY_FIELD_TEMPLATE_FIELD_DESCRIPTION_LABEL" | ||
+ | size="30" | ||
+ | type="textarea" /> | ||
+ | </fieldset> | ||
</field> | </field> | ||
</source> | </source> | ||
+ | <translate> | ||
+ | ===Considerations for the default value === <!--T:22--> | ||
+ | </translate> | ||
+ | <translate><!--T:23--> | ||
+ | * The default may contain spaces tabs and new lines <ref>https://tools.ietf.org/html/rfc7158</ref> (makes for better readability)</translate> | ||
+ | <translate><!--T:24--> | ||
+ | * The data elements within the string must be quoted using " instead of '. Failure to do so will cause the json decode to fail on the default values.</translate> | ||
+ | |||
+ | <translate> | ||
+ | ===Retrieving your data=== <!--T:25--> | ||
+ | </translate> | ||
+ | <translate><!--T:26--> | ||
+ | The settings of a repeatable form field are returned as a json encoded array (same as the default)</translate> | ||
+ | |||
+ | <source lang="php"> | ||
+ | // get the repeatable field value and decode it | ||
+ | $list_hosts = json_decode( $params->get('list_templates'),true); | ||
+ | // loop your result | ||
+ | foreach( $list_templates as $list_templates_idx => $list_template ) { | ||
+ | // do something clever for each of the templates | ||
+ | } | ||
+ | </source> | ||
+ | <translate> | ||
+ | ===References=== <!--T:27--> | ||
+ | </translate> | ||
+ | <references> | ||
+ | </references> | ||
+ | <noinclude> | ||
+ | <translate> | ||
+ | <!--T:17--> | ||
[[Category:Standard form field types]] | [[Category:Standard form field types]] | ||
+ | </translate> | ||
+ | </noinclude> |
Latest revision as of 09:27, 27 May 2019
Please use the Subform form field type (in multiple mode) instead.
Provides a modal with rows of formfields that you specify. As many options can be added as desired. Note this form field has a jQuery based javascript file as a dependency.
- name (mandatory) is the unique name of the parameter.
- type (mandatory) must be repeatable.
- label (mandatory) (translatable) is the descriptive title of the field.
- description description text for the form field. Displays at the top of the modal with the name as well as in the usual position in the form.
- default The default value for the form field if the field is left empty. Note this has to be a json string compatible with the contents of the form field.
- id id of the hidden form field. (the modal will have this id with an added suffix of "_modal" and the table within the modal will have this id with a suffix of "_modal_table").
- class class of the table.
- select (translatable) The text to show on the modal button.
- icon the icon to show on the select button (is prefixed with "icon-").
- maximum the maximum number of rows of fields allowed (by default 999 to be effectively infinite).
To create a form field you must first of all create a repeatable form field as usual.
<fields>
Within this you place open and close tag (if not already in one - if there is an existing fields tag for params etc. this is not needed.) and within this a tag.
<fieldset>
The fieldset tag MUST have a name the same as your repeatable field name with "_modal" appended to the end of it - it should also have the in the fieldset tag.
repeat="true"
Within this fieldset you then include the form fields that you wish to have repeating (as with any form field).
Example XML Definition
<field name="list_templates"
type="repeatable"
icon="list"
description="PLG_TINY_FIELD_TEMPLATE_FIELD_ELEMENTS_DESC"
label="PLG_TINY_FIELD_TEMPLATE_FIELD_ELEMENTS_LABEL"
default='{"template":["Layout","Simple snippet"],
"location":["layout1.html","snippet1.html"],
"description":["HTMLLayout","Simple HTML snippet"]}'>
<fieldset hidden="true" name="list_templates_modal" repeat="true">
<field name="template"
label="PLG_TINY_FIELD_TEMPLATE_FIELD_NAME_LABEL"
size="30"
type="text" />
<field name="location"
label="PLG_TINY_FIELD_TEMPLATE_FIELD_LOCATION_LABEL"
description="PLG_TINY_FIELD_TEMPLATE_LOCATION_DESC"
size="30"
type="filelist"
directory="media/editors/tinymce/templates"
exclude="index.html"
hide_default="true"
hide_none="true" />
<field name="description"
label="PLG_TINY_FIELD_TEMPLATE_FIELD_DESCRIPTION_LABEL"
size="30"
type="textarea" />
</fieldset>
</field>
Considerations for the default value[edit]
- The default may contain spaces tabs and new lines [1] (makes for better readability)
- The data elements within the string must be quoted using " instead of '. Failure to do so will cause the json decode to fail on the default values.
Retrieving your data[edit]
The settings of a repeatable form field are returned as a json encoded array (same as the default)
// get the repeatable field value and decode it
$list_hosts = json_decode( $params->get('list_templates'),true);
// loop your result
foreach( $list_templates as $list_templates_idx => $list_template ) {
// do something clever for each of the templates
}