Грамотное взаимодействие со сторонними библиотеками в Drupal через Libraries API

Работа с библиотеками в Drupal через Libraries API

Здорово, посоны! Сегодня поделюсь информацией, как ровные разработчики подключают сторонние библиотеки к Drupal 7. Дело в том, что сообщество Drupal не приветствует включение сторонних библиотек, классов в состав отдельного модуля. Решать эту проблему мы будем через Libraries API.

Для начала работы нам потребуется установить модуль Libraries API, который является гибкой оберткой для работы с внешними библиотеками и предоставляет набор хуков и вспомогательных функций. Преимущества использования Libraries API:

  • отдельная библиотека может использоваться несколькими модулями;
  • контроль версий подключаемых библиотек;
  • взаимодействие с CSS, JS и PHP файлами;
  • унифицированная система взаимодействия с библиотеками, понятная всем разработчикам.

Libraries API требует обычного включения и создания папки libraries в sites. Теперь на примере подключения библиотеки jScrollPane я постараюсь показать, как использовать возможности модуля. Libraries API предоставляет новый хук hook_libraries_info, являющийся обязательным при описании новой библиотеки:

  1. /**
  2.  * Implements hook_libraries_info().
  3.  */
  4. function MODULE_libraries_info() {
  5. // В качестве ключа массива выбираем произвольное удобное название.
  6. $libraries['jscrollpane'] = array(
  7. // Человекопонятное название библиотеки.
  8. 'name' => 'jScrollPane plugin',
  9. // Ссылка на официальный ресурс библиотеки.
  10. 'vendor url' => 'http://jscrollpane.kelvinluck.com/',
  11. // Ссылка на страницу скачивания библиотеки.
  12. 'download url' => 'http://jscrollpane.kelvinluck.com/#download',
  13. // Информация для определения версии библиотеки.
  14. 'version arguments' => array(
  15. // Имя файла для парсинга, содержащего информацию о версии.
  16. 'file' => 'jquery.jscrollpane.min.js',
  17. // Регулярное выражение для определения версии.
  18. 'pattern' => '@(?i:jScrollPane) - v([0-9\.a-z]+)@',
  19. // Количество строк файла для парсинга (опционально).
  20. 'lines' => 5,
  21. ),
  22. // Список файлов загружаемых при подключении библиотеки. Доступные ключи: js, css, php.
  23. 'files' => array(
  24. 'js' => array(
  25. 'jquery.jscrollpane.min.js',
  26. ),
  27. 'css' => array(
  28. 'jquery.jscrollpane.css'
  29. ),
  30. ),
  31. );
  32.  
  33. return $libraries;
  34. }

Собственно, я привел пример минимально необходимого описания массива $libraries['jscrollpane'] для подключения. Хук hook_libraries_info обладает более гибкими настройками, с которыми, при желании, вы можете ознакомиться в официальной документации. Теперь, согласно описанию библиотеки jScrollPane, необходимо поместить файлы jquery.jscrollpane.min.js и jquery.jscrollpane.css в корень папки sites/libraries/jscrollpane.

Подключение и использование библиотек

Теперь, когда файлы библиотеки лежат в нужном месте и имплементирован хук, вы можете смело использовать библиотеку:

  1. libraries_load('jscrollpane');

Для более гибкого взаимодействия можно сделать и так:

  1. // Пытаемся загрузить библиотеку и проверяем ее на работоспособность.
  2. if (($library = libraries_load('jscrollpane')) && !empty($library['loaded'])) {
  3. // Рабочий код.
  4. }

Если необходимо просто убедится в наличии библиотеки:

  1. if (($library = libraries_detect($name)) && !empty($library['installed'])) {
  2. // Библиотека установлена.
  3. }
  4. else {
  5. // Ошибка. Библиотека не найдена :(
  6. // Следующий код вернет короткий статус проблемы. Например, 'not found'.
  7. $error = $library['error'];
  8. // Этот код вернет более детализированное описание проблемы.
  9. $error_message = $library['error message'];
  10. }

