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

; $Id$

В файлах с PHP-кодом после открывающего тега <?php необходимо добавить строку

// $Id$

Эту строку, если модуль будет размещен в официальном CVS-репозитории Drupal, заменит служебная информация.

Далее в файле .info должны располагаться три обязательных параметра: название модуля, его описание и версия ядра Drupal, с которой работает модуль. Кроме того, в этом файле могут находиться необязательные параметры: минимальная версия PHP, необходимая для запуска модуля, зависимость от других модулей Drupal, без которых текущий модуль не будет работать, и пр. Подробное описание всех доступных к использованию в .info-файле параметров можно найти в официальной документации (ссылка на эту и другие цитируемые в статье страницы документации размещена во врезке «Ссылки на документацию»).

В нашем случае файл currencies.info будет иметь такой вид:

; $Id$

name = Currencies block

description = Show currencies

core = 6.x

Хотя один файл в нашем модуле уже есть, но пока он отсутствует в списке имеющихся в системе модулей, и мы переходим к следующему файлу.

currencies.install

По стандартам кодирования Drupal перед каждой функцией, реализующей хук, должен быть размещен комментарий вида:

/*

 * Implementation of hook_название_хука().

 */

Аналогичный комментарий (только без текста Implementation of...) с описанием функции и ее аргументов должен располагаться перед любой другой функцией. Эти комментарии используются системой генерации документации Doxygen, по ним также удобно вести поиск. Здесь для экономии места такие комментарии опущены.

Система управления сайтом Drupal построена по модульному принципу: ядро расширяется при помощи модулей – файлов с PHP-кодом.

При инсталляции и деинсталляции модулей вызываются хуки hook_install и hook_uninstall. Отмечу, что в Drupal кроме понятий инсталляции и деинсталляции есть понятия активации и деактивации модуля. Если модуль устанавливается впервые (в административном интерфейсе, в списке модулей установлена галочка напротив нужного модуля и нажата кнопка Submit), сначала происходит событие install, затем событие enable, т. е. ядро Drupal ищет и, если находит, вызывает функции, реализующие хуки hook_install и hook_enable для устанавливаемого модуля. Далее, если администратор выключает модуль, то происходит событие disable и вызывается функция, реализующая хук hook_disable. В следующий раз, когда модуль будет вновь включен, произойдет только событие enable, а не install. Если модуль был сначала деактивирован, а затем удален (удаление производится на отдельной от списка модулей странице), то происходят события disable и uninstall и в следующий раз при включении модуля опять произойдут события install и enable.

Такое разделение очень удобно. Обычно при возникновении события install программисты создают необходимые для работы модуля таблицы в базе данных, а при событии uninstall – удаляют их, таким образом после деинсталляции модуля в системе не остается никаких свидетельств его присутствия. При включении и выключении модуля (enable и disable) никакие сохраненные модулем данные не удаляются, а лишь отключается функционал модуля.

При возникновении события install программисты создают необходимые для работы модуля таблицы в базе данных

Вернемся к нашему примеру. Информацию о курсах валют разрабатываемый модуль currencies будет получать с сервера Центрального Банка РФ. Чтобы при каждом показе блока не обращаться с запросом к удаленному серверу, данные будут сохраняться в базе данных нашего сайта. В самом простом случае для хранения данных можно было бы воспользоваться функциями cache_set или variable_set из ядра Drupal, однако такой подход не очень удобен, когда нужно хранить информацию о курсах валют за длительный период, например, для последующего ее анализа. Поэтому мы создадим отдельную таблицу в базе данных и в ней будем хранить всю полученную информацию.

Наш пример довольно прост, поэтому события enable и disable использоваться в нем не будут, а на install и uninstall мы назначим функции создания и удаления таблицы в БД, для чего в файле currencies.install разместим функции, реализующие хуки hook_install и hook_uninstall:

function currencies_install() {

  drupal_install_schema('currencies');

}

function currencies_uninstall() {

  drupal_uninstall_schema('currencies');

}

