Работа с CSS и JavaScript в темах Drupal 8

В этой статье мы более подробно остановимся на вопросах работы с библиотеками: управлением зависимостями, подключением сторонних библиотек, переопределением или отключением ненужных библиотек.

Создание библиотек

В восьмой версии Drupal фалы стилей и скриптов добаловаться в темы уже совершенно по-новому. Для того, чтобы добавить CSS или JavaScript вам нужно определить их в файле библиотек mytheme.libraries.yml, который должен находиться в корневой директории вашей темы.

Каждая библиотека должна иметь уникальное (в приделах темы) имя, может иметь произвольное количество загружаемых файлов, перечень зависимостей, а также дополнительную информацию нужную для библиотеки.

Давайте посмотрим на такой пример:

# Файл my_theme.libraries.yml

# Задаем имя библиотеки.
my-library-name:
  version: "1.0.x"
  css:
    # учитываем категории согласно SMACSS методологии.
    base:
      # Путь к фалу CSS.
      assets/css/base.css: {}
    theme:
      assets/css/print.css: { media: print }
  js:
    assets/js/myglobal.js {}
  dependencies:
    - core/jquery

# А здесь мы добавим шрифт от Google fonts.
lato:
  css:
    base: '//fonts.googleapis.com/css?family=Lato': { external: true }

Стоит отметить, что формат .yml используется для вех конфигурационных файлов в Drupal 8.

Имя библиотеки

Как я уже упомянул выше мы должны задать уникальное имя для нашей библиотеке в контексте темы или модуля, которые вызывают библиотеку.

Версия

Не обязательно задавать версию для библиотеки, но лучше сделать это. В дальнейшем, вам будет легче поддерживать код. Особенно важно добавлять версию для внешних библиотек, которая будет соответствовать версии источника.

CSS

Все CSS файлы библиотеки описываются внутри секции css, кроме того, их можно разделить на под-категории. Например:

css:
  # учитываем категории согласно SMACSS методологии.
  base:
    # Путь к фалу CSS.
    assets/css/base.css: {}
  theme:
    assets/css/print.css: { media: print }

В этом отрывке кода каждый файл указан в свое под-категории. Для того, чтобы детальнее познакомиться с принципами организации CSS стоить взглянуть на документацию по организации CSS Drupal. Вкратце, скажем, что Друпал использует SMACSS методологию организации файлов стилей. Все файлы условно разбиваться на под-категории: base, layout, component, state, и theme. Примечательно то, что независимо от библиотек, файлы стилей подключаются на странице именно в порядке следования этих под-категорий. То есть, файл из секции base одной библиотеки будет загружаться совместно с файлом из этой секции другой библиотеки.

Дополнительные свойства

Дополнительные свойства для CSS файлов могут быть заданы с помощью фигурных скобок после пути к файлу:

theme:
  assets/css/print.css: { media: print }

Здесь мы передаем кастомные медиа-свойства для файла, в данном случае это print, но мы можем задать и другие медиа-свойства, например установить значения минимальной или максимальной ширины, к которой будут применены правила файла.

JavaScript

Файлы .js добавляются в секции js. Для них нет какой-либо дополнительной структуры, но вы можете добавить кастомные свойства в фигурных скобках после пути файла. Например, вы можете указать значение minified: true, чтобы Drupal минифицировал данный файл при агрегации. Также, перед именем файла вы можете указать регион страницы, куда будет загружен файл. По умолчанию Drupal 8 загружает все скрипты в нижнюю часть страницы, но если вам нужно поместить скрипт вверх, то можно указать header: true и скрипт будет помещен в head документа. Вот пример подключения .js файла в библиотеке:

js-header:
  header: true
  js:
    header.js: { minified: true }

js-footer:
  js:
    footer.js: { minified: true }

Зависимости

Здесь все просто. В конце определения вашей библиотеки вы можете добавить секцию, в которой укажите от каких библиотек она зависит и эта библиотека тоже будет добавлена вместе с вашей. Важно, чтобы эта библиотека существовала, и вы правильно указали бы ее имя и путь. Например:

# ... код библиотеки
# Объявляем зависимости.
dependencies:
  - core/jquery

В данном случае мы объявили зависимость от библиотеки jquery, которая была определена модулем core в его файле библиотек core.libraries.yml.

Внешние файлы

Добавить внешний файл в библиотеку очень просто: укажите полный путь к файлу, а в дополнительных свойствах обязательно скажите, что файл внешний { external: true }. Мы уже добавляли таким образом шрифт в коде в начале поста:

# ... код библиотеки
# А здесь мы добавим шрифт от Google font.
lato:
  css:
    base:
      '//fonts.googleapis.com/css?family=Lato': { external: true }

Прикрепляем библиотеки

Если вы просто перечислите ваши библиотеки в mytheme.libraries.yml, то ничего особенного не произойдет. Чтобы Drupal знал о ваших библиотеках, нужно сказать ему какие и как использовать. У вас есть три способа вызова библиотек: подключить библиотеку глобально через mytheme.info.yml, вызвать библиотеку из Twig-шаблона, а также добавить ее через препроцесс-хук. Рассмотри все три способа детальнее.

