• Joomla 5.0

Этот раздел описывает более продвинутые функции Joomla Form API, чем описано ранее, и включает следующие аспекты:

• укажите путь к файлу, чтобы Joomla могла найти ваше определение формы (форм) в случае, если вы не следуете стандартам Joomla.
• определение группировок полей – Joomla предоставляет два типа, а именно наборы полей и группы полей.
• динамическое изменение вашей формы (после того, как она была загружена из XML-файла)
• методы, подобные отражению, которые позволяют вам извлекать информацию из структуры вашей формы и данных.

Раздел завершается примером компонента с примерами вышеуказанных аспектов.

Пути к файлам

По умолчанию Joomla будет искать в папке ... / forms вашего компонента XML-определение вашей формы (а также в папке ... / models / forms для обеспечения совместимости с Joomla 3), в файлах сайта, если ваша форма отображается во внешнем интерфейсе, или в файлах администратора, если ваша форма отображается во внутреннем интерфейсе. Статическая функция addFormPath() позволяет вам добавить другой каталог в список каталогов, в которых Joomla будет выполнять поиск.

(Аналогично addFieldPath() позволяет вам определить другой каталог для любых определений полей пользовательской формы (по умолчанию используется .../models/fields в Joomla 3) и addRulePath() позволяет определить другой каталог для любых пользовательских правил проверки (по умолчанию используется .../models /rules в Joomla 3). Однако с появлением пространства имен в Joomla 4 его стало проще добавлять. addfieldprefix и addruleprefix добавьте атрибуты к вашей форме, чтобы Joomla могла находить пользовательские типы полей и правила проверки.)

Наборы полей

Наборы полей связаны с <fieldset name="myfieldset"> элемент в XML-определении формы. Преимущество использования наборов полей заключается в том, что в вашем файле макета вы можете использовать

$form->renderFieldset("myfieldset");

для отображения всех полей, которые имеют <field> элементы внутри <fieldset> открывающие и закрывающие теги. Это вместо того, чтобы вызывать renderField() для каждого поля в наборе полей.

Набор полей можно рассматривать как набор полей, которые должны отображаться вместе в форме и, таким образом, схожи по концепции с HTML <fieldset> элемент. Однако обратите внимание, что renderFieldset() не выводит HTML-код <fieldset> или связанные теги.

Группы полей

Группы полей связаны с <fields name="mygroup"> элемент в XML-определении формы. Это влияет на атрибут HTML name, который присваивается элементам ввода HTML полей, которые определены в <fields> открывающий и закрывающий теги в определении формы XML и, следовательно, имя параметра, отправленного на сервер в HTTP POST запросе.

Если вы укажете опцию "control" => "myform" когда вы настраиваете свой экземпляр формы, значения полей ввода будут отправлены на сервер в HTTP POST запросе с ключом типа

myform[field1]

myform[field2]

myform[field3]

Если вы заключите эти поля в определение формы XML в <fields name="mygroup"> элемент, то параметры POST будут отправлены с именами типа

myform[mygroup][field1]

myform[mygroup][field2]

myform[mygroup][field3]

Если ваш компонент имеет таблицу базы данных и вы храните ряд параметров в виде строки json в одном из столбцов таблицы, то вы можете сгруппировать элементы ввода HTML этих параметров внутри <fields> элемент. Если вы назовете тег fields в соответствии с именем вашего столбца, вы сможете использовать функциональность таблицы Joomla, чтобы легко преобразовать ассоциативный массив PHP, возникающий из параметров POST, в строку json для хранения в базе данных.

Тот самый $group параметр, который появляется в нескольких методах Form API, относится к name атрибут <fields> тег в формате определения XML.

Обратите внимание , что fieldsets и field groups являются независимыми. В определении XML вашей формы вы можете иметь <fields> элементы внутри <fieldset> элементы, а также <fieldset> элементы внутри <fields> элементы.

Динамически Изменяющиеся Формы

Если вы определили свою форму статически в XML-файле, то после ее загрузки вы можете динамически изменять ее в своем PHP-коде, используя API Form

• добавление дополнительных полей в вашу форму путем загрузки другого XML-определения формы
• изменение существующего поля или групп полей,
• удаление поля или группы полей.

Добавление полей с помощью определения формы

Чтобы включить дополнительные определения из файла в свою форму, выполните следующие действия

$form->loadFile($filename);

проходя мимо $filename XML-файла, структурированного таким же образом, как и ваш основной файл определения формы.

В качестве альтернативы вы можете создать SimpleXMLElement ( $xml скажем) в вашем коде, который содержит тот же XML, а затем вызовите

$form->load($xml);

(Код Joomla для loadFile() просто считывает данные из файла в переменную SimpleXMLElement, а затем вызывает load()).

С помощью обеих этих функций вы можете передавать дополнительные параметры:

• $replace (в load() способ) / $reset (в loadFile() метод) – оба они имеют одинаковый эффект и относятся к случаю, когда поле в загружаемом XML-файле имеет имя, которое уже совпадает с именем в форме. Если установлено значение true, то новое поле заменяет старое. Если установлено значение false, то новое поле игнорируется.
• $xpath – если вы хотите, чтобы учитывалась только часть загружаемой XML-структуры, вы можете указать xpath для выбора части или фрагментов XML, которые вы хотите включить.