Функции drupal_install_schema и drupal_uninstall_schema являются частью Drupal Schema API. Schema API – это слой абстракции от базы данных, благодаря которому программист может не задумываться о том, как адаптировать свой SQL-запрос под ту или иную базу данных, ему достаточно сформировать массив определенного вида и передать его одной из функций Schema API, после чего этот массив будет преобразован в корректный SQL-запрос к той базе данных, которая используется с Dupal. Единственный аргумент, который принимают эти две функции, – название модуля, схема которого будет установлена или удалена, т. е. после вызова drupal_install_schema('currencies') Drupal попытается создать таблицы, описанные в реализации hook_schema модуля currencies, поэтому нужно создать эту реализацию (см. листинг 1). Этот хук должен возвращать ассоциативный массив, содержащий информацию о создаваемых таблицах. В нашем примере создается таблица с именем currencies_block и двумя полями: timestamp и data. Подробное описание формата возвращаемого массива можно найти в документации.

function currencies_schema() {

  $schema['currencies_block'] = array(

    'description' => t('Some table description.'),

    'fields' => array(

      'timestamp' => array(

        'type' => 'int',

        'size' => 'normal',

        'not null' => TRUE,

        'default' => 0,

      ),

      'data' => array(

        'type' => 'text',

        'not null' => TRUE,

      ),

    ),

  );

  return $schema;

}

На данном этапе в нашем модуле currencies есть два файла: currencies.info и currencies.install, но он по-прежнему недоступен для выбора на странице со списком модулей, поскольку в нем отсутствует самый важный файл – .module. Если в папке модуля создать файл currencies.module и разместить в нем всего две строчки:

<?php

// ; $Id$

(их описание было дано выше), модуль тут же станет доступным для установки, однако, так как файл currencies.module не содержит никаких инструкций, установка этого модуля приведет только к созданию одной таблицы в БД и он не будет нам полезен. Поэтому мы переходим к самому большому, сложному и важному этапу – разработке основного функционала модуля.

currencies.module

В Drupal реализован механизм «ролей» и «прав доступа». По умолчанию в системе есть две «роли» (группы) пользователей – анонимы и авторизованные пользователи, одна из которых автоматически присваивается каждому пользователю в зависимости от того, авторизован он в системе или нет. Каждый модуль может объявить «права доступа» к своим ресурсам, после чего администратор сайта через специальный интерфейс может установить, какие роли имеют доступ к каким сервисам сайта. Например, обычно пользователи, входящие в группу авторизованных, могут вести персональный блог, а у анонимов такой возможности нет. В любой момент администратор сайта через Web-интерфейс может создать дополнительные роли (модераторы, администраторы и т. п.), определить особые разрешения для каждой из ролей (например, модераторы могут снимать с публикации материалы и комментарии, а администраторы их безвозвратно удалять) и назначать эти роли любому пользователю, причем ему одновременно может быть присвоено несколько ролей.

В интерфейсе администратора с помощью hook_menu и Forms API будет создана форма, позволяющая указать список валют.

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

• интерфейс администратора;

• автоматически выполняемые процедуры;

• функции темизации;

• интерфейс пользователя.

В интерфейсе администратора с помощью hook_menu и Forms API будет создана форма, позволяющая администратору указать список валют, которые необходимо выводить в блоке, адрес XML-документа, из которого будет «подтягиваться» информация об обновленных курсах валют, и частоту обновления данных. Кроме того, с помощью hook_perm будет создано «право доступа», дающее возможность администратору сайта ограничить доступ к настройкам модуля.

Регулярно выполняемая процедура в модуле будет одна: при запуске строки cron-таблицы необходимо проверить, когда произошло последнее обновление данных о курсах валют. Если между текущим моментом и последним обновлением данных прошло время большее, чем указано в соответствующей настройке интерфейса управления модулем, то необходимо соединиться с сервером ЦБ, получить обновленные данные и сохранить их в базе.

Интерфейс пользователя создадим при помощи хука hook_block, позволяющего формировать блоки с данными. Чтобы верстальщик мог изменять внешний вид выводимых модулем данных, создадим свою функцию темизации, которую необходимо зарегистрировать в системе при помощи hook_theme.