Прикрепляем библиотеку глобально

В разделе библиотек просто укажите пути и имена библиотек, которые хотите использовать всюду на сайте. Например:

libraries:
  - core/normalize
  - mythemename/my-library-name

Прикрепляем библиотеку к файлу шаблона

Лично мне эта возможность очень нравиться, она позволяет реализовать действительно компонентный подход при разработке тем Drupal 8. В Twig-шаблонах предусмотрена специальная функция attach_library(), которая будет вызывать файлы библиотеки только в том случае, если блок, который использует этот шаблон будет выведен на странице. То есть, вы значительно уменьшаете размер загружаемого кода, используете только то, что вам нужно и когда это нужно. Например:

{# В файле Twig-шаблона node--article--full.html.twig. #}

{{ attach_library('mythemename/my-library-name') }}

Файлы библиотеки буду загружены только на страницах полного вида нод типа article. Просто супер!

Добавляем библиотеку через препроцесс-хук

Для бэк-энд разработчиков, возможно, привычнее будет добавлять библиотеки через PHP. Например:

function mytheme_preprocess_maintenance_page(&$variables) {
  $variables['#attached']['library'][] = 'mytheme/cuddly-slider';
}

Вы можете использовать любые хуки и логику, главное — это добавить свою библиотеку к массиву ['library'].

Дополнительные действия с библиотеками

Поскольку все файлы стилей и .js теперь подключаться с помощью библиотек, это дает дополнительные возможности разработчикам тем для управления библиотеками на уровне темы. Есть два основных действия, которые вы можете совершать с библиотеками: расширять и переписывать, и делается это методами libraries-extend и libraries-override соотвественно.

Расширяем библиотеки

С помощью использования метода libraries-extend внутри вашего инфо-файла темы вы можете прикрепить собственную библиотеку к любой существующей библиотеке. Если библиотека, которую вы хотите расширить загружается типичным способом, без каких-либо дополнительных манипуляций, то сделать это достаточно просто. Например:

# В файле mytheme.info.yml
libraries-extend:
  # Библиотека форума темы Classy загружается только, когда используется шаблон
  # forums.html.twig
  # В это же время будут добавляться и файлы вашей библиотеки.
  classy/forums:
    - mythemename/forums

В комментариях к примеру все довольно понятно написано. Файлы вашей библиотеки будут загружать только вместе с файлами расширяемой.

Переписываем библиотеки

Метод libraries-override дает вам еще более мощные инструменты для управления библиотеками. С его помощью вы можете удалять или замещать файлы определенной библиотеки. Давайте рассмотри все более детально на примерах.

Удаляем файл

# В файле mytheme.info.yml
libraries-override:
  # Указываем имя библиотеки.
  core/jquery.ui:
    # Перечисляем CSS-файлы. Обязательно в таком порядке!
    css:
      # Категория, согласно методологии SMACSS обязательна.
      theme:
        # Путь к файлу. Внимание! Этот путь не относительно вашей темы.
        assets/vendor/jquery.ui/themes/base/theme.css: false

Обратите внимание на комментарии. При отключении CSS-файла вы должны четко придерживаться порядка, как и при его определении. Только путь к файлу библиотеки указывается так же, как он указан в файле определения библиотеки, а не относительно вашей темы или корня сайта. Приставка core/ перед названием библиотеки указывает на модуль, который инициирует данную библиотеку.

Ну и в конце примера вы видите, что мы добавляем false к пути файла. Именно это говорит Drupal, что файл должен быть исключен из библиотеки при ее использовании.

Заменяем файл

Механизм замены похож на механизм удаления, с той лишь разницей, что после пути файла мы указываем имя файла на который хотим заменить текущий. Например:

# В файле mytheme.info.yml
libraries-override:
  system/maintenance:
    css:
      theme:
        # Заменяем файл system.maintenance.css в модуле System собственным файлом.
        css/system.maintenance.css: css/maintenance.css

Здесь есть один интересный нюанс. Поскольку мы заменяем файл существующей библиотеки, то наш файл не должен быть определен в каких-либо наших библиотеках. Также при сборке страницы файл будет вставлен именно в то место, где был заменяемый файл.

Заменяем или удаляем всю библиотеку.

Вы можете заменить или удалить целую библиотеку, сделать это очень просто. Например:

# В файле mytheme.info.yml
libraries-override:
  # Заменяем библиотеку messages темы Classy свой собственной.
  classy/messages:
    mythemename/messages
  # Полностью удаляем библиотеку search results темы Classy.
  classy/search-results: false

При замене одной библиотеки на другую, их имена и содержимое не обязательно должны соответствовать.

Заключение

Как я уже говорил ранее, Drupal 8 подошел к вопросу разработки фронт-енда очень основательно и глубоко. Фактически система предлагает современные инструменты для гибкой и компонент-ориентированной разработки, которых сегодня не дает ни одна из популярных CMS с открытым исходным кодом. Наша же с вами задача — правильно и удачно использовать эти инструменты. Успехов!