Грамотное взаимодействие со сторонними библиотеками в 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');

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

  .d88888b.          d8888  888888b.    8888888b.  
d88P" "Y88b d88888 888 "88b 888 "Y88b
888 888 d88P888 888 .88P 888 888
888 888 d88P 888 8888888K. 888 888
888 888 d88P 888 888 "Y88b 888 888
888 Y8b 888 d88P 888 888 888 888 888
Y88b.Y8b88P d8888888888 888 d88P 888 .d88P
"Y888888" d88P 888 8888888P" 8888888P"
Y8b

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