Пишем модуль, Form API в Drupal 7 (уровень 2.1). Часть 1

Сложность: 
2

На фоне прочих популярных систем управления содержанием Друпал располагает массой неоспоримых преимуществ. И одно из них - это очень продуманное и логичное АПИ. В этой статье мы узнаем, как правильно написать модуль для Drupal 7, а также, напишем форму, которая будет добавлять или вычитать 2 числовых значения.

Структура модуля

Для начала нам нужно создать модуль. Каждый вновь создаваемый модуль должен состоять, как минимум, из 2 файлов:

  1. Файл с расширением .info - в нем будет находиться системная информация о модуле, как то: название модуля, его описание, версия и т.п.
  2. Файл с расширением .module - здесь будет находиться тело нашего модуля. Этот файл обычно содержит описание хуков и пользовательских функций.

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

  • Названия этих файлов всегда должны быть аутентичны, поскольку именно они определяют название модуля в системе друпал. Пример файлов модуля: my_module.info и my_module.module
  • Все модули должны содержаться в отдельной папке, которая, в свою очередь, должна находится в папке “sites/all/modules/custom”. Пример:  модуль имеет системное название “my_module”. В этом случае лучшее место, куда нужно разместить данный модуль это здесь: “[папка_сайта]/sites/all/modules/custom/my_module” (Если у вас нет папки “custom”, то создайте ее).

Написание файла .info

Как было сказано выше, нам предстоит создать, по сути, обычный калькулятор с использованием функционала Друпал. Назовем наш модуль “calculator”. Как видно из самого названия модуля, он у нас должен лежать в папке “[папка_сайта]/sites/all/modules/custom/calculator”. В этой же папке необходимо создать 2 файла. Создадим файл calculator.info, содержимое которого будет следующим:

1. name = Calculator
2. description = custom module to subtract and addition of numbers
3. version = 7.x-1.x-dev
4. core = 7.x

В строчке 1 указано название модуля - именно под этим названием он будет отображаться на странице списка модулей. Строчка 2 содержит описание модуля, которое тоже будет отображаться в списке модулей. В строчке номер 3 задается версия модуля. Последняя строчка указывает, какой из версий Друпала поддерживается данный модуль. В нашем случае указывается, что поддерживается он всеми версиями Друпал 7, то есть 7.0, 7.1 и т.д.

Написание файла .module

Файл .info нами написан. Самое время приступить к написанию файла .module. Его название должен быть аналогичным файлу .info, то есть calculator.module. Создадим файл и напишем первые его строчки:

<?php
 /**
 * @file
 * Build page and form for calculator.
 */

Что такое Хук?

Теперь приступаем к создатнию страницы. За создание страниц отвечает hook_menu.

Но сначала несколько слов отдельно о хуках. Хуки позволяют модулям взаимодействовать с ядром Друпал.
Модули, используемые в Друпале, работают по принципу «крюка» (англ. hook — крючок, ловушка). По сути, хук — это PHP функция с названием  calculator_hook_name(),  где “calculator” — отображение названия модуля (имя файла calculator.module), а «hook_name» — это название самого хука. Каждый хук имеет определенный набор параметров и типов результатов.

hook_menu

Как говорилось выше, hook_menu встраивается в ядро Друпал и делает возможным указание на страницы. Таким образом, давайте создадим страницу, в которой будет размещается наш будущий калькулятор. Пример кода будет выглядеть так:

1. /**
2.  * Implements hook_menu(). 
3.  */
4. function calculator_menu() {
5.   $items = array();
6.   $items['calculator-page'] = array(
7.     'title' => 'Calculator',
8.     'page callback' => 'drupal_get_form',
9.     'page arguments' => array('calculator_page_form'),
10.   'access callback' => TRUE,
11.  );
12   return $items;
  }

Рассмотрим написанный код:

  • В строчках 1-3 содержится описание комментария фукнции, т.е. что мы подключаем hook_menu.
  • Далее идет объявление функции (4), потом мы определяем переменную “items” как массив.
  • В 6 строке содержится указание та то, что адрес нашей страницы будет читаться так: “/calculator-page” (указан ключ массива).
  • 7 строчка задает заголовок нашей страницы.
  • Ключ “page callback” задает функцию, которая будет отвечать за вывод страницы. В данном случае указана функция “drupal_get_form”, эта функция обрабатывает форму перед ее выводом.
  • Строка 9 задает аргумент функции, которая указана в параметре “page callback”. То есть, в момент вывода страницы, у нас вызывается функция “drupal_get_form” с аргументом “calculator_page_form” (аргумент указан в значении параметра “page arguments”).
  • Параметр “access callback” (10) задает доступ к странице. В текущем состоянии, как это здесь указано, страница доступна всем без ограничений. Если же зададим здесь значение параметра “FALSE”, то страница перестанет быть доступной кому-либо. Также в данный параметр можно подставлять пользовательские функции.
  • В строчке номер 12 возвращаются все параметры, которые мы задали. 

Функция для вывода формы

 Давайте сразу же опишем пользовательскую функцию для вывода формы, которая указана в параметре “page arguments”, находящемся выше. Сама функция формы имеет следующий вид:

/**
* Build calculator form.
*/
function calculator_page_form($form, $form_state) { $form = array(); return $form; }

