Разработка: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 - только для фреймов. Имя фрейма, обрабатывающего эту форму. Используется крайне редко. По умолчанию пустая строка.
• $attributes - строка атрибутов для тега <form>. Будет добавлена внутрь тега. Разрешены любые атрибуты, предусмотренные стандартом HTML 4.01. По умолчанию null.
• $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(), но используется для динамических форм, в случаях, когда вам нужно добавить дополнительные поля в форму после отправки данных пользователем.

elementExists($name)

Только для использования внутри definition_after_data(). Проверяет существование элемента с указанным именем в форме.

• $elementName - имя элемента для проверки

removeElement($name)

Только для использования внутри definition_after_data(). Удалить ранее созданный элемент с указанным именем из формы.

• $elementName - имя элемента для удаления

getElementValue($name)

Только для использования внутри definition_after_data(). Получить введенное значение из указанного элемента формы.

• $elementName - имя элемента, значение из которого вы хотите получить

getElement($name)

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

Пример 1: Установка нового значения поля после отправки данных пользователем.

   // получаем новое значение
   $newvalue = 'foo';
   // получаем ранее созданный элемент (например типа "text")
   $element =& $mform->getElement('my_element');
   // устанавливаем в него новое значение
   $element->setValue($newvalue);

Пример 2: установка новых вариантов в поле select после отправки данных пользователем.

   // создаем новые варианты для элемента
   $options = array();
   $options[-1] = 'Новый вариант1';
   $options[-2] = 'Новый вариант2';
   // получаем ранее созданный элемент типа "select"
   $element =& $mform->getElement('my_element');
   // загружаем новые данные в элемент
   $element->load($options);

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);

setDefault('elementName', $value)

Установить значение $value по умолчанию для элемента elementName.

   $mform->addElement('hidden', 'имяэлемента');
   $mform->setDefault('имяэлемента', $value);

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

   $mform->setDefault('имягруппы[имяэлемента]', $value);

Для элемента hierselect в качестве второго аргумента нужно указывать массив со значениями по умолчанию для каждого уровня:

   $mform->setDefault('имяэлемента', array(14, 2, 8));

setConstant('elementName', $value)

Установить постоянную переменную $value по умолчанию для элемента elementName.

   $mform->addElement('textarea', 'имяэлемента','Текстовое поле');
   $mform->setDefault('имяэлемента', $value);

Не перекрывается _GET и _POST. Возможно использование, когда setDefault не помогает.

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);

insertElementBefore($element, $nameAfter)

Вставляет элемент перед уже ранее добавленным функцией add_element(). Этот метод полезно применять в динамических формах, внутри функции definition() или definition_after_data().

• $element - Объект вставляемого элемента. Для создания объекта используйте функцию create_element();
• $nameAfter - Имя элемента перед которым будет вставлен элемент

Помните, что имя каждого элемента в форме должно быть уникальным (кроме элементов типа radio).

Пример:

   // создаем элемент
   $element =& $mform->createElement('text', 'my_new_text', 'Пояснение к текстовому полю');
   // добавляем его перед уже ранее созданным элементом
   $mform->insertElementBefore($element, 'my_old_text');

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

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

• $element - имя элемента, к которому применяется проверка
• $message - сообщение, в случае если проверка не пройдена
• $type - тип правила проверки (см. таблицу ниже)
• $format - дополнительные данные, требующиеся для некоторых проверок. По умолчанию null.
• $validation - на какой стороне производить проверку. Возможные значения:
  • server - на стороне сервера (по умолчанию)
  • client - на стороне клиента
• $reset - используется при проверке на стороне клиента. Сбрасывать ли данные в этом поле на значение по умолчанию, если введены неправильные данные? по умолчанию false (не сбрасывать).
• $force - применять ли проверку даже если проверяемый элемент не существует? По умолчанию false (не применять). Этот параметр используется для проверок в динамических формах.

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

