Разработка:moodleQuickForm

Общие сведения

Библиотека moodleQuickForm (она же moodleform) построена на основе библиотеки PEAR HTML_QuickForm. Описание работы всех функций moodleQuickForm следует искать именно по этой ссылке.

При помощи moodleQuickForm можно описать большинство стандартных форм. Эта библиотека значительно облегчает время и силы, потраченные на разработку формы.

Перечисление всего того, что доступно в moodleQuickForm заняло бы слишком много места, поэтому перечислим только те задачи, которые при помощи этой библиотеки решить нельзя:

• создать форму в виде таблицы, в которой более 2-х столбцов
• создать длинную горизонтальную форму

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

Внешний вид

Внешне все формы класса moodleform выглядят одинаково: это таблица из 2-х столбцов, и некоторого количества строк:

Правила объявления формы

Установка всех элементов формы происходит либо в функции definition() (для статических форм), либо в функции definition_after_data() (для динамических форм).

Описание стандартных методов moodleform

__construct($action, $customdata, $method, $target, $attributes, $editable)

Этот метод вызывается когда вы создаете новый объект формы.

Параметры:

• $action - какая страница будет обрабатывать данные это формы. Работает аналогично <form action="...">. По умолчанию - адрес той страницы, на которой находится форма.
• $customdata - дополнительные данные для формы. Эти параметры будут записаны во внутреннюю переменную $this->_customdata доступны из всех внутренних методов формы. Передать можно все что угодно, никаних ограничений нет, тип переменной - на ваше усмотрение, но если вам нужно передать несколько значений, то рекомендуется использовать объект. По умолчанию null.
• $method - метод формы, GET или POST. По умолчанию POST.
• $target - только для фреймов. Имя фрейма, обрабатывающего эту форму. Используется крайне редко. По умолчанию null.
• $attributes - строка атрибутов для тега <form>. Будет добавлена внутрь тега. Разрешены любые атрибуты, предусмотренные стандартом HTML 4.01. По умолчанию пустая строка.
• $editable - доступна ли форма для редактирования. По умолчанию true (в противном случае все поля в форме будут неактивными).

definition()

Этот абстрактный метод обязательно должен быть переопределен. В нем содержится всё объявление формы.

Существует несколько основных правил, которых следует придерживаться при написании функции definition():

• Описание каждой формы должно начинаться со ссылки на HTML_QuickForm:
• Если используются глобальные переменные - их объявление также происходит в начале.

    class myform extends dof_modlib_widgets_form
    {
        function definition()
        {
            // делаем глобальные переменные видимыми
            global $DOF;
            // создаем ссылку на HTML_QuickForm
            $mform =& $this->_form;
            ...
        }
    }

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

definition_after_data()

Этот метод следует использовать в случае, если вам требуется создать динамическую форму, т. е. форму, которая конструируется в зависимости от различных исходных данных. Этот метод вызывается после definition() и set_data(), но до display(). Этот метод работает также как и definition(), но используется для динамических форм.

display()

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

get_data($slashed)

Получить данные формы после всех проверок на стороне клиента и сервера. Данные получаются в виде объекта, именами полей которого являются имена заданных в функции definition() объектов, а значениями - значения полей в форме (по умолчанию или введенные). Любой другой способ получения данных, кроме как через эту функцию, не допускается.

• $slashed - экранировать кавычки. По умолчанию true.

Пример:

   $data = $form->get_data();

set_data($data)

Добавить в форму значения по умолчанию для всех перечисленных полей. Значения полей по умолчанию также можно передать в параметре конструктора $customdata, если вы имеете дело с динамической формой. Любой другой способ передачи значений по умолчанию в форму не допускается.

• $data - объект вида (имя_поля -> значение)

Пример:

   $data = new Object();
   // заполняем объект значениями по умолчанию
   $data->field1 = 'value1';
   $data->field2 = 'value2';
   // Отправляем значения в форму
   $form->set_data($data);

get_submitted_data($slashed)

Получить данные из формы, к которым еще не применены никакие проверки.

• $slashed - экранировать кавычки. По умолчанию true.

add_element($type, $name, $description, $attributes, $options)

Добавить элемент в форму. Наиболее часто используемая функция при построении формы. $type - Тип элемента $name - Имя элемента в форме. Только латинские буквы. $description - Описание элемента. Выведется слева от него. $attributes - строка с параметрами, вставляемая в html-тег элемента. $options - массив с дополнительными параметрами. Назначение параметров зависит от типа элемента.

Поведение самой функции add_element также зависит от типа добавляемого элемента. Подробнее об этом - см. раздел Элементы формы.

create_element($type, $name, $description, $attributes, $options)

Этот метод используется для добавления группы элементов. Созданные элементы добавляются в массив. Отличие этой функции от add_element() состоит в том, что add_element() добавляет уже полностью готовый элемент в форму, а create_element() только создает элемент в памяти для последующего добавления. Назначение аргументов этой функции аналогично функции add_element().

Обращение к функции создания элемента происходит по ссылке для ускорения быстродействия.