С этим все просто, как видите. Идет создание новой функции с двумя аргументами. Для функции, которая выводит форму  необходимо прописывать переменные в аргументах “form” и “form_state”. Теперь файл можно сохранить и включить модуль с названием “Calculator”, последний после этого должен отображаться в списке модулей Друпала (адрес на страницу “/admin/modules”). После включения модуля, Вам становится доступной страница, созданная ранее в hook_menu (страница по адресу “/calculator-page”).

Если, все же, эта страницау вас не открылась, или были допущены ошибки в самом коде, тогда выполните следующую последовательность шагов:

  1. Проверьте, действительно ли модуль “Calculator” включен. Если все же не включен, включите его.
  2. Сверьте код, который написан в hook_menu. Если какой либо элемент кода не прописан, сделайте необходимые добавления.
  3. Проверьте правильность написания функции, котороя отвечает за вывод формы.

ВАЖНО: Если у вас уже включен модуль, и вы делаете правки в hook_menu, то, после изменения параметров в этом хуке, нужно чистить кеш Друпала, поскольку данные о страницах в системе Друпал кешируются.  Очистить кеш можно обратившись к разделу Configuration -> Development -> Perfomance, где на самом верху страницы расположена кнопка “Clear all caches” (ссылка на страницу “/admin/config/development/performance”).

Объявление элементов формы

На данном этапе у нас написаны hook_menu и функция для вывода формы. Как видно из примера, в середине функции у нас объявилась переменная “form”, которая сразу же возвращается. В промежутке между объявлением и возвратом данной переменной мы должны описать нашу форму, вернее ее элементы.
Самый лучший справочник по элементам форм в Друпал можно найти по этой ссылке. Пусть вас не пугают объемы найденного в двух больших таблицах: на самом деле подаваемая информация отлично структурирована, и это облегчит вам ее восприятие.

Наш будущий калькулятор должен состоять из 3-х элементов: двух текстовых полей, в которые мы будем вводить 1е и 2е числовое значение и одно поле для выбора оператора (у нас пусть это будет выпадающим список), то есть у нас это "сложение" или "вычитание".
Для 2 числовых значений мы создаем 2 элемента с типом “textfield”. О данном типе элемента можно прочитать здесь.

Допишем следующие строчки в функции для вывода формы (calculator_page_form) между объявлением переменной “form” и возвратом этой переменной. Вот сам код:

$form['number1'] = array(
  '#type' => 'textfield',
  '#title' => t('Number 1'),
  '#size' => 20,
);
$form['number2'] = array(
  '#type' => 'textfield',
  '#title' => t('Number 2'),
  '#size' => 20,
);

Обратите внимание на то, что в массиве переменной “form” у нас имеется 2 ключа. Для каждого элемента указываются следующие параметры:

  • #type - обозначает тип элемента формы (обязательный параметр почти ко всем элементам формы).
  • #title - заголовок, который будет выводится у элемента.
  • #size - ширина нашего текстового поля.

Следует отметить, что 2 последние параметры применимы к элементу формы с типом “textfield”, у других элементов формы данные параметры могут отсутствовать.

Надо также иметь в виду, что ключи элементов формы должны быть уникальными. В данном случае ключами элементов формы есть сами системные названия ее двух элементов: “number1” и “number2”.

Обновите страницу, и давайте посмотрим, что же у нас получилось. Итак, результат наших усилий приобрел следующий вид:

Form API в Drupal 7

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

Теперь нам нужно задать выбор оператора, для чего мы воспользуемся возможностями выпадающего списа. Выпадающий список в Друпал имеет тип “select”. Пропишем следующие строчки кода между объявлением 2 текстового поля и возвратом формы:

$form['operator'] = array(
  '#type' => 'select',
  '#title' => t('Operator'),
  '#options' => array('+', '-'),
);

Как видно на рисунке, кроме параметров “#type” и “#title”, данный тип элемента содержит еще параметр “#options”. В нем указываются те элементы, которые будут отображаться в самом выпадающем списке.
Параметр “#options”  - заметьте - будет недоступен элементам формы с типом “textfield”. Сразу же давайте добавим кнопку, которая будет отправлять нашу форму. Код для кнопки прописываем следующий:

$form['submit'] = array(
  '#type' => 'submit',
  '#value' => t('Calculate'),
);

Таким образом, мы создали новый елемент формы с машинным названием “submit” (текст ключа элемента). Еще здесь есть опция “#type”, которую мы уже знаем, а также опция “#value”, которая задает текст, отображающийся на кнопке.

Весь код формы для функции будет выглядеть так:

/** 
* Build calculator form.
*/
function calculator_page_form($form, $form_state) { $form = array(); $form['number1'] = array( '#type' => 'textfield', '#title' => t('Number 1'), '#size' => 20, ); $form['number2'] = array( '#type' => 'textfield', '#title' => t('Number 2'), '#size' => 20, ); $form['operator'] = array( '#type' => 'select', '#title' => t('Operator'), '#options' => array('+', '-'), ); $form['submit'] = array( '#type' => 'submit', '#value' => t('Calculate'), ); return $form; }

Картинка страницы с формой будет иметь следующий вид:

Пишем модуль, Form API в Drupal 7

Итог

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

Рассказать друзьям: