Журнал PC Magazine/RE №11/2009 - PC Magazine/RE

<div class="node<?php if ($sticky) {

    print " sticky";

  } ?>

  <?php if (!$status) {

    print " node-unpublished";

  } ?>">

  <h2 class="title"><?php print $title?></h2>

  <span class="submitted"><?php print $submitted?></span>

  <div class="content"><?php print $content?></div>

</div>

Формы

Прежде чем говорить об изменении внешнего вида форм, ознакомимся с основами Drupal Forms API – программного интерфейса, используемого для генерации форм. Применение Forms API несколько сложнее создания HTML-форм вручную, так как требует изучения логики его работы, однако его использование обязательно, поскольку Forms API решает ряд важных задач:

• любой разработчик может добавить или удалить элементы в форме, созданной другим разработчиком, не меняя ее исходного кода;

• любой разработчик может добавить дополнительные функции проверки и обработки введенных пользователем данных без изменения исходной формы;

• формы, созданные с использованием Forms API, защищены от атак, связанных с отправкой пользователем модифицированной формы;

• любой разработчик может изменить внешний вид формы, не изменяя ее исходного кода.

Каждая форма в Drupal представляет собой функцию, возвращающую ассоциативный массив. Этот массив должен содержать информацию обо всех элементах формы, функциях проверки (валидаторы, validators) и обработки (сабмиттеры, submitters) введенных данных. Данная функция должна быть расположена в файле модуля, о разработке модуля говорилось в статье, опубликованной в PC Magazine/RE, 9/2009.

Рассмотрим простой пример.

function test_form($form_state) {

  $form["example_text_field"] = array(

    '#type' => 'textfield',

    '#title' => 'Example text field',

  );

  $options = array(

    0 => 'zero',

    1 => 'one',

    2 => 'two',

  );

  $form["example_select"] = array(

    '#type' => 'select',

    '#title' => 'Example select list',

    '#options' => $options,

    '#description' => t('You can select only value "one" in this

      form'),

  );

  $form["submit"] = array(

    '#type' => 'submit',

    '#value' => t('Submit'),

  );

  return $form;

}

Приведенная выше функция генерирует форму, состоящую из текстового поля, выпадающего списка с тремя элементами и кнопкой для отправки данных. Имя этой функции – ее уникальный идентификатор ($form_id), который будет использоваться для отображения и изменения данной формы сторонними модулями. Чтобы вывести форму на экран, нужно через hook_menu создать страницу, где будет вызвана функция drupal_get_form, принимающая в качестве параметра $form_id формы, которая должна быть отображена на экране:

function имя_модуля_menu() {

  $items = array();

  $items['test-form'] = array(

    'title' => 'Test form',

    'page callback' => 'test_form_page',

    'access arguments' => array('access content'),

    'type' => MENU_NORMAL_ITEM,

  );

  return $items;

}

function test_form_page() {

  return drupal_get_form('test_form');

}

В массиве, возвращаемом функцией test_form($form_state), не определены процедуры проверки значений и заполнения полей (структур), поэтому ядро Drupal после нажатия на форме кнопки Submit попробует найти и выполнить функции form_id_validate и form_id_submit. В нашем случае, как легко догадаться, это будут функции с именами test_form_validate и test_form_submit:

function test_form_validate($form, &$form_state) {

  if($form_state['values']['example_select'] != 1) {

    form_set_error('example_select', t('You must select value

      "one" in select list :)'));

  }

}

function test_form_submit($form, &$form_state) {

  drupal_set_message('Form sumitted! Values:');

  drupal_set_message("textbox: " .

    $form_state['values']['example_text']);

  drupal_set_message("selectlist: " .

    $form_state['values']['example_select']);

}

Функция-валидатор проверяет выбранное в выпадающем списке значение и, если оно не one, посылает сообщение об ошибке с указанием, какой элемент формы вызвал ошибку. Функция-сабмиттер выводит на экран введенные пользователем значения. В реальном случае эта функция должна будет сохранить данные в базе данных.

При желании программист может в массиве $form функции test_form задать свойство #submit, содержащее массив обработчиков значений и свойство #validate с массивом валидаторов (см. листинг 4). Зеленым цветом выделены строки, добавленные к ранее описанным функциям. Код модуля также дополнится функциями из листинга 5.

Листинг 4

function test_form($form_state) {

  $form["example_text_field"] = array(

    '#type' => 'textfield',

    '#title' => 'Example text field',

    '#description' => 'Text must contain more then

      3 symbols',

  );

  $options = array(

    0 => 'zero',

    1 => 'one',

    2 => 'two',

  );

  $form["example_select"] = array(

    '#type' => 'select',

    '#title' => 'Example select list',

    '#options' => $options,

    '#description' => t('You can select only value "one"

      in this form'),

   );

  $form["submit"] = array(

    '#type' => 'submit',

    '#value' => t('Submit'),

  );

  $form["#validate"] = array('test_validate_first',

    'test_validate_second');

  $form["#submit"] = array('test_submit_first',

    'test_submit_second');

  return $form;

}

Листинг 5

function test_validate_first($form, &$form_state) {

  if(mb_strlen($form_state['values']['example_text_field']) < 3) {

    form_set_error('example_text_field', t('Text must contain more then 3 symbols'));

  }

}

function test_validate_second($form, &$form_state) {

  if($form_state['values']['example_select'] != 1) {

    form_set_error('example_select', t('You must select value "one" in select list :)'));

  }

}

function test_submit_first($form, &$form_state) {

  drupal_set_message('First submitter');

  drupal_set_message("textbox: " . $form_state['values']['example_text']);

}

function test_submit_second($form, &$form_state) {

  drupal_set_message('Second submitter');

  drupal_set_message("selectlist: " . $form_state['values']['example_select']);

}

Здесь добавлен валидатор, который проверяет текст, введенный в текстовое поле; если его длина оказывается меньше трех символов, то генерируется сообщение об ошибке.

При создании форм всегда рекомендуется использовать не стандартные валидаторы и сабмиттеры, а объявлять их явно, так как в этом случае сторонние программисты смогут дополнить массивы #submit и #validate своими функциями. Если используются стандартные валидаторы и сабмиттеры, то сторонние программисты смогут только заменить существующие функции своими, а это не всегда удобно.

На заметку: полезные модули

Signwriter. Часто бывает необходимо использовать в заголовке страницы или меню какой-либо экзотический шрифт, отсутствующий у большинства посетителей сайта. Модуль Signwriter генерирует картинки с текстом, написанным заданным шрифтом (шрифт предварительно должен был закачан на сервер). Через меню администратор может включить замену заголовков страниц и блоков созданными картинками, а через специальную функцию и вовсе можно заменить картинками любой текст.

Blocktheme. Не всегда удобно создавать и закачивать на сервер шаблоны под каждый используемый на сайте блок. Кроме того, реализованная в Drupal система масок имен для шаблонов не для всех задач бывает достаточно гибкой. Модуль Blocktheme позволяет через интерфейс управления блоками выбрать для каждого из них один из заранее созданных шаблонов.

Devel. Мощный инструмент в руках Drupal-разработчика. Разработчику тем оформления модуль Devel предоставляет информацию обо всех используемых для генерации страницы шаблонах и функциях темизации.

PNG Fix. Модуль, исправляющий проблему с непрозрачностью PNG-файлов в браузерах IE 5.5 и IE 6. Настраивается работа модуля через интерфейс администратора, изменение файлов темы оформления не требуется.

Теперь вернемся к основной теме статьи – темизации Drupal. Функция drupal_get_form, получив на вход $form_id, идентификатор формы, которую нужно вывести на экран, вызывает функцию form_builder, проверяющую права доступа текущего пользователя к каждому из полей формы, и при наличии этих прав выводит стандартный HTML-код для каждого элемента формы. Каждый созданный элемент формы имеет уникальный атрибут id. Самый простой способ переопределения внешнего вида элементов формы – создание CSS-файла с описанием стилей нужных элементов формы. Если этого недостаточно, элементам формы можно добавить параметры #prefix и #suffix, которые будут содержать HTML-код, выводимый до и после созданного элемента. Если и этого мало, можно определить параметр #theme, который должен содержать используемое имя функции темизации.

Персональные функции темизации можно задать для всей формы целиком или для каждого ее элемента. По умолчанию Drupal для темизации формы пробует найти функцию theme_form_id, поэтому использование параметра #theme не обязательно.

Все функции, определенные параметром #theme, должны быть также объявлены через hook_theme (описание этого хука было дано в предыдущей статье).

Давайте изменим внешний вид созданного текстового поля. Для этого сначала создадим реализацию хука hook_theme:

function название_модуля_theme() {

  return array(

    'example_text_field_theme_function' => array(

      'arguments' => array('form' => NULL),

    ),

  );

}

Затем модифицируем массив $form["example_text_field"], который создается в функции test_form, добавив в него параметр #theme:

$form["example_text_field"] = array(

  '#type' => 'textfield',

  '#title' => 'Example text field',

  '#description' => 'Text must contain more then 3 symbols',

  '#theme' => 'example_text_field_theme_function',

);

Теперь мы можем объявить функцию theme_example_text_field_theme_function и задать в ней любой HTML-код для отображения выбранного элемента:

function theme_example_text_field_theme_function($element) {

  $class = "";

  if(isset($element["#needs_validation"])) {