Этот документ является полным справочник к Forms API Друпала. Если вас интересует пошаговая интрукция о том, как создавать собственные формы, вам лучше начать с быстрого введения в Forms API.
Жирным шрифтом помечены параметры, которые, в большинстве случаев, обязательно стоит заполнить при создании элемента.
button
Описание: Обычная кнопка. При нажатии, форма передается в обработчик Друпала, где она проходит валидацию и перестройку. Submit-обработчик формы не выполняется по-умолчанию, но можно использовать#executes_submit_callback, чтобы это изменить.
<?php
$form['copy'] = array(
'#type' => 'checkbox',
'#title' => t('Send me a copy.'),
);
?>
checkboxes
Описание: Группа чекбоксов. Здесь, #options — это ассоциативный массив. При обработке, форма возвратит в параметре #return_value значение, которое находится в ключах массива. На самой форме отображаются значения этого массива. Массив #options не может содержать элементов с ключем равным .
<?php
$form['node_options_'. $node->type] = array(
'#type' => 'checkboxes',
'#title' => t('Default options'),
'#default_value' => variable_get('node_options_'. $node->type, array('status', 'promote')),
'#options' => array(
'status' => t('Published'),
'moderate' => t('In moderation queue'),
'promote' => t('Promoted to front page'),
'sticky' => t('Sticky at top of lists'),
'revision' => t('Create new revision'),
),
'#description' => t('Users with the <em>administer nodes</em> permission will be able to override these options.'),
);
?>
date
Описание: Поле выбора даты. В параметре #default_value будет стоять сегодняшняя дата, если не указать другого. Форматом параметров #default_value и #return_value является массив с ключами ’year’, ’month’, and’day’: array('year' => 2007, 'month' => 2, 'day' => 15)
Примечание: следует включать $form['#attributes'] = array('enctype' => "multipart/form-data"); в описание формы. См. http://drupal.org/node/111782.
Примечание: Параметр #required этим элементом не поддерживается (его установка в TRUE будет всегда вызывать ошибки валидации). Вместо этого, используйте собственную функцию валидации для проверки массива $_FILES (но с #required должен быть FALSE). Кроме того, вам нужно самостоятельно позаботиться о выводе звездочки или другой пометки «обязательности» поля, если это необходимо. Это можно реализовать темизацией элемента (см #theme).
Описание: Элемент разметки. Служит для разметки внутри форм. При создании этого элемента нет нужды заполнять параметр #type = 'markup', так как это тип — по-умолчанию для всех элементов.
Обратите внимание: этот элемент не обертывается в html-теги вообще, поэтому не удивляйтесь если вдруг внутренние элементы этого поля криво вылезут на форме.
<?php
$form['contact_information'] = array(
'#value' => variable_get('contact_form_information', t('You can leave us a message using the contact form below.')),
);
?>
item
Описание: Поле с неменяющимся значением, заголовком и описанием.
Примечание: так как это поле «только для чтения», установка параметра #required повлияет только на вид этого поля (красная звездочка подле заголовка).
<?php
$form['weight'] = array(
'#type' => 'weight',
'#title' => t('Weight'),
'#default_value' => $edit['weight'],
'#delta' => 10,
'#description' => t('Optional. In the menu, the heavier items will sink and the lighter items will be positioned nearer the top.'),
);
?>
Параметры
#access
Описание: Будет ли элемент доступен на форме. Если равен FALSE, элемент не будет выведен на форме вообще.
<?php
$form['files']['file_directory_path'] = array(
'#type' => 'textfield',
'#title' => t('File system path'),
'#default_value' => file_directory_path(),
'#maxlength' => 255,
'#description' => t('A file system path where the files will be stored. This directory has to exist and be writable by Drupal. If the download method is set to public this directory has to be relative to Drupal installation directory, and be accessible over the web. When download method is set to private this directory should not be accessible over the web. Changing this location after the site has been in use will cause problems so only change this setting on an existing site if you know what you are doing.'),
);
$form['#after_build'] = array('system_check_directory');
...
function system_check_directory($form, $form_element) {
file_check_directory($form_element['#value'], FILE_CREATE_DIRECTORY, $form_element['#parents'][0]);
return $form_element;
}
?>
Массив, который определяет вид и поведение элемента с AHAH функциональностью.
Параметр #ahah обеспечивает AHAH (Асинхронный HTML и HTTP) — родственный AJAX’у подходу для динамического обновления веб-страниц. AHAH прост и функционален — ответы сервера возвращают HTML код, который вcтавляется в нужное место страницы.
Корректная работа AHAH обеспечивается исполнением этих шагов:
Друпал конструирует и выводит элемент с #ahah параметрами. К странице автоматически цепляется JavaScript файл misc/ahah.js.
ahah.js ищет на странице все элементы, у которых выставлен параметр #ahah['path'] и навешивает свой обработчик на событие #ahah['event'] элемента.
Когда происходит данное событие (напр. 'click'), обработчик отсылает запрос на путь, указанный в#ahah['path'] (это путь из меню Друпала).
Друпал генерирует HTML и отдает его этому запросу. Пока все это происходит, пользователь видит на форме прогресс-бар или анимированную иконку, что определяется в #ahah['progress'].
Когда ahah.js получает ответ от друпала, он вставляет возвращенный HTML в #ahah['wrapper']. Метод вставки результата на страницу определяется в #ahah['method'].
#ahah['effect']
Описание: Определяет эффект, используемы для вставки контента из AHAH запроса.
Допустимые значения: Строка. Возможные значения: 'none' (по-умолчанию), 'fade', 'slide'. При установленной JQuery библиотеке Interface elements, любые эффекты с названием effectToggle могут быть также использованы.
<?php
$form['choice_wrapper']['poll_more'] = array(
'#type' => 'submit',
'#value' => t('More choices'),
'#description' => t("If the amount of boxes above isn't enough, click here to add more choices."),
'#weight' => 1,
'#submit' => array('poll_more_choices_submit'), // If no javascript action.
'#ahah' => array(
'path' => 'poll/js',
'wrapper' => 'poll-choices',
'method' => 'replace',
'effect' => 'fade',
),
?>
#ahah['event']
Описание: Когда это событие происходит, Друпал отправляет HTTP запрос посредством JavaScript к пути, указанному в #ahah['path'].
Допустимые значения: Строка. Возможные значения: 'click', 'blur', 'change'. Имейте в виду, что#ahah['event'] не обязательно заполнять, так как каждому элементу присваивается свое событие по-умолчанию.
#ahah['method']
Описание: Определяет метод вставки возвращенного запросом HTML кода в селекторе #ahah_wrapper. Если ничего не выставлено, возвращенный HTML просто заменяет содержание элемента с аттрибутом idравным #ahah_wrapper. Кроме того, можно использовать любые методы операций с DOM в JQuery.
Описание: Если выставлен, параметр включает AHAH-поведение элемента. Значение этого параметра — друпаловский путь, с коллбэк-функцией, генерирующей HTML код и возвращающей этот код Друпалу. Результат будет помещен в место на странице, которое соответствует селектору #ahah['wrapper'].
Допустимые значения: Строка, содержащая путь в меню Друпала.
В этом примере #ahah['path'] заполнено путем 'upload/js', который определяется в этом же модуле (upload_menu). При обращении к 'upload/js', будет выполнена функция upload_js, которая сгенерирует HTML и возвратит его запрашивающей странице.
#ahah['progress']
Описание: Выбирает прогресс-бар или анимированную иконку (опционально, текст), которые будут показываться во время ожидания ответа от AHAH запроса.
#ahah['progress']['message'] Строка. Опциональное сообщение; должно быть пропущено через t().
#ahah['progress']['url'] Строка. Опциональный коллбэк для выяснения позиции прогресс-бара (по описанию из progress.js). Используется если 'type' равен 'progress'.
#ahah['progress']['interval'] Строка. Интервал запросов обновления прогресс-бара (по описанию из progress.js). Используется если установлен 'url' и 'type' равен 'progress'.
<?php
$form['weight'] = array(
'#type' => 'weight',
'#title' => t('Weight'),
'#default_value' => $edit['weight'],
'#delta' => 10,
'#description' => t('Optional. In the menu, the heavier items will sink and the lighter items will be positioned nearer the top.'),
);
?>
Описание: Текстовое описание или подсказка к элементу формы. Настоятельно рекомендуется сперва помещать эти значения в функцию t() для того, чтобы не терять возможности локализации формы.
<?php
$form['weight'] = array(
'#type' => 'weight',
'#title' => t('Weight'),
'#default_value' => $edit['weight'],
'#delta' => 10,
'#description' => t('Optional. In the menu, the heavier items will sink and the lighter items will be positioned nearer the top.'),
);
?>
<?php
$form['settings_general']['upload_usersize_default'] = array(
'#type' => 'textfield',
'#title' => t('Default total file size per user'),
'#default_value' => $upload_usersize_default,
'#size' => 5,
'#maxlength' => 5,
'#description' => t('The default maximum size of all files a user can have on the site.'),
'#field_suffix' => t('MB')
);
?>
Описание: Варианты выбора в списках (выпадающих, обычных, а также списках чекбоксов и переключателей).
Допустимые значения: Массив вида array(t('Значение 1'), t('Значение 2')) или array('return_value1' =>t('Значение 1'), 'return_value2' => t('Значение 2')) если элемент должен возвращать определенные значения.
ДЛЯ ВНУТРЕННЕГО ИСПОЛЬЗОВАНИЯ. Определяет, отрисован ли элемент уже.
#process
Описание: Массив функций (каждая вместе с массивом аргументов), которые будут вызваны при процессинге (обработке) формы. Часто используется для <a href="#ahah">#ahah</a> обработчиков. Используя этот параметр, модули могут навешивать дополнительные действия над элементом, например, тип «radios» расширяется дополнительными переключателями, используя функции процессинга.
Допустимые значения: Массив масивов
Пример использования (system.module) в <a href="/api/function/system_elements/6">system_elements()</a>:
В этом примере, вызывается без аргументов функция <a href="/api/function/expand_radios/6">expand_radios()</a>. Эта функция добавляет новые элементы типа radioпосредством добавления значений в массив #options обрабатываемого элемента (radios).
#processed
ДЛЯ ВНУТРЕННЕГО ИСПОЛЬЗОВАНИЯ. Определяет, обработана ли форма или элемент.
Описание: Адрес, на который попадает пользователь после обработки формы. Это значение по-умолчанию возвращается обработчиком формы (начиная с шестого Друпала, в $form_state['redirect']), но вы можете задавать произвольное значение используя параметр #redirect в hook_form_alter(). Смотрите также #action.
p>Допустимые значения: Внутренний путь или массив аргументов для функции url(). параметр также может быть установлен в FALSE, что приведет к отмене редиректа после обработки формы.
Описание: Определяет обязательность элемента. Если параметр выставлен, то при валидации формы, элемент автоматически проверяется на пустое значение. Поля загрузки файлов не могут быть обязательными.
Описание: Обеспечивает создание коллекций элементов. Чаще всего используется к «родительскому элементу» (у которгого выставлен параметр #parent). Смотрите статью #tree and #parents для подробного разбора работы этого параметра.
Описание: Список функций валидации, которые должна пройти форма или элемент перед submit-обработчиком. Используется для навешивания дополнительных проверок, или для использования своей функции вместо стандартной FROM_ID_validate.
Допустимые значения: Массив названий функций. Каждая функция должна принимать $form и$form_state в своих параметрах и использовать form_set_error(), если форма не проходит валидацию, например:
<?php
function test_form_validate($form, &$form_state) {
if ($form_state['values']['name'] == '') {
form_set_error('name', t('You must select a name for this group of settings.'));
}
}
?>
Описание: Используется для установки значений, которые не могут быть изменены пользователем. Не путать с #default_value, которое всего лишь устанавливает значение по-умолчанию.