Создание модулей: Создание файлов

Модули — базовые блоки, образующие основу Drupal. Кроме того, они представляют собой механизм расширения функциональности изначально поставляемой версии Drupal, которая называется ядром Drupal. Тем, кто не знаком с Drupal, я часто говорю, что модули похожи на элементы конструктора “Лего”. Следование заранее оговоренным правилам позволяет им абсолютно точно сочетаться друг с другом, и такие сочетания модулей позволяют создавать мощные и сложные решения.

Модули Drupal делятся на две общие категории — основные и дополнительные. Основные модули поставляются вместе с Drupal и включают в себя такие модули, как опросы, меню, таксономия, поиск, агрегатор новостей и форумы. Дополнительные модули — это все модули, созданные сообществом, которое расширяет и усовершенствует функциональные возможности ядра Drupal. Дополнительных модулей буквально тысячи, они доступны для загрузки по адресу http://drupal.org/project/modules и охватывают диапазон от простых модулей для решения одной задачи (вроде вывода текущей даты и времени) до сложных решений наподобие интерфейсов для электронной коммерции.

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

Создание файлов

Сначала нужно выбрать имя для модуля. Вполне годится имя “annotate” — и коротко, и понятно. После этого понадобится выбрать место для хранения модуля. Сторонние и разработанные самостоятельно модули хранятся в каталоге /sites/all/modules, причем каждый модуль в собственном подкаталоге, имя которого совпадает с именем модуля.

Можно создать каталог /sites/all/modules/custom для хранения всех модулей, созданных с нуля — так вы облегчите жизнь тому, кто будет просматривать ваш сайт и интересоваться, какие модули загружены с сайта Drupal.org, а какие специально разработаны для данного сайта. Теперь в каталоге /sites/all/modules/custom необходимо создать подкаталог annotate, который будет содержать все файлы, связанные с модулем аннотирования. Первым файлом, который мы создадим для нового модуля, будет annotate.info. У каждого модуля в Drupal 7 должен быть файл .info, имя которого должно совпадать с именем самого модуля. Для модуля аннотации базовая информация, которая необходима для распознавания модуля системой Drupal, выглядит так:
 

name = Annotate
description = "Allows users to annotate nodes."
package = Pro Drupal Development
core = 7.x
files[] = annotate.module
files[] = annotate.install
configure = admin/config/content/annotate/settings

Структура этого файла стандартна для всех модулей Drupal 7. Элемент name используется для вывода имени модуля на странице Modules configuration (Конфигурация модулей). Элемент description описывает модуль и также выводится на странице Modules configuration. Элемент package определяет пакет или группу, с которой связан модуль. На странице Modules configuration модули сгруппированы по пакетам. Поле core определяет версию Drupal, для которой написан модуль. Элемент php указывает версию PHP, необходимую для работы модуля. Наконец, элемент files представляет собой массив имен файлов, связанных с модулем. С нашим модулем аннотации связаны файлы annotate.module и annotate.install.

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

name =Annotate
description = "Allows users to annotate nodes."
package = Pro Drupal Development
core = 7.x
dependencies[] = forum
dependencies[] = taxonomy
files[] = annotate.module
files[] = annotate.install
php = 5.2

Теперь все готово для создания самого модуля. Создайте в подкаталоге sites/all/ modules/custom/annotate файл по имени annotate.module. В начало этого файла поместите открывающий дескриптор PHP и дескриптор идентификации CVS, а за ними комментарий:

<?php
/**
* @file
* Позволяет пользователям добавлять в ноды персональные аннотации.
*
* При выводе ноды добавляет текстовое поле, которое позволяет
* аутентифицированным пользователям вставлять примечания.
*/

Обратите внимание на стиль комментария. Он начинается с символов /**, продолжается строками со звездочкой с одним предшествующим пробелом ( *) и завершается отдельной строкой с символами */. Элемент @file означает, что содержимое последующих строк описывает действие файла. Такое однострочное описание используется компонентом автоматического извлечения и форматирования документации api.module (см. http://drupal.org/project/api). На сайте Drupal.org посетите страницу http://api.drupal.org. Там находится подробная документация по каждому API-интерфейсу, предоставляемому Drupal. Не поленитесь и просмотрите этот раздел сайта — это бесценный источник для тех, кто разрабатывает или изменяет модули.

После пустой строки добавлено более развернутое описание, предназначенное для программистов, которые будут изучать (и, конечно же, улучшать) наш код. Обратите внимание, что здесь специально не использован закрывающий дескриптор ?> — в PHP они не обязательны и даже могут привести к проблемам с завершающими пробельными символами в файлах (см. http://drupal.org/coding-standards#phptags).

Теперь необходимо определить некоторые параметры, чтобы можно было использовать веб-форму для выбора нод, которые пользователь захочет аннотировать. Для этого понадобится выполнить два шага. Сначала мы определим путь, где будут находиться параметры настройки, а потом создадим форму параметров. Для создания пути необходимо реализовать хук, а именно — hook_menu.