01 - Введение
Эта страница описывает, как вы в целом взаимодействуете с классом Joomla Form, и предоставляет код простого компонента, который вы можете установить, чтобы продемонстрировать использование этого API. С помощью приведенной ниже диаграммы мы пройдемся по каждому этапу отображения формы вплоть до обработки отправленных данных.
Раздел, выделенный бледно-желтым цветом, представляет собой код библиотеки Joomla, в частности код, относящийся к классу Form.
Прямоугольники на белом фоне содержат ваш код расширения.
Для начала вам необходимо определить вашу форму в формате XML, используя стандартные типы полей формы Joomla . Смотрите код компонента ниже для примера. В общих чертах, каждый элемент поля в вашем XML-файле сопоставляется элементу HTML (в основном "входному") в форме, при этом атрибуты поля XML сопоставляются атрибутам элемента (ввода). Многие из возможных атрибутов поля перечислены в Тип поля текстовой формы .
Шаг 1 Загрузка формы
Шаг 1 - это когда пользователь переходит на веб-страницу, на которой вы отображаете форму.
Сначала вам нужно создать экземпляр класса Joomla Form , и вы делаете это, извлекая FormFactory из контейнера внедрения зависимостей и вызывая createForm. Вы можете сделать это с помощью кода:
$form = Factory::getContainer()->get(FormFactoryInterface::class)->createForm("sample", array("control" => "myform"));
В приведенном выше коде (который взят из примера кода ниже) мы создали экземпляр формы и присвоили ему имя "sample" (вы можете называть его как угодно, он просто должен быть уникальным, чтобы не конфликтовать с любыми другими формами Joomla на той же веб-странице), а также передали массив с "control" => "myform". Затем для элементов ввода HTML будут установлены атрибуты name в "myform [сообщение]", "myform [электронная почта]" и т.д. Когда пользователь отправляет форму, элементы данных будут переданы таким образом в параметрах HTTP POST, и тогда их очень легко получить в массив PHP.
Далее мы получаем класс Form для загрузки в XML-файл, содержащий определение формы:
$form->loadFile("sample_form.xml"); // передать путь к файлу и имя определения формы XML
Объект Form считывает файл в память (как PHP SimpleXMLElement) и анализирует XML, чтобы убедиться в его корректности. Элемент SimpleXMLElement представлен синим прямоугольником с надписью "xml" на диаграмме.
Шаг 2 Предоставление данных для предварительного заполнения
Вы предоставляете значения для любого элемента формы, который пожелаете. Например, если эта форма используется для редактирования записи в базе данных, вам следует предварительно заполнить ее существующими значениями полей из базы данных. Вы можете предоставить значения, настроив ассоциативный массив $data где для каждого элемента массива:
- ключом к успеху является
nameполя (в XML-файле) - значение - это то, чем вы хотите предварительно заполнить это поле
Вы проходите мимо $data массив в качестве параметра формы bind метод, и Joomla Form затем сохраняет эти данные локально в экземпляре Формы, представленном синими полосами на диаграмме.
Шаг 3 Вывод формы в формате HTML
Ты звонишь renderField:
echo $form->renderField($name);
где $name является name поля в XML-файле, и вы получаете возвращенный HTML-код, который вы можете отобразить в выходных данных. Joomla обрабатывает свое XML-представление вашей формы, чтобы получить раздел, относящийся к переданному name, генерирует HTML для этого HTML-элемента и включает html- value атрибут, основанный на предварительно заполненных данных, которые вы передали на шаге 2.
При выводе формы вам также необходимо окружить входные элементы в виде <form> элемент и добавьте submit кнопка.
Шаг 4 Пользователь, отправляющий форму
Пользователь вводит данные в вашу HTML-форму и нажимает на submit кнопка. Браузер генерирует HTTP POST-запрос на URL, указанный в <form> элемент и передается на сервер в виде массива, называемого myform (или что бы там ни было option вы выбрали ранее) значения, введенные пользователем; каждый элемент массива, указанный пользователем name атрибут элемента ввода HTML.
Joomla перенаправляет этот пост в ваш компонент. Поскольку это новый HTTP-запрос, предыдущий экземпляр формы больше не существует, поэтому вам нужно повторить Шаг 1, чтобы создать экземпляр формы и загрузить файл определения формы XML в память.
Шаг 5 Обработка данных HTTP POST
На этом этапе вы обрабатываете предоставленные данные. Это включает в себя 4 части:
Получение данных POST
Вы можете использовать функцию ввода в Joomla, чтобы получить данные, которые ввел пользователь. Например
$app = Factory::getApplication();
$data = $app->input->post->get('myform', array(), "array");
прочитаю ПОСТ myform параметры в ассоциативный массив.
Фильтрация данных
Крайне важно обеззараживать любые полученные данные, чтобы избежать инъекционных атак со стороны хакеров. Для многих методов ввода применяется фильтрация, но если вы считываете их непосредственно в массив (как указано выше), то фильтрация не применяется, и вы должны сделать это явно, используя, например
$filteredData = $form->filter($data);
При этом применяется фильтрация к каждому из входных значений. Фильтр, применяемый к полю, определяется атрибутом "filter = ..." для этого поля в вашем XML-файле формы, или, если он отсутствует, фильтр по умолчанию удалит HTML-теги и т.д. Из ваших значений данных. Возможными фильтрами являются классы, которые находятся в libraries/src/Form/Filter. Обратите внимание, что эти фильтры полей формы отличаются от фильтров ввода .
Проверка данных
Вы подтверждаете данные, введенные пользователем, позвонив по телефону
$result = $form->validate($data);
Joomla сравнивает введенные пользователем данные с проверкой, которую вы определили в XML-файле вашей формы, и генерирует ошибки для полей, которые не проходят проверку.
Предоставление отзывов пользователей
Если есть ошибки проверки, то вы должны отобразить эти ошибки пользователю и повторно отобразить форму, предварительно заполнив поля (отфильтрованными) данными, которые пользователь ввел ранее.
Если ошибок нет, то вы можете подтвердить это пользователю и показать следующую веб-страницу.
Пример кода компонента
Ниже приведен код небольшого компонента, который вы можете установить, чтобы продемонстрировать базовое использование Joomla forms. Поместите следующие 3 файла в папку с именем "com_sample_form1". Затем заархивируйте папку для создания com_sample_form1.zip и установите это как компонент на свой экземпляр Joomla.
Для простоты этот компонент использует способ определения компонента в Joomla 3, и это не будет работать в Joomla 5. Если вам нужен эквивалент, который будет работать под Joomla 5, то вы можете скачать и установить этот zip-файл .
com_sample_form1.xml Файл манифеста для компонента
<?xml version="1.0" encoding="utf-8"?> <extension type="component" version="3.1.0" method="upgrade"> <name>com_sample_form1</name> <version>1.0.0</version> <description>Sample form 1</description> <administration> </administration> <files folder="site"> <filename>sample_form1.php</filename> <filename>sample_form.xml</filename> </files> </extension>
sample_form.xml Файл, содержащий XML-файл для определения формы
<?xml version="1.0" encoding="utf-8"?> <form> <field name="message" type="text" label="Enter message" size="40" class="inputbox" required="true" /> <field name="email" type="email" label="Enter email" required="true" size="40" class="inputbox" /> <field name="telephone" type="telephone" label="Enter telephone number" required="true" size="40" class="inputbox" validate="tel" /> </form>
sample_form1.php Код компонента.
<?php
defined('_JEXEC') or die('Restricted access');
use Joomla\CMS\Form\Form;
use Joomla\CMS\Factory;
$form = Form::getInstance("sample", __DIR__ . "/sample_form.xml", array("control" => "myform"));
$prefillData = array("email" => ".@.");
if ($_SERVER['REQUEST_METHOD'] === 'POST')
{
$app = JFactory::getApplication();
$data = $app->input->post->get('myform', array(), "array");
echo "Message was " . $data["message"] .
", email was " . $data["email"] .
", and telephone was " . $data["telephone"] . "<br>";
$filteredData = $form->filter($data);
$result = $form->validate($filteredData);
if ($result)
{
echo "Validation passed ok<br>";
}
else
{
echo "Validation failed<br>";
$errors = $form->getErrors();
foreach ($errors as $error)
{
echo $error->getMessage() . "<br>";
}
// in the redisplayed form show what the user entered (after data is filtered)
$prefillData = $filteredData;
}
}
$form->bind($prefillData);
?>
<form action="<?php echo JRoute::_('index.php?option=com_sample_form1'); ?>"
method="post" name="sampleForm" id="adminForm" enctype="multipart/form-data">
<?php echo $form->renderField('message'); ?>
<?php echo $form->renderField('email'); ?>
<?php echo $form->renderField('telephone'); ?>
<button type="submit">Submit</button>
</form>
После установки перейдите на свой сайт и добавьте следующий параметр к URL-адресу: ?option=com_sample_form1. Затем вы должны увидеть отображаемую форму с 3 обязательными полями:
- общее поле ввода текста для сообщения
- поле для ввода электронной почты, предварительно заполненное строкой ".@".
- поле для ввода телефонного номера.
и используя инструменты разработки вашего браузера, вы можете сравнить атрибуты HTML с атрибутами в вашем определении формы XML.
Обратите внимание, что современные браузеры будут выполнять некоторую проверку вводимых вами значений, в частности, они будут проверять адрес электронной почты и заставят вас вводить что-либо в поля с установленным атрибутом "обязательно", но (в настоящее время) не выполняют проверку полей телефонного номера.
После того, как вы введете действительные данные в поля и нажмете Submit, затем данные будут отправлены на сервер с использованием того же URL-адреса (опять же, используйте инструменты разработки ваших браузеров, чтобы увидеть параметры) и будет запущена часть POST примера кода. При этом запускаются процедуры фильтрации и проверки. Если имеются ошибки проверки (поле "Телефон" имеет некоторую проверку), то код выводит сообщения об ошибках и предварительно заполняет форму данными, которые ввел пользователь, перед повторным воспроизведением. Включив html-теги в введенные вами значения данных, вы можете увидеть, как фильтрация удаляет их.