Сайт справки

01 - Введение

Эта страница описывает, как вы в целом взаимодействуете с классом Joomla Form, и предоставляет код простого компонента, который вы можете установить, чтобы продемонстрировать использование этого API. С помощью приведенной ниже диаграммы мы пройдемся по каждому этапу отображения формы вплоть до обработки отправленных данных.

Раздел, выделенный бледно-желтым цветом, представляет собой код библиотеки Joomla, в частности код, относящийся к классу Form.

Прямоугольники на белом фоне содержат ваш код расширения.

Basic 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-теги в введенные вами значения данных, вы можете увидеть, как фильтрация удаляет их.

Наверх

© Сайт справки 2024