Способ интерпретации входных параметров и поведение этой функции также зависят от указанного типа элемента. Подробнее об этом - см. раздел Элементы формы.

Пример:

   // создаем массив
   $objs = array();
   // Создаем элементы формы
   $objs[] =& $mform->createElement('text', 'testname1', 'Пояснение к полю 1');
   $objs[] =& $mform->createElement('text', 'testname2', 'Пояснение к полю 2');
   $objs[] =& $mform->createElement('text', 'testname3', 'Пояснение к полю 3');
   // добавляем элементы в форму
   $grp =& $mform->addElement('group', 'groupname', 'Пояснение для группы элементов', $objs);

addRule($element, $message, $type, $format, $validation, $reset, $force)

Добавить правило для отдельного поля. Эту функцию следует использовать для проверок на стороне клиента и простых проверок на стороне сервера. Для сложных проверок данных (например с использованием обращения к БД) используйте функцию validation().

• $element
• $message
• $type
• $format=null
• $validation='server'
• $reset = false
• $force = false

Таблица типов правил для полей формы

имя	значение	пример кода

setDefault($elementName, $defaultValue, $slashed)

Установить значение по умолчанию для выбранного элемента.

• $elementName - имя элемента
• $defaultValue - значение по умолчанию
• $slashed - в указанном значении экранированы кавычки. По умолчанию false.

is_submitted()

Возвращает true если форма подтверждена, и false в противном случае.

is_cancelled()

Возвращает true если форма отменена, и false в противном случае.

setAdvanced($elementName, $advanced)

Устанавливает поля формы как "дополнительные" - то есть они по умолчанию скрыты, и появляются по щелчку на кнопке "показать дополнительные".

• $elementName - имя элемента, который вы хотите пометить как дополнительные
• $advanced - включить/отключить признак дополнительности. Полезно при построении динамических форм: если в зависимости от какого-либо параметра поля должны быть обязательными или необязательными.

add_action_buttons($cancel, $submitlabel)

Показывает две кнопки "Сохранить изменения" и "Отменить".

• $cancel - показывать ли кнопку "отменить". По умолчанию true.
• $submitlabel - Надпись на кнопке сохранения данный. Значение переменной по умолчанию - null. Надпись по умолчанию "Сохранить изменения".

setShowAdvanced($showadvancedNow)

Изменить текст на кнопке с "Показать дополнительные" на что-нибудь более оригинальное.

• $showadvancedNow - Тип:строка, текст который вы хотите поместить на кнопке

setType($elementname, $paramtype)

Отвечает за первичную проверку значений, которые вы получаете из формы. Всегда используйте этот метод при получении данных из формы.

• $elementname - имя элемента в форме
• $paramtype - ожидаемый тип получаемых данных

Список возможных значений для $paramtype можно посмотреть в статье Константы типов данных

validation($data, $files)

Вызывается автоматически, после отправки данных на сервер. Не вызывайте эту функцию вручную.

Используется для дополнительной проверки данных на стороне сервера. Все необходимые проверки должны быть проведены именно здесь.

• $data - массив вида array('имя_поля' => 'значение') из отправленных данных
• $files - массив загруженных в форму файлов. Имеет вид array('имя_поля' => 'путь_к_временному_файлу')

Должен возвращать массив вида array('имя_поля' => 'текст_сообщения_об_ошибке'). По умолчанию возвращает пустой массив.

Элементы формы

Во всех приведенных примерах переменная $form обозначает ссылку на объект HTML_QuickForm. Подробнее об этом в описании функции definition().

Во всех текстовых полях (кроме кнопок) можно использовать html-теги форматирования.

Таблица типов элементов в moodleform:

Внешний вид	Описание	Имя	Код для вставки
?	Заголовок формы. Этот заголовок будет говорить об общем содержании данных в форме. Также он используется в случае, когда вам нужно разбить форму на несколько частей.	header	$mform->addElement('header','testname', 'Текст заголовка');
?	Стандартный html-элемент checkbox.	checkbox	$mform->addElement('checkbox', 'testname', 'Текст_перед_галочкой', 'Текст_после галочки');
?	Стандартное диалоговое окно загрузки файла.	file	$mform->addElement('file', 'userfile', 'Текст перед окном загрузки файла');
?	Добавление группы элементов. Для того, чтобы добавить группу элементов, их нужно предварительно создать при помощи функции create_element()	group	// создаем массив $objs = array(); // Создаем элементы формы $objs[] =& $mform->createElement('text', 'testname1', 'Пояснение к полю 1'); $objs[] =& $mform->createElement('text', 'testname2', 'Пояснение к полю 2'); $objs[] =& $mform->createElement('text', 'testname3', 'Пояснение к полю 3'); // добавляем элементы в форму $grp =& $mform->addElement('group', 'groupname', 'Пояснение для группы элементов', $objs);
?	Стандартный html-элемент password	password	mform->addElement('password', 'testname', 'Текст перед окном с паролем');
?	Тоже самое, что и элемент password, но с дополнительной галочкой "отобразить пароль".	passwordunmask	$mform->addElement('passwordunmask', 'testname', $DOF->get_string('to_begin', 'infosec'));
?	Стандартный html-элемент radio	radio	$mform->addElement('radio', 'testname', 'Текст до переключателем', 'Текст после переключателя', 'Значение');
?	Стандартный html-элемент select. Массив $choices содержит варианты для оператора select. Значениями массива являются текстовые надписи в списке выбора, а ключами - значения этих вариантов.	select	// создаем массив с вариантами выбора $choices = array('a' => 'Текст варианта 1', 'b' => 'Текст варианта 2'); // Добавляем элемент формы $mform->addElement('select', 'testname', 'Пояснение для строки выбора', $choices);
?		selectgroups
?		submitlink
?	Стандартный html-элемент text. Последний параметр - строка html-атрибутов. В данном примере длина поля задана 33 символа.	text	$mform->addElement('text', 'testname', 'Пояснение для текстового поля', ' length="33" ');
?	Стандартный html-элемент textarea. Значения ширины и высоты задаются в виде массива, последним аргументом.	textarea	$mform->addElement('textarea', 'testname', $DOF->get_string('to_begin', 'infosec'), array('cols'=>80, 'rows'=>20));
?	Диалоговое окно с выбором даты. Обратите внимание, что при получении данных через get_data() значение этого поля автоматически трансформируется в метку unixtime на 12:00:00 дня выбранной даты. По умолчанию выставляется текущая дата и время. Другое начальное значение может быть задано при помощи функции setDefault().	date_selector	$mform->addElement('date_selector', 'testname', 'Пояснение для поля даты');
?	Этот элемент аналогичен элементу date_selector, только добавлены параметры часов и минут. Полученные данные также трансформируются в unixtime, но уже для выбранных значений часов и минут. По умолчанию выставляется текущая дата и время. Другое начальное значение может быть задано при помощи функции setDefault().	date_time_selector	$mform->addElement('date_time_selector', 'testname', 'Пояснение для поля даты');
?	Полноценный html-редактор для редактирования страниц. Его вид (обычный или расширенный) настраивается индивидуально каждым пользователем для себя. Обратите внимание, что в качестве дополнительных параметров можно массивом передать значения ширины и высоты текстового поля.	htmleditor	$mform->addElement('htmleditor', 'testname', $DOF->get_string('to_begin', 'infosec'), array('cols'=>80, 'rows'=>20)
?	Выбор формата для редактирования сообщения. Полезно использовать вместе со встроенным html-редактором.	format	$mform->addElement('format', 'testname', $DOF->get_string('to_begin', 'infosec'));
?	Обычное текстовое поле, не передает никаких данных. Полезно использовать для различных пояснений и отображения текущей информации о каком-либо объекте. Вы также можете использовать этот элемент для разбиения формы на небольшие смысловые блоки, не разрывая рамку формы. Для более явного разбиения используйте элемент header.	static	$mform->addElement('static', 'testname', 'Пояснение:', 'Само текстовое значение');
?	Стандартный html-элемент hidden, скрытое поле для передачи служебных id, адресов для перенаправления и т. д. Помните о необходимости проверки значений из этого поля.	hidden	$mform->addElement('hidden','testname', 'Значение скрытого поля');
?	Установить модуль видимым/скрытым. Только для использования внутри Mooodle.	modvisible
?	Элемент с двумя стандартными radio-кнопками выбора: да и нет.	selectyesno
?	Шкала выставление оценки за задание. Только для использования внутри Moodle.	modgrade
?	Кнопка "отменить форму". При нажатии на нее происходит отмена всех произведенных в форме действий.	cancel	$mform->addElement('cancel', 'testname', 'Надпись на кнопке');
?	Элемент аналогичен кнопке типа submit, но при использовании button пропускается проверка данных на стороне клиента.	button	$mform->addElement('button', 'testname', 'Надпись на кнопке');
?	Выбрать файл из курса. Только для использования внутри курса Moodle.	choosecoursefile
?	Кнопка отправки данных из формы. Обязательно ставьте ее в конце, иначе все введенные данные нельзя будет отправить. Существует также альтернативный способ задать такую кнопку - это функция get_data()	submit	$mform->addElement('submit', 'testname', 'Текст на кнопке');
?	Выбрать вопрос из категории. Только при редактировании теста и только внутри курса Moodle.	questioncategory
?	Элемент checkbox c расширенными функциями - такие элементы можно объединять в группы и устанавливать им контрольный переключатель (делает либо все галочки поставлеными либо снятыми) при помощи функции add_checkbox_controller() .	advcheckbox
?	Окно с картинкой для использования Capcha проверки. Обратите внимание, что для того чтобы использовать этот элемент вы сначала должны получить уникальный ключ с на сайте http://recaptcha.net/api/getkey.	recaptcha	$mform->addElement('recaptcha', 'testname', 'Текст с пояснением');

Установка дополнительных полей

Установка дополнительных

Установка проверки на стороне клиента или сервера

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

Проверка на стороне сервера

Если вам требуется дополнительная проверка данных на стороне клиента, то используйте стандартный метод validation($data, $files). Любые другие способы проверки данных после формы должны использоваться только в особо исключительных случаях.