Subform - Подчиненная форма

Тип поля Subform дает возможность использовать XML-формы внутри друг друга или использовать существующие формы внутри вашей текущей формы. Поле позволяет включить любую существующую форму в текущую форму. Если атрибут multiple - true тогда включеная форма будет повторяемой.

Поле имеет несколько "предопределенных" макетов для отображения подчиненной формы в виде таблицы или в виде div контейнера, и, конечно можно использовать свой собственный макет.

Поле поддерживает значения по умолчанию из включенной формы и из json строки в атребуте default. Последнее имеет более высокий приоритет.

Пример определения XML поля для одиночного режима:

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

Пример определения XML поля для многократного режима:

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

Пример XML из 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>

Пример XML с exampleform.xml в поле

<?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>

XML субформы также может быть указан в строке в качестве альтернативы размещению XML субформы в отдельном файле. Следующий пример иллюстрирует это:

<?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>

Атрибуты поля:

type (обязательно) должно быть subform.
name (обязательно) уникальное имя поля.
label (обязательно) (переводимое) описательное название поля.
description (необязательно) (переводимое) это текст, который будет показан в подсказке, когда пользователь перемещает курсор на раскрывающемся списке.
required (необязательно) Поле должно быть заполнено перед отправкой формы.
message (необязательно) Сообщение об ошибке, которое будет отображаться вместо сообщения по умолчанию.
default (необязательно) значение по умолчанию, строка в формате JSON.
formsource (обязательно) источник формы для включения.Путь к XML-файлу или имя формы для поиска с помощью JForm::getInstance().
multiple (необязательно) многократное состояние для поля формы. Будет ли подформа повторяемой или нет.
min (необязательно) минимальное количество повторений в multiple режиме. По умолчанию: 0.
max (необязательно) максимальное количество повторений в multiple режиме. По умолчанию: 1000.
groupByFieldset (необязательно) будет ли группа полей подформы организованна как fieldset (true или false). По умолчанию: false.
buttons (необязательно) какие кнопки показывать в режиме multiple. По умолчанию: add,remove,move.
layout (необязательно) имя макета для рендеринга полей inputs подформы.
validate (необязательно) должно быть установлено значение SubForm (обратите внимание, что это чувствительно к регистру!), чтобы поля в подчиненной форме были индивидуально проверены. По умолчанию: поля в подчиненной форме не проверяются, даже если указаны правила проверки.

Доступные макеты:

joomla.form.field.subform.default рендерит подформу в div контейнер, без поддержки повторений. По умолчанию для одиночного режима
joomla.form.field.subform.repeatable рендерит подформу в div контейнер, используется для режима multiple. Поддержка groupByFieldset.
joomla.form.field.subform.repeatable-table рендерит подформу в виде таблицы, можно использовать для multiple режима. Поддержка groupByFieldset. По умолчанию рендеринг каждого поля в качестве столбца таблицы, но если groupByFieldset=true то рендеринга каждый fieldset как столбец таблицы.

Если поле в подчиненной формы имеет дополнительную JavaScript логику, то она не может работать в multiple режиме, потому что не видит поля, добавленные полем подчиненной формы динамически. Если это произошло, то вам нужно настроить поле, чтобы поддержать его.

Следующий пример может помочь:

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 ...
    })
});

Из-за этого некоторые дополнительные поля Joomla! могут не работать на данный момент.

Валидация полей и фильтры.

Поле формы субформы не обеспечивает валидацию и фильтры для дочерних полей.

Добавление: С момента исправления безопасности в Joomla 3.9.7 filter="example" атрибуты в дочерних полях субформы поддерживаются, и поля будут проверены; но НЕ в полях пользовательской формы, которые расширяют класс JFormFieldSubform. Вы должны сами адаптировать такие пользовательские поля!

Осторожно!

Все расширения, использующие поля подчиненной формы, ДОЛЖНЫ добавить атрибут filter к своим дочерним полям подчиненной формы типов editor, textarea, text (возможно, и других), начиная с Joomla 3.9.7, как это обычно бывает для «нормальных» полей JForm, если вы хотите разрешить ввод HTML. В противном случае проверка возвращается к STRING, что является общим поведением для «нормальных» полей JForm.

Examples:

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

Примеры.

Проблема.

После добавления новых строк выбранные строки не являются «выбранными».

Решение.

Вот пример того, как повторно инициализировать jQuery Selected в недавно добавленных повторяющихся строках:

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

Или фрагмент PHP для использования, например, в вашем плагине в методе **onBeforeCompileHead** или в представлении компонента.

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

Таким образом, недавно добавленные строки теперь «выбраны»

Проблема.

Данные подчиненной формы не сохраняются в базе данных на пользовательском компоненте.

Решение.

Добавьте следующую строку в начало соответствующего класса таблицы:

protected $_jsonEncode = array('fieldnamehere');

Более подробная информация здесь.