Имя	Описание	Пример кода
required	Обязательное поле	$mform->addRule('testname','Это поле является обязательным', 'required',null,'client');
minlength	Минимальная длина значения в поле.	$mform->addRule('testname','Слишком короткое значение', 'minlength', 10,'client');
maxlength	Максимальная длина значения в поле.	$mform->addRule('testname','Слишком длинное значение', 'maxlength', 256,'client');
rangelength	Проверка длины значения с обеих сторон: например не больше 5 и не меньше 7. Параметры задаются массивом из двух элементов. В данном примере от 111 до 222.	$mform->addRule('testname','Длина значения неправильна', 'rangelength', array(111, 222),'client');
email	Проверка email-адреса	$mform->addRule('testname','неправильный email', 'email',null,'client');
regex	Проверка данных регулярными выражениями. Используется редко, в случае, когда обычных проверок недостаточно.
lettersonly	Только латинские буквы.	$mform->addRule('testname','Ошибка', 'lettersonly', null,'client');
alphanumeric	Только латинские буквы и цифры	$mform->addRule('testname','Ошибка', 'alphanumeric', null,'client');
numeric	Целое или дробное число	$mform->addRule('testname', 'В этом поле разрешены только числа', 'numeric', null, 'client');
nopunctuation	В строке не должны присутствовать специальные символы. Список: ()./*^?#!@$%+=,"'><~[]{}	$mform->addRule('testname', 'Введены запрещенные символы', 'nopunctuation', null, 'client');
nonzero	Ненулевое значение	$mform->addRule('testname', 'Только ненулевые значения', 'nonzero', null, 'client');
callback	Использовать пользовательскую функцию для проверки данных. Используется крайне редко, если у вас есть сложные проверки - то лучше используйте для них функцию validation().
compare	Сравнить два значения. Может использоваться для сравнения чисел и строк. Операторы, используемые для сравнения: == равно != не равно > больше >= больше или равно < меньше <= меньше или равно
uploadedfile
maxfilesize	Проверка максимального значения файла для конкретного поля
mimetype	Проверка mime-типа загруженного файла.
filename	Проверка имени файла. Убираются все потенциально опасные символы.

is_submitted()

Возвращает true если форма подтверждена кнопкой типа "submit", и false в противном случае. Обратите внимание, что кнопка "отмена" в форме также является кнопкой типа "submit", поэтому используйте для этих целей функцию is_canceled(). Для проверки того, что данные отправлены в форму, и корректно прошли все проверки на стороне сервера и клиента, можно использовать такую конструкцию:

if ( $form->is_submitted() AND confirm_sesskey() AND $formdata = $form->get_data() AND ! $form->is_cancelled() )
{//даные переданы и прошли все проверки

    ....

}elseif( $form->is_cancelled() )
{// ввод данных отменен

    ....

}

Здесь:

• $form->is_submitted() - проверка того, что данные в форме были отправлены кнопкой типа "submit"
• confirm_sesskey() - проверка того, что данные отправлены внутри текущей сессии (встроенная функция moodle)
• $formdata = $form->get_data() - получение данных формы, и одновременное подтверждение того, что данные прошли все проверки, не не нажата кнопка "отмена".

Также возможно сначала проверять is_canceled(), а потом is_submitted().

is_cancelled()

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

setAdvanced($elementName, $advanced)

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

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

setShowAdvanced($showadvancedNow)

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

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

add_action_buttons($cancel, $submitlabel)

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

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

add_checkbox_controller($groupid, $buttontext, $attributes, $originalValue)

Добавляет переключатель (ссылку или кнопку), контролирующий состояние нескольких элементов типа advcheckbox.

• $groupid - id группы элементов типа advcheckbox, которую контролирует этот переключатель
• $buttontext - текст на кнопке переключателя. По умолчанию "выделить все".
• $attributes - ассоциативный массив html-атрибутов для тега, описывающего переключатель
• $originalValue - Возможные состояния: 0 или 1. Изначальное состояние всех переключателей контролируемой группы. По умолчанию 0 (все галочки сняты).

setType($elementname, $paramtype)

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

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

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

validation($data, $files)

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

Используется для дополнительной проверки данных на стороне сервера. Все необходимые сложные проверки должны быть проведены именно здесь. Для простых проверок (на тип данных, проверка email-адреса и т. п.) используйте функцию addRule()

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

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

disabledIf($elementName, $dependentOn, $condition, $value)

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

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

• $elementName - имя зависимого элемента.
• $dependentOn - имя элемента, чье состояние должно быть проверено условием $condition.
• $condition - по умолчанию 'notchecked'.
• $value - значение, используемое для проверки условия. По умолчанию "1".

Таблица вариантов условий для параметра $condition

Значение	Пояснение
checked	Элемент выделен. Используется для элементов radio и checkbox. Не работает с элементами advcheckbox.
notchecked	Элемент не выделен. Используется для элементов radio и checkbox. Не работает с элементами advcheckbox.
eq	Значение указанного элемента равно значению указанному в параметре $value.
noteq	Значение указанного элемента не равно значению указанному в параметре $value.
noitemselected	В указанном html-элементе "select" ничего не выбрано.

applyFilter($elementName, $functionName);

Применить проверку элементу формы.

Параметры

• $elementName - название элемента внутри формы. В качестве имени можно использовать специальное значение __ALL__ чтобы применить проверку ко всем элементам.
• $functionName - название функции (без скобок и аргументов), которая должна быть применена к этому элементу

Пример:

   // применение проверки ко всем элементам
   $mform->applyFilter('__ALL__', 'trim');
   
   // применение проверки к одному элементу
   $mform->applyFilter('lastname', 'addslashes');

closeHeaderBefore($elementName)

Закрыть рамку формы до элемента с указанным именем. Эта функция позволит вам выносить нижние элементы "за пределы" визуальной рамки формы, а также добавлять элементы без заголовка. Иными словами, эта функция закрывает тег <FIELDSET>. Эта функция должна быть обязательно вызвана ПОСЛЕ добавления элемента, перед которым закрывается рамка формы.

Пример:

   // добавляем элемент формы
   $mform->addElement('text', 'name', $this->dof->get_string('name','plans').':');
   // Выносим его, и следующие элементы за рамку формы
   $mform->closeHeaderBefore('name')

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

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

header

Заголовок формы. Этот заголовок будет говорить об общем содержании данных в форме. Также он используется в случае, когда вам нужно разбить форму на несколько частей. Если вам нужно закрыть рамку заголовка перед каким-либо элементом, используйте функцию closeHeaderBefore()

$mform->addElement('header','testname', 'Текст заголовка');

checkbox

Стандартный html-элемент checkbox.

$mform->addElement('checkbox', 'testname', 'Текст_перед_галочкой', 'Текст_после галочки');

file

Стандартное диалоговое окно загрузки файла.

$mform->addElement('file', 'userfile', 'Текст перед окном загрузки файла');

group

Добавление группы элементов. Для того, чтобы добавить группу элементов, их нужно предварительно создать при помощи функции create_element() Параметры (в порядке перечисления):

• тип
• название элемента
• пояснение
• массив с элементами
• разделитель для элементов (в примере - тег <br>)
• добавить ли имя группы к имени элемента (true - добавить)

    // создаем массив
    $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, '<br>', true);

password

Стандартный html-элемент password

mform->addElement('password', 'testname', 'Текст перед окном с паролем');

passwordunmask

То же самое, что и элемент password, но с дополнительной галочкой "отобразить пароль".

$mform->addElement('passwordunmask', 'testname', 'Текст перед окном с паролем');

radio

Стандартный html-элемент radio. Единственный элемент в quickform, несколько объектов которого можно добавить, используя одинаковое значение name.

$mform->addElement('radio', 'testname', 'Текст до переключателя 1', 
'Текст после переключателя 1', 'Значение1');
$mform->addElement('radio', 'testname', 'Текст до переключателля 2', 
'Текст после переключателя 2', 'Значение2');

select

Стандартный html-элемент select. Массив $choices содержит варианты для оператора select. Значениями массива являются текстовые надписи в списке выбора, а ключами - значения этих вариантов.

    // создаем массив с вариантами выбора
    $choices = array('a' => 'Текст варианта 1', 'b' => 'Текст варианта 2');

    // Добавляем элемент формы
    $mform->addElement('select', 'testname', 'Пояснение для строки выбора', $choices);

Дополнительные функции

Элемент select обладает дополнительными методами, которые

• addOption($text, $value, $attributes=null) - добавить новый вариант к select-элементу, уже после того как он был создан, и в него были установлены значения. Параметры:
  • $text - текст, который отображается пользователю
  • $value - значение, которое передается из формы
  • $attributes - дополнительные html-атрибуты тега OPTION (если требуется). Передаются строкой, либо массивом в формате ключ-значение.

Пример:

$select = $mform->getElement('testname');
$select->addOption('Текст для отображения', 555);

text

Стандартный html-элемент text. Последний параметр - строка html-атрибутов. В данном примере длина поля задана 100%. Это гарантирует, что элемент будет нормально выглядеть и умещаться в форму при любых размерах экрана.

$mform->addElement('text', 'testname', 'Пояснение для текстового поля', ' width="100%" ');

textarea

Стандартный html-элемент textarea. Значения ширины и высоты задаются в виде массива, последним аргументом. Ширину поля также рекомендуется задавать 100%.

$mform->addElement('textarea', 'testname', 'Пояснение:', array('width'=>'100%', 'height'=>'100px'));

date_selector

Диалоговое окно с выбором даты. Обратите внимание, что при получении данных через get_data() значение этого поля автоматически трансформируется в метку unixtime на 12:00:00 дня выбранной даты. По умолчанию выставляется текущая дата и время. Другое начальное значение может быть задано при помощи функции setDefault().

$options = array();// объявляем массив для установки значений по умолчанию
$options['startyear'] = 1980; // устанавливаем год, с которого начинать вывод списка
$options['stopyear']  = 2001; // устанавливаем год, которым заканчивается список
$options['optional']  = false; // убираем галочку, делающую возможным отключение этого поля

$mform->addElement('date_selector', 'testname', 'Пояснение для поля даты', $options);
// устанавливаем время по умолчанию на год вперед
$mform->setDefault('testname', time()+3600*24*365);

date_time_selector

Этот элемент аналогичен элементу date_selector, только добавлены параметры часов и минут. Полученные данные также трансформируются в unixtime, но уже для выбранных значений часов и минут. По умолчанию выставляется текущая дата и время. Другое начальное значение может быть задано при помощи функции setDefault().

$options = array();// объявляем массив для установки значений по умолчанию
$options['startyear'] = 1980; // устанавливаем год, с которого начинать вывод списка
$options['stopyear']  = 2001; // устанавливаем год, которым заканчивается список
$options['optional']  = false; // убираем галочку, делающую возможным отключение этого поля

$mform->addElement('date_time_selector', 'testname', 'Пояснение для поля даты', $options);

htmleditor

Полноценный html-редактор для редактирования страниц. Его вид (обычный или расширенный) настраивается индивидуально каждым пользователем для себя (в настройках профиля moodle). Обратите внимание, что в качестве дополнительных параметров можно массивом передать значения ширины и высоты текстового поля.

$mform->addElement('htmleditor', 'testname', 'Пояснение:', array('width'=>'100%', 'height'=>'200px')

format

Выбор формата для редактирования сообщения. Полезно использовать вместе со встроенным html-редактором.

$mform->addElement('format', 'testname', 'Текст пояснения');

static

Обычное текстовое поле, не передает никаких данных. Полезно использовать для различных пояснений и отображения текущей информации о каком-либо объекте. Вы также можете использовать этот элемент для разбиения формы на небольшие смысловые блоки, не разрывая рамку формы. Для более явного разбиения используйте элемент header.

$mform->addElement('static', 'testname', 'Пояснение:', '<b><i>Само текстовое значение</i></b>');

hidden

Стандартный html-элемент hidden, скрытое поле для передачи служебных id, адресов для перенаправления и т. д. Помните о необходимости проверки значений из этого поля.

$mform->addElement('hidden','testname', 'Значение скрытого поля');

modvisible

Установить модуль видимым/скрытым. Только для использования внутри Mooodle.

selectyesno

Элемент с двумя стандартными select-вариантами выбора: да и нет.

    $mform->addElement('selectyesno', 'testname', 'Текст пояснения');
    // установить значение по умолчанию "да"
    $mform->setDefault('stoponerror', 1);

modgrade

Шкала выставление оценки за задание. Только для использования внутри Moodle.

cancel

Кнопка "отменить форму". При нажатии на нее происходит отмена всех произведенных в форме действий.

$mform->addElement('cancel', 'testname', 'Надпись на кнопке'); 

button

Элемент аналогичен кнопке типа submit, но при использовании button пропускается проверка данных на стороне клиента.

$mform->addElement('button', 'testname', 'Надпись на кнопке');

choosecoursefile

Выбрать файл из курса. Только для использования внутри курса Moodle.

submit

Кнопка отправки данных из формы. Обязательно ставьте ее в конце, иначе все введенные данные нельзя будет отправить. Существует также альтернативный способ задать такую кнопку - это функция get_data()

$mform->addElement('submit', 'testname', 'Текст на кнопке');

questioncategory

Выбрать вопрос из категории. Только при редактировании теста и только внутри курса Moodle.

advcheckbox

Элемент checkbox c расширенными функциями - такие элементы можно объединять в группы и устанавливать им контрольный переключатель (делает либо все галочки поставлеными либо снятыми) при помощи функции add_checkbox_controller().

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

Несовместим с функцией disabledIf()

$mform->addElement('advcheckbox', 'testname[1]', 'Описание:', 'Текст за галочкой', array('group' => 'id_группы'));

$mform->addElement('advcheckbox', 'testname[2]', 'Описание:', 'Текст за галочкой', array('group' => 'id_группы'));

recaptcha

Окно с картинкой для использования Capcha проверки. Обратите внимание, что для того чтобы использовать этот элемент вы сначала должны получить уникальный ключ с на сайте http://recaptcha.net/api/getkey.

$mform->addElement('recaptcha', 'testname', 'Текст с пояснением');

hierselect

Несколько зависимых друг от друга html-элементов типа "select". В зависимости от выбранной опции в первом элементе, меняются значения остальных. При вызове функции addElement в последнем параметре указывается, какими символами разделять операторы select.

// для начала создадим два массива - по количеству операторов select
// которые нам предстоит создать

// Первый, главный элемент select
$select1[0] = 'Pop';
$select1[1] = 'Classical';
$select1[2] = 'Funeral doom';

// второй элемент select - его варианты зависят от первого
$select2[0][0] = '--- Artist ---';
$select2[0][1] = 'Red Hot Chil Peppers';
$select2[0][2] = 'The Pixies';
      
$select2[1][0] = '--- Artist ---';
$select2[1][1] = 'Wagner';
$select2[1][2] = 'Strauss';
      
$select2[2][0] = '--- Artist ---';
$select2[2][1] = 'Pantheist';
$select2[2][2] = 'Skepticism';

// добавляем новый элемент в форму
$myselect =& $mform->addElement('hierselect', 'testname', 'Текст с пояснением:',null,'<br>');
// устанавливаем для него варианты ответа
$myselect->setOptions(array($select1, $select2));
// устанавливаем значения по умолчанию: 'Funeral doom'->'Pantheist'
$mform->setDefault('testname', array(2, 1));

html

Добавить собственный html-код. Используйте этот тип элементов формы, только в случае, если ни один из перечисленных элементов вам не подходит, или нужно решить какую-либо нетривиальную задачу с форматированием. Может помочь в случае решения задачи разбиения формы на 3, или более колонок ([1] [2]).

$mform->addElement('html', '<div class="qheader">');

autocomplete

Элемент, который автоматически подсказывает варианты по мере набора текста. Выглядит как обычный элемент text, но имеет встроенный javascript. Значение по умолчанию устанавливается стандартным образом.

// Создаем массив подсказок
$options = array('апельсин', 'ананас', 'авокадо');
// добавляем новый элемент в форму
$element =& $mform->addElement('autocomplete', 'testname', 'Текст с пояснением:', 'size=12');
// устанавливаем массив подсказок
$element->setOptions($options);

dof_calendar

Элемент, который автоматически отображает 2 календаря для выбора диапазона дат. Календари находятся на одной линии. Под каждым календарем поле-указывает в формате д.м.гг дату, которая выбрана на календаре. В скрытое поле каждого календаря помещается время в unixtime, причем первый календарь (слева) отсчитывает время от 00.00.01, а второй (справа) с 23.59.59. Если на правом и на левом календарях отмечена одна дата, то диапазон, соответственно, равен 00.00.01-23.59.59, что полностью охватывает выбранный день. Так же, у этого элемента есть возможность удаления тегов, как правил это select-поля(старый вариант выбора дат). Для этого нужно в $options указать имена этих полей

Пример:

// добавляем новый элемент в форму
$element = $mform->addElement('dof_calendar', 'calendarname', 'Текст с пояснением:', $options),где 
'Текст с пояснением:' - Текст, который будет выведен выше календарей
$options - массив, с указанием дат(левый и правый календарь)
* $options['date_from'] - с какой даты брать отсчет(левый календарь)(unix time)
* $options['date_to']  - по какую дату брать отсчет(правый календарь)(unix time)
-------------
* $options[] = 'field_from'; (элемент будет удален  $mform->addElement('date_selector', 'field_from',$this->dof->modlib('ig')->igs('from'),$options); )
* $options[] = 'field_to';   (элемент будет удален  $mform->addElement('date_selector', 'field_to',$this->dof->modlib('ig')->igs('from'),$options); )

Если параметр options опущен, то берется текущая дата. Важно !! При объявлении времени, нужно брать массив именно с этими параметры(date_from, date_to). Выходные данные имеют вид

 [calendarname] = Array
       [date_from] = ... (unux time)
       [date_to] = ... (unux time)

dof_autocomplete

Элемент с выпадающим списком подсказок по мере набора текста. Выглядит как обычный элемент text, но имеет встроенный javascript. В помощь с ним создается автоматически hidden поле, значение которого будет равно индексу выбранного элемента (name="id_autocomplete" id="id_hidden_auto"). В dof_autocomplete есть обязательные параметры, работа без которых невозможна. Записываются они в переменную массив $options. В неё же и помещается массив $options(ключ=>значение), это так называемые значения по умолчанию (необязательные).

• Список обязательных полей для переменной $options:
  • plugintype - тип плагина (например storage)
  • plugincode - код плагина (например plans)
  • querytype - тип запроса, именно по нему и определяется, что надо делать( например plans_name ). Этот тип должен совпадать с типом, который будет находиться в этом в плагине в методе widgets_field_variants_list
  • sesskey - ключ сессии(чтоб идентифицировать запрос) задается методом sesskey()
  • type - тип действия ( например autocomplete ). Есть ещё тип savefield
• Необязательные поля:
  • default - массив значений по умолчания( например $a[19]= "primer"), где ключ - это id элемента из бд
  • departmentid - id подразделения, из которого пришел запрос
  • extoptions - подключает расширенные возможности dof_autocomplete

Простой пример

$mform->addElement('dof_autocomplete', $elementName = null, $elementLabel = null, $attributes = null, $options = null);

Более подробный пример

    //Создаем массив входных данных
    $options = array();
    $options['plugintype'] =   "storage";
    $options['plugincode'] =   "plans";
    $options['querytype']  =   "plans_name";
    $options['sesskey']    =   sesskey();
    $options['type']       =   'autocomplete'; 
    $options['departmentid'] = $departmentid;
    // установим значение по умолчанию
    $default = array( 19 => 'Test text' );
    $options['default'] = $default;

    // добавляем новый элемент в форму
    $mform->addElement('dof_autocomplete', 'testname', 'Надпись перед полем:', array('width' => '100%'), $options);

• Замечение:
  • следует помнить, что элемент autocomplete сам в себе подключает js-библиотеки, и потому, объявление класса формы на странице должно быть раньше, чем печать шапки страницы
  • выходные данные имеют вид

 [testname] = Array
       [text] = выбранное в меню значение (текст, который отображается в поле формы)
       [id] = id выбранного объекта (как правило число)

Необходимые методы: Плагин, данные которого будут составлять автозаполнение должен иметь метод widgets_field_variants_list($querytype, $data=""), который возвращает массив объектов в формате

 
$a = array();
a[1] = object(
          name -> ЗНАЧЕНИЕ_1 ДЛЯ ВЫПАДАЮЩЕГО СПИСКА
            id -> id элемента_1
             );
a[2] = object( 
          name -> ЗНАЧЕНИЕ_2 ВЫПАДАЮЩЕГО СПИСКА
            id -> id элемента_2
             ); 
   ...  
]

Здесь:

• $querytype - тип запроса (только маленькие латинские буквы, цифры и знак подчеркивания)
• $data - входные данные, (как правило строка) набранные данные в поле autocomplete

Замечания:

• поля name и id обязательны в возвращаемых объектах
• рекомендуется возвращать не более 15 записей для быстрой работы AJAX-запроса, пользуйтесь ограничением SQL-выборки

Расширенный autocomplete

Добавляет к возможностям dof_autocomplete не только выбирать значения, но и создавать их, переименовывать и удалять. Активируется при помощи дополнительного параметра extoptions, который имеет свои настройки:

• empty - активирует пустое значение(для удаления)
• create - активирует создание записи
• rename - активирует переименование записи

Сами по себе настройки не взаимосвязаны, поэтому можно задавать только необходимые нам расширения. Отсутствие всех настроек не активирует ни одного расширения. Настройки empty и create активируются передачей обычного булевского значения true, для активации rename понадобится передача id переименовываемого обьекта.

Пример активизации расширенного autocomplete

$options['extoptions'] = new stdClass;
$options['extoptions']->create = true;
if (!empty($id))
{
    $options['extoptions']->empty = true;
    $options['default'] = array($id => $name.' ['.$id.']');
    $options['extoptions']->rename = $id;
}

Для обработки значений autocomplete используется метод из modlib/widgets get_extvalues_autocomplete($name,$autocomplite), где

• name - имя поля dof_autocomplete,
• autocomplite - данные полученыые из get_data() формы поля dof_autocomplete.

Замечания:

• Использовать расширенные возможности можно только выбрав соответствующий пункт из меню. Обычное "стирание" или "вбивание" данных не дадут никакого эффекта.

dof_duration

Элемент для задания длительности временного интервала в часах, днях, неделях, и т. п.

// задаем возможные единицы измерения: часы и минуты
$options['availableunits'] = array(60   => $this->dof->modlib('ig')->igs('minutes'),
                                   3600 => $this->dof->modlib('ig')->igs('hours'));
// добавляем сам элемент
$mform->addElement('dof_duration', 'testname', 'Текст с пояснением:', $minutesoptions);

dof_single_use_submit

Одноразовая submit-кнопка. Отправляет данные формы и сразу же становится неактивной, для того чтобы избежать повторного нажатия и отправки данных (doubleclick). Имеет дополнительный метод setPleaseWaitText(), при помощи которого можно устанавливать надпись, которая появляется после нажатия на кнопку.

// создаем кнопку, с надписью "сохранить"
$submit = &$mform->addElement('dof_single_use_submit', 'testsinglesubmit', $this->dof->modlib('ig')->igs('save'));
// Устанавливаем сообщение после нажатия - "обработка"
$submit->setPleaseWaitText($this->dof->modlib('ig')->igs('processing'));

Решение наиболее распространенных задач

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

Установка обязательных полей происходит при помощи функции addRule().

Пример:

   // устанавливаем поле "город"
   $mform->addElement('text', 'city', 'Город :', 'maxlength="100" size="30"');
   // делаем поле обязательным
   $mform->addRule('city','Это поле является обязательным', 'required',null,'client');

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

Установка дополнительных полей производится при помощи функции setAdvanced(). Необязательные элементы должны располагаться один за другим.

Пример:

   // устанавливаем два текстовых поля и делаем их необязательными
   $mform->addElement('text', 'my_field1', 'Пояснение :');
   $mform->setAdvanced('my_field1');
   $mform->addElement('text', 'my_field2', 'Пояснение :');
   $mform->setAdvanced('my_field2');

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

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

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

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

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

Все малозначимые проверки желательно производить на стороне клиента для увеличения быстродействия приложения. Все проверки на стороне клиента производятся при помощи функции addRule().

В параметре validation обязательно нужно указать 'client'.

Пример:

   // устанавливаем поле "фамилия"
   $mform->addElement('text', 'lastname', 'Фамилия :');
   // делаем его обязательным
   $mform->addRule('lastname','Это поле является обязательным', 'required',null,'client');

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

Стандартный вариант

Установка зависимых полей производится при помощи функции disabledIf().

Пример:

   // Устанавливаем элемент checkbox
   $mform->addElement('checkbox', 'my_checkbox', get_string('forcedownload', 'resource'));
   // устанавливаем текстовое поле
   $mform->addElement('text', 'my_field', 'Пояснение :');
   // устанавливаем зависимость
   $mform->disabledIf('my_field', 'my_checkbox', 'checked');

Расширенный вариант

Для html-элеметов "select", есть возможность установить иерархическую зависимость элементов (то есть в зависимости от того, что было выбрано в первом "select", меняются значения в остальных). Синтаксис этого элемента указан в разделе Элементы формы (в самом конце, он называется hierselect).

Известные проблемы

В этом разделе собраны обнаруженные проблемы с элементами формы и способы их решения.

Данные не приходят из поля формы, даже в validation

Возможно на странице обработчика формы есть функция optional_param (или required_param) которая называется точно также как поле в форме. Если это так, то указанное поле из данных формы пропадет.

text

• Поле ввода слишком широкое, слишком узкое, или вылезает за границы заголовка
  • Решение: Нужно в свойства элемента добавить style="width:100%;". В этом случае элемент растянется до конца формы, и не будет вылезать за границы формы вне зависимости от того - большой монитор у пользователя или маленький.
  • Пример:

$mform->addElement('select', 'my_select', 'Description...', $options, ' style="max-width:400px;width:100%;" ');

textarea

• Поле ввода слишком широкое, слишком узкое, или вылезает за границы заголовка
  • Решение: Нужно в свойства элемента добавить style="width:100%;". В этом случае элемент растянется до конца формы, и не будет вылезать за границы формы вне зависимости от того - большой монитор у пользователя или маленький.
  • Пример:

$mform->addElement('textarea', 'name', 'Description...',  array('style' => 'width:100%;max-width:400px;height:150px;'));

hierselect

• Не работает Javascript если в качестве значения hierselect используются цифры
  • Решение: в списке значений после цифры добавлять пробел, или любой другой символ.
  • Пример: array('1' => "1 "); вместо array('1' => "1");
• Невозможно отключить только одно поле hierselect не отключая при этом остальные
  • Решение: отсутствует.
• При количестве select-элементов 3 или больше портится верстка. Подписи к select-элементам не совпадают с самими элементами.
  • Решение: до элемента hierselect вставить html-элемент который содержит div, устанавливающий фиксированный межстрочный интервал (см. пример). После добавления hierselect-элемента закрыть div.
  • Пример:

    // выравниваем строки по высоте
    $mform->addElement('html', '<div style=" line-height: 1.9; ">');
    
    // Дальше идет объявление hierselect...
    // ...
    
    // закрываем тег выравнивания строк
    $mform->addElement('html', '</div>');

• При указании строковых ключей массива hierselect не работает. Это происходит из-за того что в Javascript мы можем иметь дело либо с индексированными массивами, либо с объектами. Ассоциативные массивы там не предусмотрены.
  • Решение: не использовать ассоциативные ключи массивов при создании элементов hierselect. Если же обойтись без них никак нельзя - то можно закодировать ассоциативные элементы числами ('option1' - 1, 'option2' - 2 и т. д.), а на стороне обработчика раскодировать обратно.
• По неизвестным причинам иногда перестает работать переключение с одной опции на другую.
  • Решение: скорее всего в списке дочерних опций присутствуют элементы не для всех родительских опций (см. пример). Для каждой опции верхнего уровня должен присутствовать хотя бы один элемент нижнего уровня.
  • Пример:

Неправильный код:

$level1 = array();
$level1[0] = 'option0';
$level1[1] = 'option1';

$level2 = array();
$level2[1][0] = 'option1_0';
$level2[1][1] = 'option1_1';

Правильный код:

$level1 = array();
$level1[0] = 'option0';
$level1[1] = 'option1';

$level2 = array();
$level2[0][0] = 'option0_0'; // без этой строки ничего не будет работать
$level2[1][0] = 'option1_0';
$level2[1][1] = 'option1_1';

• Данные из поля hierselect передаются вне зависимости от того, было отключено поле или нет.
  • Решение: отсутствует.
• При проверке данных в функции validation() нельзя сообщить о том, что ошибка произошла внутри какого-то конкретного select-элемента.
  • Решение: отсутствует. Можно указать только указывать сам hierselect-элемент как источник ошибки, и сообщить подробности в сообщении.

hidden

• Не работает правило disabledif. Невозможно установить значение из hidden-поля для использования disabledif-правила.
  • Решение: создать другой элемент (например checkbox), записать в него нужное значение, и в стилях установить ему display:none
  • Пример:

$mform->addElement('radio', 'hidden_hack', '', '', 'true', 'style' => 'display:none;');

Ссылки

• Справка по базовым методам класса HTML_QuickForm
• Справки по элементам класса moodleform
• Getting Started Guide по элементам оригинального класса HTML_QuickForm. Некоторые обращения к методам могут отличаться от moodleform.
• [3] Примеры объявления элементов.