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

Теперь приступим к реализации каждого из описанных этапов. Для начала добавим в наш файл 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 – массив «прав доступа». Пользователи, обладающие правами доступа, перечисленными в этом массиве, могут получить доступ к создаваемому пункту меню.

Тема оформления в Drupal – это набор особым образом сформированных HTML-шаблонов и CSS-файлов, на основе которых ядро Drupal генерирует запрашиваемую пользователем страницу. Если в системе используется встроенный в Drupal шаблонный «движок» PHPTemplate, то каждая тема оформления может содержать служебный файл template.php, в котором могут размещаться функции, переопределяющие стандартный вывод модулей. У каждой темы оформления, как и у каждого модуля, должно быть свое уникальное имя и файл настроек .info.

Более подробную информацию о параметрах пунктов меню можно найти в документации.

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

function 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 автоматически управляет закэшированными данными и при необходимости удаляет устаревшие записи.

function currencies_contents() {

  if(!$c = cache_get('currencies')) {

    /* здесь пропущен код, отвечающий за получение

       и обработку XML-файла */

    $output = theme('currencies_block', $result);

    $t = variable_get('currencies_list_freq', 3600);

    if(!$t || !is_numeric($t)) $t = 3600;

    cache_set("currencies", $output, 'cache', time() + $t);

  } else {

    $output = $c->data;

  }

  return $output;

}

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

Теперь подробнее остановимся на функциях темизации (theming; термин не слишком благозвучен, но уже стал общепринятым). Теоретически прямо в коде функции currencies_contents() можно было бы сформировать HTML-код, который в дальнейшем и видел бы посетитель сайта в браузере. Однако такой подход неверен, поскольку при изменении оформления данных пришлось бы менять код модуля, а это влечет за собой две проблемы. Во-первых, модуль могут использовать сторонние разработчики, и им для внесения изменений придется вникнуть в структуру модуля и внести в него изменения, которые могут привести к ошибкам. Во-вторых, часто при разработке крупных проектов версткой и программированием занимаются разные люди. Верстальщик может не иметь представления о том, как работать с языком PHP в целом и модулями Drupal в частности. По этому правильнее вынести все действия, связанные с оформлением данных, в отдельные файлы и функции, для чего и нужны функции темизации.