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

Материал из DOF
Версия от 16:02, 1 июня 2009; Ilya (обсуждение | вклад) (setType($elementname, $paramtype): Данные о константах сведены в таблицу и корректно описаны)
Перейти к: навигация, поиск

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

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

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

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

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

Внешний вид

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

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

Описание стандартных методов 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 (в противном случае все поля в форме будут неактивными).
display()

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

get_data($slashed)

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

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

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

  • $slashed - экранировать кавычки. По умолчанию true.
add_element()
add_group()
add_rule()
set_default()
is_submitted()

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

is_cancelled()

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

setAdvanced($elementName, $advanced)

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

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

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

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

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

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

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

Константа Значение
PARAM_INT Только целые числа
PARAM_INTEGER Только целые числа, alias для PARAM_INT
PARAM_NUMBER Целые числа и числа с плавающей точкой
PARAM_ALPHA Только английские буквы
PARAM_ALPHANUM Только числа и латинские буквы.
PARAM_ALPHAEXT То же, что и PARAM_ALPHA, дополнительно разрешены символы "\"(слеш), "_"(подчеркивание), "-"(минус).
PARAM_NOTAGS Удалить все html-теги. Не злоупотребляйте этим типом.
PARAM_TEXT Основной тип для передачи текста - подходит для обработки строк на разных языках, содержит знаки препинания, не пропускает html-тегов
PARAM_FILE Получить безопасное имя файла. Все нежелательные символы удаляются, защита от XSS, SQL-инъекций, и просмотра директорий.
PARAM_SEQUENCE Числовая последовательность: только цифры и запятые. Пример: 1, 7, 155, 19
PARAM_TAG Одно или несколько слов, разделенные пробелами. Используется для составления облака тегов (список интересов и т.п.). Поддерживает национальные алфавиты.
PARAM_TAGLIST Список тегов через запятую. Поддерживает национальные алфавиты.
PARAM_PATH Безопасное относительное имя файла. Все нежелательные символы удаляются, защита от XSS, SQL-инъекций, и просмотра директорий.
PARAM_HOST FQDN или IP-адрес (как 4 числа разделенные точками, например 123.123.123.123).
PARAM_URL Ожидается правильный URL-адрес. Учтите, что указание доменной зоны обязательно, например http://localhost/ не пройдет, но http://localhost.localdomain/ - пройдет.
PARAM_CLEANFILE безопасное имя файла, но в отличии от PARAM_FILE удаляются не только нежелательные символы, но и символы национального алфавита.
PARAM_BOOL Конвертирует параметр в 0 или 1. Используйте его для переключателей в формах и URL.
PARAM_CLEANHTML Очищает присланный HTML, и убирает слеши. Замечание: Не забудьте применить к этим данным addslashes() перед вставкой в базу!
PARAM_BASE64 данные в формате base64 encoding
PARAM_RAW НЕ ПРОВЕРЯТЬ данные. Используйте этот формат только для тестирования, либо в полной уверенности в том, что данные из этого поля будут проверены позднее.
validation($data, $files)

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

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

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

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

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

Заголовок формы

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

Код:

   $mform->addElement('header','имя_html-элемента', 'Текст заголовка');

Текстовое пояснение

Поле select

Элемент text

Элемент radio

Элемент checkbox

Элемент textarea

Элемент hidden

Элемент dateselector

Добавление дополнительных данных

Установка обязательных полей

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

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

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

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

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

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

Установка зависимых полей