Тип поля формы Joomla — Subform

• Тип поля формы Subform CMS Joomla
  • Примеры определения поля в манифесте XML
  • Атрибуты полей формы Subform
  • Доступные шаблоны поля формы Subform
  • Принять во внимание!
• Проверка полей и Фильтры
  • Ахтунг!
• Примеры

Тип поля формы Subform CMS Joomla

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

В поле есть два "предопределенных" макета для отображения Subform либо в виде table, либо в виде контейнера div, а также поддержка пользовательских макетов.

Примеры определения поля в манифесте XML

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

<field name="field-name" type="subform"
    formsource="path/to/exampleform.xml"
    label="Поле Subform" description="Описание поля Subform" />

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

<field name="field-name" type="subform"
    formsource="path/to/exampleform.xml" multiple="true"
    label="Поле Subform" description="Описание поля Subform" />

Пример XML-файла exampleform.xml

<?xml version="1.0" encoding="UTF-8"?>
<form>
    <field name="example_text" type="text" label="Тут текст метки" />
    <field name="example_textarea" type="textarea" label="Пример 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="Тут текст метки" />
        <field name="example_textarea" type="textarea" label="Пример Textarea" cols="40" rows="8" />
    </fieldset>
    <fieldset name="section2" label="Section2">
        <field name="example_list" type="list" default="1" class="advancedSelect" label="Пример списка">
            <option value="1">JYES</option>
            <option value="0">JNO</option>
        </field>
    </fieldset>
</form>

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

<?xml version="1.0" encoding="UTF-8"?>
<field
	name="field-name"
	type="subform"
	label="Поле Subform"
	description="Описание поля Subform"
	multiple="true"
	min="1"
	max="10"
	>
	<form>
		<field
			name="example_text"
			type="text"
			label="Тут текст метки"
			/>
		<field
			name="example_textarea"
			type="textarea"
			label="Пример Textarea"
			cols="40"
			rows="8"
			/>
	</form>
</field>

Атрибуты полей формы Subform

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

Доступные шаблоны поля формы Subform

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

Принять во внимание!

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

jQuery(document).ready(function(){
    ... здесь код для настройки вашего поля как обычно...

    jQuery(document).on('subform-row-add', function(event, row){
        ... вот код для настройки полей в новой строке ...
    })
});

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

Проверка полей и Фильтры

Поле формы Subform не обеспечивает проверку (Validation) и фильтры (Filters) для дочерних полей.

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

Ахтунг!

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

Примеры

Задача

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

Решение

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

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

Таким образом, недавно добавленные строки теперь "chosen" (доступны к выбору).

Задача

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

Решение

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

protected $_jsonEncode = array('fieldnamehere');

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

Перевод с английского официальной документации Joomla:
https://docs.joomla.org/Subform_form_field_type