В дополнение к примеру в приведенном ниже примере кода, вы можете найти примеры загрузки дополнительных XML-файлов в ядро Joomla administrator com_menu код, связанный с настройкой администратором параметров меню сайта. Основные параметры для элемента меню сайта указаны в файле item.xml в administrator/com_menus/models/forms, но в модели com_menu item.php этот код дополняется параметрами, определенными в XML-файле, который находится в каталоге layout, связанном со страницей сайта, которая будет отображаться.

Динамическая настройка Полей

Вы можете использовать setField() чтобы добавить или заменить одно поле в экземпляре Формы, и setFields() чтобы добавить или заменить несколько полей. Чтобы использовать их, вы создаете XML, относящийся к полю, затем передаете его setField()

$xml = new SimpleXMLElement('<field name="newfield" … />');
$form->setField($xml);

Аналогично вы можете определить массив таких XML-элементов и передать их setFields(), что эквивалентно вызову setField() на каждом из отдельных элементов.

Укажите $group и $fieldset параметры для включения нового поля в определенную группу полей и набор полей.

Если $replace параметру присваивается значение true, тогда, если будет найдено существующее поле с той же группой полей и названием, оно будет заменено.

Если $replace если параметру присвоено значение false и найдено существующее поле с той же группой полей и именем, то новое поле будет проигнорировано.

Настройка Атрибутов и значений полей

setFieldAttribute() позволяет установить / изменить атрибут, связанный с полем. Обратите внимание, что атрибут ссылается на атрибут поля Joomla, а не на атрибут HTML элемента ввода. Например, для установки HTML placeholder атрибут, который вы должны установить в Joomla hint атрибут поля, и это работает только в том случае, если тип поля формы поддерживает этот атрибут.

HTML - код value атрибут обрабатывается несколько иначе, чем другие атрибуты HTML. Как описано в разделе Как работают формы , в экземпляре формы Joomla структура формы XML (определенная XML-файлом определения формы) хранится отдельно от данных предварительного заполнения формы (передаваемых в bind() метод). Что выводится в value атрибут элемента ввода HTML - это, в первую очередь, атрибут поля формы Joomla по умолчанию (если поддерживается для этого типа поля), но он переопределяется любым значением, указанным для этого поля в bind() звони.

Таким образом, вы можете установить атрибут по умолчанию, используя setFieldAttribute(), но для установки значения поля непосредственно в данных предварительного заполнения используйте setValue().

Удаление полей

Вы можете удалить поля из определения формы, вызвав removeField() чтобы удалить определенное поле или removeGroup() чтобы удалить все поля в пределах указанной группы полей.

Методы Отражения

Существует ряд методов, позволяющих получить доступ к различным аспектам данных экземпляра формы. В основном они довольно просты для понимания, и ниже объясняются только случаи, когда это может быть не совсем понятно.

getData() возвращает в качестве объекта реестра Joomla данные предварительного заполнения, которые были заданы с помощью Формы bind() звони.

Методы getField(), getFieldset() и getGroup() все поля возвращают как объекты Joomla FormField , а не как они хранятся внутри экземпляра Формы.

getFieldsets() возвращает массив объектов Fieldset со свойствами, которые отражают <fieldset> отметьте в файле определения формы. Итак, если у вас есть

<fieldset name="myfieldset" label="myfieldsetLabel" description="myfieldsetDescription">

тогда вы можете сделать

$fieldsets = $form->getFieldsets();
echo $fieldsets['myfieldset']->label;   // outputs "myfieldsetLabel"

getFormControl() возвращает строку из вашего $options параметр, переданный при создании экземпляра формы. Если вы использовали стандарт Joomla для "control" => "jform" в рамках этого $options затем массив getFormControl() вернет строку "jform".

getInput() и getLabel() верните HTML-код для <input> метка и <label> соответственно поля, которое было передано в качестве параметра. Однако обратите внимание, что ни один из этих методов не работает, если у вас есть пользовательское поле. Также обратите внимание, что эти методы формы отличаются от getInput() и getLabel() Методы FormField, которые вы должны предоставить при настройке некоторых типов пользовательских полей.

getValue() возвращает значение поля, которое вы передаете в качестве параметра, считывая его из данных, переданных в bind() вызов. При этом не учитывается атрибут по умолчанию, установленный для поля, который будет преобразован в атрибут значения поля HTML, если для этого поля не предоставлены данные для предварительного заполнения.

Пример кода компонента

Для этого раздела вы можете скачать этот zip-файл компонента и установить его. Он демонстрирует некоторые функции, описанные в этом разделе. Он не следует стандартному шаблону Joomla MVC и вместо этого обладает всей функциональностью единственного класса расширения. Это связано с тем, что его цель - выделить API, связанные с манипулированием формами.

После того как вы установили файл, перейдите на домашнюю страницу вашего сайта и добавьте параметр запроса ?option=com_sample_form3 для запуска компонента. При этом должна отображаться форма, позволяющая вводить данные и отправлять форму. Комментарии в коде должны прояснять, что происходит.