Контроль статуса и версии библиотек

В качестве бонуса к этому посту расскажу, как выводить информацию о библиотеке на странице статуса Drupal admin/reports/status. Для этого придется добавить в ваш .install-файл имплементацию хука hook_requirements.

  1. /**
  2.  * Implements hook_requirements().
  3.  */
  4. function MODULE_requirements($phase) {
  5. $requirements = array();
  6.  
  7. if ($phase == 'runtime') {
  8. $t = get_t();
  9. $library = libraries_detect('jscrollpane');
  10.  
  11. if (empty($library['installed'])) {
  12. // Сообщение о том, что библиотека не установлена
  13. $requirements['jscrollpane_plugin'] = array(
  14. 'title' => $t('jScrollPane plugin'),
  15. 'value' => $t('At least @a', array('@a' => '2.0.17')),
  16. 'severity' => REQUIREMENT_ERROR,
  17. 'description' =>
  18. $t('You need to download the !jscrollpane, extract @js_file and @css_file files from the archive and
  19. place them to the root of "jscrollpane" directory in the %path directory on your server.',
  20. array(
  21. '!jscrollpane' => l($t('jScrollPane plugin'), $library['download url']),
  22. '%path' => 'sites/all/libraries',
  23. '@js_file' => 'jquery.jscrollpane.min.js',
  24. '@css_file' => 'jquery.jscrollpane.css',
  25. )
  26. ),
  27. );
  28. }
  29. elseif (version_compare($library['version'], '2.0.17', '>=')) {
  30. // Библиотека установлена и ее версия является актуальной.
  31. $requirements['jscrollpane_plugin'] = array(
  32. 'title' => $t('jScrollPane plugin'),
  33. 'severity' => REQUIREMENT_OK,
  34. 'value' => $library['version'],
  35. );
  36. }
  37. else {
  38. // Библиотека установлена, однако требует обновления версии.
  39. $requirements['jscrollpane_plugin'] = array(
  40. 'title' => $t('jScrollPane plugin'),
  41. 'value' => $t('At least @a', array('@a' => '2.0.17')),
  42. 'severity' => REQUIREMENT_ERROR,
  43. 'description' =>
  44. $t('You need to download a later version of the !jscrollpane and replace the old version
  45. located in the %path directory on your server.',
  46. array(
  47. '!jscrollpane' => l($t('jScrollPane plugin'), $library['download url']),
  48. '%path' => $library['library path']
  49. )
  50. ),
  51. );
  52. }
  53. }
  54.  
  55. return $requirements;
  56. }

В качестве наглядного примера интеграции с Libraries API рекомендую посмотреть модуль Colorbox – он собственно и мне служил источником получения знаний.

В общем, теперь вы знаете, как необходимо обращаться со сторонними библиотеками в Drupal – как их подключать и куда складировать. Надеюсь, благодаря этому посту, ваш код станет еще чище!

Комментарии

Аватар пользователя xandeadx
xandeadx

чем это лучше обычного hook_library()?

Аватар пользователя angarsky
angarsky
Libraries API - более гибкая обертка. Например, через hook_library() PHP либу не подключишь. Ну и набор дополнительных функций для упрощения работы. Особо глубоко не копал, если честно, но с библиотеками мне так понравилось работать.
Аватар пользователя drupby
drupby

библиотеку можно также подключить через #attached

$form['myelement']['#attached']['libraries_load'][] = array('myAwesomeLibrary');

Добавить комментарий

 8888888888   .d8888b.                      
888 d88P Y88b
888 888
8888888 .d88P 88888888 888 888
888 .od888P" d88P `Y8bd8P'
888 d88P" d88P X88K
888 888" d88P .d8""8b.
888 888888888 88888888 888 888


Зарегистрируйтесь для добавления материалов без проверки.