Грамотное взаимодействие со сторонними библиотеками в Drupal через Libraries API
Здорово, посоны! Сегодня поделюсь информацией, как ровные разработчики подключают сторонние библиотеки к Drupal 7. Дело в том, что сообщество Drupal не приветствует включение сторонних библиотек, классов в состав отдельного модуля. Решать эту проблему мы будем через Libraries API.
Для начала работы нам потребуется установить модуль Libraries API, который является гибкой оберткой для работы с внешними библиотеками и предоставляет набор хуков и вспомогательных функций. Преимущества использования Libraries API:
- отдельная библиотека может использоваться несколькими модулями;
- контроль версий подключаемых библиотек;
- взаимодействие с CSS, JS и PHP файлами;
- унифицированная система взаимодействия с библиотеками, понятная всем разработчикам.
Libraries API требует обычного включения и создания папки
в libraries
. Теперь на примере подключения библиотеки jScrollPane я постараюсь показать, как использовать возможности модуля. Libraries API предоставляет новый хук sites
, являющийся обязательным при описании новой библиотеки:hook_libraries_info
- /**
- * Implements hook_libraries_info().
- */
- function MODULE_libraries_info() {
- // В качестве ключа массива выбираем произвольное удобное название.
- $libraries['jscrollpane'] = array(
- // Человекопонятное название библиотеки.
- 'name' => 'jScrollPane plugin',
- // Ссылка на официальный ресурс библиотеки.
- 'vendor url' => 'http://jscrollpane.kelvinluck.com/',
- // Ссылка на страницу скачивания библиотеки.
- 'download url' => 'http://jscrollpane.kelvinluck.com/#download',
- // Информация для определения версии библиотеки.
- 'version arguments' => array(
- // Имя файла для парсинга, содержащего информацию о версии.
- 'file' => 'jquery.jscrollpane.min.js',
- // Регулярное выражение для определения версии.
- 'pattern' => '@(?i:jScrollPane) - v([0-9\.a-z]+)@',
- // Количество строк файла для парсинга (опционально).
- 'lines' => 5,
- ),
- // Список файлов загружаемых при подключении библиотеки. Доступные ключи: js, css, php.
- 'files' => array(
- 'js' => array(
- 'jquery.jscrollpane.min.js',
- ),
- 'css' => array(
- 'jquery.jscrollpane.css'
- ),
- ),
- );
-
- return $libraries;
- }
Собственно, я привел пример минимально необходимого описания массива
для подключения. Хук $libraries['jscrollpane']
обладает более гибкими настройками, с которыми, при желании, вы можете ознакомиться в официальной документации. Теперь, согласно описанию библиотеки jScrollPane, необходимо поместить файлы jquery.jscrollpane.min.js и jquery.jscrollpane.css в корень папки hook_libraries_info
.sites/libraries/jscrollpane
Подключение и использование библиотек
Теперь, когда файлы библиотеки лежат в нужном месте и имплементирован хук, вы можете смело использовать библиотеку:
- libraries_load('jscrollpane');
Для более гибкого взаимодействия можно сделать и так:
- // Пытаемся загрузить библиотеку и проверяем ее на работоспособность.
- if (($library = libraries_load('jscrollpane')) && !empty($library['loaded'])) {
- // Рабочий код.
- }
Если необходимо просто убедится в наличии библиотеки:
- if (($library = libraries_detect($name)) && !empty($library['installed'])) {
- // Библиотека установлена.
- }
- else {
- // Ошибка. Библиотека не найдена :(
- // Следующий код вернет короткий статус проблемы. Например, 'not found'.
- $error = $library['error'];
- // Этот код вернет более детализированное описание проблемы.
- $error_message = $library['error message'];
- }
Контроль статуса и версии библиотек
В качестве бонуса к этому посту расскажу, как выводить информацию о библиотеке на странице статуса Drupal
. Для этого придется добавить в ваш .install-файл имплементацию хука admin/reports/status
.hook_requirements
- /**
- * Implements hook_requirements().
- */
- function MODULE_requirements($phase) {
- $requirements = array();
-
- if ($phase == 'runtime') {
- $t = get_t();
- $library = libraries_detect('jscrollpane');
-
- if (empty($library['installed'])) {
- // Сообщение о том, что библиотека не установлена
- $requirements['jscrollpane_plugin'] = array(
- 'title' => $t('jScrollPane plugin'),
- 'value' => $t('At least @a', array('@a' => '2.0.17')),
- 'severity' => REQUIREMENT_ERROR,
- 'description' =>
- $t('You need to download the !jscrollpane, extract @js_file and @css_file files from the archive and
- place them to the root of "jscrollpane" directory in the %path directory on your server.',
- array(
- '!jscrollpane' => l($t('jScrollPane plugin'), $library['download url']),
- '%path' => 'sites/all/libraries',
- '@js_file' => 'jquery.jscrollpane.min.js',
- '@css_file' => 'jquery.jscrollpane.css',
- )
- ),
- );
- }
- elseif (version_compare($library['version'], '2.0.17', '>=')) {
- // Библиотека установлена и ее версия является актуальной.
- $requirements['jscrollpane_plugin'] = array(
- 'title' => $t('jScrollPane plugin'),
- 'severity' => REQUIREMENT_OK,
- 'value' => $library['version'],
- );
- }
- else {
- // Библиотека установлена, однако требует обновления версии.
- $requirements['jscrollpane_plugin'] = array(
- 'title' => $t('jScrollPane plugin'),
- 'value' => $t('At least @a', array('@a' => '2.0.17')),
- 'severity' => REQUIREMENT_ERROR,
- 'description' =>
- $t('You need to download a later version of the !jscrollpane and replace the old version
- located in the %path directory on your server.',
- array(
- '!jscrollpane' => l($t('jScrollPane plugin'), $library['download url']),
- '%path' => $library['library path']
- )
- ),
- );
- }
- }
-
- return $requirements;
- }
В качестве наглядного примера интеграции с Libraries API рекомендую посмотреть модуль Colorbox – он собственно и мне служил источником получения знаний.
В общем, теперь вы знаете, как необходимо обращаться со сторонними библиотеками в Drupal – как их подключать и куда складировать. Надеюсь, благодаря этому посту, ваш код станет еще чище!
Комментарии
чем это лучше обычного hook_library()?
библиотеку можно также подключить через #attached
$form['myelement']['#attached']['libraries_load'][] = array('myAwesomeLibrary');
Добавить комментарий