В интерфейсе администратора с помощью hook_menu и Forms API будет создана форма, позволяющая указать список валют.
Выше уже была описана логика работы разрабатываемого модуля, сейчас, перед тем как написать первые строки кода, необходимо более подробно продумать алгоритм работы программы. Если говорить о нашем случае, то программа будет разбита на четыре основные части:
• интерфейс администратора;
• автоматически выполняемые процедуры;
• функции темизации;
• интерфейс пользователя.
В интерфейсе администратора с помощью hook_menu и Forms API будет создана форма, позволяющая администратору указать список валют, которые необходимо выводить в блоке, адрес XML-документа, из которого будет «подтягиваться» информация об обновленных курсах валют, и частоту обновления данных. Кроме того, с помощью hook_perm будет создано «право доступа», дающее возможность администратору сайта ограничить доступ к настройкам модуля.
Регулярно выполняемая процедура в модуле будет одна: при запуске строки cron-таблицы необходимо проверить, когда произошло последнее обновление данных о курсах валют. Если между текущим моментом и последним обновлением данных прошло время большее, чем указано в соответствующей настройке интерфейса управления модулем, то необходимо соединиться с сервером ЦБ, получить обновленные данные и сохранить их в базе.
Интерфейс пользователя создадим при помощи хука hook_block, позволяющего формировать блоки с данными. Чтобы верстальщик мог изменять внешний вид выводимых модулем данных, создадим свою функцию темизации, которую необходимо зарегистрировать в системе при помощи hook_theme.
Административный интерфейсТеперь приступим к реализации каждого из описанных этапов. Для начала добавим в наш файл currencies.module функцию:
function currencies_perm() {
return array('access currencies block settings');
}
Эта функция – реализация хука hook_perm, который, как сказано выше, определяет дополнительные права доступа. Hook_perm – один из самых простых хуков, он всего лишь возвращает массив строк, представляющих собой права доступа. После инсталляции модуля администратор сайта на странице Admin – Permissions (admin/user/permissions) может указать, какие группы пользователей имеют право доступа access currencies block settings, а мы в дальнейшем, во время реализации формы настроек модуля при помощи функции user_access, будем проверять, имеет ли текущий пользователь право доступа access currencies block settings или нет.
Важный момент. Пользователь с uid=1, т. е. первый созданный в системе, является суперпользователем, для него функция user_access всегда возвращает значение TRUE, а это значит, что он всегда имеет доступ ко всем функциям сайта. Это одна из причин, почему не рекомендуется работать в системе с учетной записью суперпользователя: зачастую разработчики забывают раздавать пользователям необходимые права доступа, так как сами, работая как суперпользователи, не имеют проблем с доступом к ресурсам сайта.
Для определения дополнительного системного пути, по которому в нашем примере будет доступна страница управления модулем, необходимо создать реализацию хука hook_menu:
function currencies_menu() {
$items = array();
$items['admin/settings/cur-block'] = array(
'title' => t('Currencies block settings'),
'description' => 'Currencies block settings.',
'page callback' => 'drupal_get_form',
'page arguments' => array('currencies_settings'),
'access arguments' => array('access cur block settings'),
);
return $items;
}
Эта функция также возвращает ассоциативный массив. Ключом каждого элемента массива должен быть путь, регистрируемый в системе (в нашем случае это admin/settings/cur-block), а значением – вложенный массив, содержащий информацию о создаваемом пункте меню. Давайте разберем каждый из параметров отдельно.
Title – заголовок меню – будет использоваться при переходе на страницу с адресом admin/settings/cur-block в строке заголовка браузера (тег <title>) и в качестве заголовка страницы (тег <h1>), а также в качестве текста ссылки, ведущей на созданную страницу настроек.
Description – описание пункта меню, которое в нашем случае будет использоваться на странице администрирования.
Page callback – функция, которая будет генерировать страницу, создаваемую по указанному пути. В простом случае значением этого параметра должна быть функция, возвращающая HTML-код, который будет показан пользователю. Однако мы по указанному адресу создаем не обычную страницу, а форму, значения которой автоматически сохраняются в БД. Поэтому для параметра page callback мы назначаем вызов системной функции drupal_get_form(), которая выведет на экран форму, созданную функцией с именем, указанным в элементе массива page arguments; в нашем случае это функция currencies_settings(). Функция currencies_settings() должна вернуть ассоциативный массив, содержащий информацию об элементах создаваемой формы. Подробнее об этом массиве будет рассказано ниже.
Access arguments – массив «прав доступа». Пользователи, обладающие правами доступа, перечисленными в этом массиве, могут получить доступ к создаваемому пункту меню.
Подготовка Web-страницыТема оформления в Drupal – это набор особым образом сформированных HTML-шаблонов и CSS-файлов, на основе которых ядро Drupal генерирует запрашиваемую пользователем страницу. Если в системе используется встроенный в Drupal шаблонный «движок» PHPTemplate, то каждая тема оформления может содержать служебный файл template.php, в котором могут размещаться функции, переопределяющие стандартный вывод модулей. У каждой темы оформления, как и у каждого модуля, должно быть свое уникальное имя и файл настроек .info.
Более подробную информацию о параметрах пунктов меню можно найти в документации.
Сейчас в нашем модуле определен новый пункт меню, но не определена функция, формирующая содержимое страницы, на которую этот пункт указывает (см. листинг 2).
Листинг 2function currencies_settings() {
$form['currencies_list'] = array(
'#type' => 'textfield',
'#title' => t('Currencies'),
'#default_value' => variable_get('currencies_list',
"USD,EUR,CNY,BYR,KZT,TRY,UAH,JPY"),
'#maxlength' => 255,
);
$form['currencies_list_freq'] = array(
'#type' => 'textfield',
'#title' => t('Frequency of updating of the data
(in seconds)'),
'#default_value' => variable_get('currencies_list_freq',
3600),
'#maxlength' => 255,
'#description' => t('It is recommended to use value
not less than 3600.'),
);
$form['currencies_list_url'] = array(
'#type' => 'textfield',
'#title' => t('Адрес xml-файла'),
'#default_value' => variable_get('currencies_list_url',
"http://www.cbr.ru/scripts/XML_daily.asp?date_req=
%d/%m/%y"),
'#maxlength' => 255,
'#description' => t('The XML-file address.'),
);
return system_settings_form($form);
}
Как и хуки hook_menu, hook_schema и многие другие хуки Drupal, эта функция должна возвращать ассоциативный массив, на этот раз содержащий информацию о параметрах создаваемой формы. Здесь мы создаем три однострочных текстовых поля (параметр #type имеет значение textfield), значения по умолчанию для которых (параметр #default_value) будут храниться и выбираться из стандартной таблицы variables Drupal при помощи функций variable_set() и variable_get(). Благодаря использованию функций drupal_get_form и system_settings_form нет необходимости заботиться о создании кнопок Submit и Reset, а также о функциях, обрабатывающих и сохраняющих данные формы. В более сложных случаях, которые будут рассмотрены в следующей статье, придется вручную создавать функции проверки введенных пользователем значений и сохранения данных.
Подробное описание типов полей, используемых в формах, можно найти в документации.
Все, мы завершили разработку первой из трех частей нашего модуля – административного интерфейса и переходим к разработке второй его части – инструмента получения данных от удаленного сервера.
Регулярные процедурыЧтобы Drupal периодически выполнял определенные действия, в планировщике задач операционной системы необходимо настроить запуск файла cron.php, который находится в корне каждого Drupal-сайта. При выполнении этого файла будет вызываться хук hook_cron, и в нашем модуле мы напишем его реализацию:
function currencies_cron() {
currencies_contents();
}
Процедура получения и обработки XML-файла, расположенного на удаленном сервере, довольно обычна, поэтому она здесь не приведена. При желании вы можете самостоятельно разобрать логику работы этой функции, изучив исходные коды модуля Currencies, которые есть на диске, прилагаемом к журналу. В результате ее работы формируется массив $result, в котором содержится информация о курсах валют и который передается функции темизации. Функцию currencies_contents() см. в листинге 3. Здесь мы сначала проверяем, нет ли запрашиваемых данных в кэше Drupal, если нет, то происходит соединение с удаленным сервером (его адрес указан через административный интерфейс модуля), получение и обработка XML-файла и формирование массива данных, который передает функции темизации. Функция темизации формирует выходной HTML-код, записываемый в кэш, его время жизни явно указывается исходя из соответствующей настройки, заданной в интерфейсе управления модулем. Drupal автоматически управляет закэшированными данными и при необходимости удаляет устаревшие записи.