Перейти к содержанию

Менеджер активов⚓︎

В Grav 1.6 менеджер активов был полностью переписан, чтобы обеспечить более гибкий механизм для управления CSS и JavaScript ресурсами в темах. Основная цель диспетчера ресурсов является упрощение процесса добавления ресурсов из тем и плагинов, обеспечивая расширенные возможности, такие как приоритет, а также предоставление конвейера активов, который может быть использован для ресурсов minify, compress и inline, чтобы уменьшить количество запросов браузера, а также общий размер активов.

Он гораздо более гибкий и надежный, чем раньше. Кроме того, это значительно чище и легче следовать, если вы начнете копаться в коде. Менеджер ресурсов доступен во всем Grav и может быть доступен в хуках событий плагинов, а также непосредственно в темах с помощью вызовов Twig.

Техническая информация

Основной класс Assets был значительно упрощен и сокращен. Большая часть логики была разбита на 3 трейта. testing trait, которая содержит функции, в основном используемые в нашем тестовом наборе, utils trait, которая содержит методы, которые разделяются между обычными типами ресурсов (js, inline_js, css, inline_css) и конвейером активов, который может минимизировать и сжимать, и, наконец, legacy trait, которая содержит методы, которые являются ярлыками или обходными путями, и которые, как правило, не должны использоваться в дальнейшем.

Менеджер ресурсов полностью обратно совместим с синтаксисом, используемым в версиях до Grav 1.6, однако в приведенной ниже документации будет описан новый предпочтительный синтаксис.

Конфигурация⚓︎

Менеджер ресурсов Grav имеет простой набор опций настройки. Значения по умолчанию находятся в системном файле system.yaml, но вы можете переопределить любые или все из них в вашем файле user/config/system.yaml:

assets:                                        # Конфигурация менеджера ресурсов (JS, CSS)
  css_pipeline: false                          # Конвейер CSS - это объединение нескольких ресурсов CSS в один файл.
  css_pipeline_include_externals: true         # Включить внешние URL-адреса в конвейер по умолчанию
  css_pipeline_before_excludes: true           # Отправьте конвейер до любых исключенных файлов
  css_minify: true                             # Минимизировать CSS во время конвейеризации
  css_minify_windows: false                    # Сократите переопределить для платформ Windows. False по умолчанию из-за ThreadStackSize
  css_rewrite: true                            # Перепишите все относительные URL-адреса CSS во время конвейеризации
  js_pipeline: false                           # Конвейер JS - это объединение нескольких ресурсов JS в один файл.
  js_pipeline_include_externals: true          # По умолчанию включать внешние URL-адреса в конвейер
  js_pipeline_before_excludes: true            # Визуализировать конвейер перед исключенными файлами
  js_module_pipeline: false                    # Конвейер JS-модулей - это объединение нескольких ресурсов JS-модулей в один файл
  js_module_pipeline_include_externals: true   # Включение внешних URL-адресов в конвейер по умолчанию
  js_module_pipeline_before_excludes: true     # Рендеринг конвейера перед любыми исключенными файлами
  js_minify: true                              # Минимизировать JS во время конвейеризации
  enable_asset_timestamp: false                # Включить временные метки активов
  collections:
    jquery: system://assets/jquery/jquery-3.x.min.js

Структура⚓︎

Существует несколько уровней управления позиционированием, как показано на схеме ниже. В порядке охвата они:

  • Group - позволяет группировать ресурсы, такие как head (по умолчанию) иbottom
  • Position - before, pipeline(default) и after. По сути, это позволяет вам указать, где в группе должен быть загружен актив.
  • Priority - Это управляет приоритетом*, где большие целые числа (например, 100) будут выводиться перед более низкими целыми числами. 10 - это значение по умолчанию.
CSS
┌───────────────┐
│ Группа (head) │
│┌─────────────┐│        ┌────────────────┐
││ Позиция     ││        │ приоритет 100  │─────┐     ┌────────────────┐
││┌───────────┐││        ├────────────────┤     ├────▶│       CSS      │
│││           │││        │ приоритет 99   │─────┤     └────────────────┘
│││ before    │├┼──┬────▶├────────────────┤     │
│││           │││  │     │ приоритет 1    │─────┤     ┌────────────────┐
││├───────────┤││  │     ├────────────────┤     ├────▶│ внутренний CSS │
│││           │││  │     │ приоритет 0    │─────┘     └────────────────┘
│││ pipeline  │├┼──┤     └────────────────┘
│││           │││  │
││├───────────┤││  │
│││           │││  │
│││ after     │├┼──┘
│││           │││
││└───────────┘││
│└─────────────┘│
└───────────────┘

JS
┌───────────────┐
│ Группа (head) │
│┌─────────────┐│        ┌────────────────┐
││ Позиция     ││        │ приоритет 100  │─────┐     ┌────────────────┐
││┌───────────┐││        ├────────────────┤     ├────▶│        JS      │
│││           │││        │ приоритет 99   │─────┤     └────────────────┘
│││ before    │├┼──┬────▶├────────────────┤     │
│││           │││  │     │ приоритет 1    │─────┤     ┌────────────────┐
││├───────────┤││  │     ├────────────────┤     ├────▶│  внутренний JS │
│││           │││  │     │ приоритет 0    │─────┘     └────────────────┘
│││ pipeline  │├┼──┤     └────────────────┘
│││           │││  │
││├───────────┤││  │
│││           │││  │
│││ after     │├┼──┘
│││           │││
││└───────────┘││
│└─────────────┘│
└───────────────┘

JS-модуль
┌───────────────┐
│ Группа (head) │
│┌─────────────┐│        ┌────────────────┐
││ Позиция     ││        │ приоритет 100  │─────┐     ┌───────────────────────┐
││┌───────────┐││        ├────────────────┤     ├────▶│        JS-модуль      │
│││           │││        │ приоритет 99   │─────┤     └───────────────────────┘
│││ before    │├┼──┬────▶├────────────────┤     │
│││           │││  │     │ приоритет 1    │─────┤     ┌───────────────────────┐
││├───────────┤││  │     ├────────────────┤     ├────▶│  внутренний JS-модуль │
│││           │││  │     │ приоритет 0    │─────┘     └───────────────────────┘
│││ pipeline  │├┼──┤     └────────────────┘
│││           │││  │
││├───────────┤││  │
│││           │││  │
│││ after     │├┼──┘
│││           │││
││└───────────┘││
│└─────────────┘│
└───────────────┘

По умолчанию CSS, JS и JS-модуль по умолчанию отображаются в позиции конвейера при выводе. В то время как InlineCSS, InlineJS и Inline JS Module по умолчанию находятся в позиции after. Однако это можно настроить, и вы можете установить любой ресурс в любое положение.

Ресурсы в темах⚓︎

Обзор⚓︎

Как правило, вы добавляете ресурсы CSS один за другим с помощью вызовов assets.addCss() или assets.addInlineCss(), а затем визуализируете эти ресурсы через assets.css(). Параметры, управляющие приоритетом, конвейерной обработкой или встраиванием, могут быть указаны для каждого ресурса при его добавлении или во время рендеринга для группы ресурсов.

Ресурсы JS обрабатываются аналогично с вызовами assets.addJs() и assets.addInlineJs(). Существует также общий метод assets.add(), который пытается угадать тип добавляемого актива, но рекомендуется использовать более конкретные вызовы методов.

Начиная с версии 1.7.27, менеджер ресурсов Grav также поддерживает JS-модули. Эти ресурсы работают точно так же, как и ресурсы JS, но их тип - type="module", и они обрабатываются с помощью вызовов assets.addJsModule() и assets.addInlineJsModule(). Общий метод assets.add() будет использоваться для JS-модуля, только если обнаруженное расширение .mjs. В противном случае любой файл .js будет рассматриваться как обычный JS.

Чтобы узнать больше о модулях JS, воспользуйтесь этими ссылками

Менеджер ресурсов также поддерживает:

  • добавление ресурсов в названные группы для отображения таких групп в разных местах и​/или с разными наборами параметров,
  • настройка именованных коллекций активов, которые могут быть добавлены за один вызов assets.add*().

Пример⚓︎

Пример того, как вы можете добавить CSS-файлы в свою тему, можно найти в теме по умолчанию quark, которая поставляется в комплекте с Grav. Если вы взглянете на templates/partials/base.html.twig, вы увидите нечто похожее:

<!DOCTYPE html>
<html>
    <head>
    ...

    {% block stylesheets %}
        {% do assets.addCss('theme://css-compiled/spectre.css') %}
        {% do assets.addCss('theme://css-compiled/theme.css') %}
        {% do assets.addCss('theme://css/custom.css') %}
        {% do assets.addCss('theme://css/line-awesome.min.css') %}
    {% endblock %}

    {% block javascripts %}
        {% do assets.addJs('jquery', 101) %}
        {% do assets.addJs('theme://js/jquery.treemenu.js', { group: 'bottom' }) %}
        {% do assets.addJs('theme://js/site.js', { group: 'bottom' }) %}
        {% do assets.addJsModule('plugin://my_plugin/app/main.js', { group: 'bottom' }) %}
    {% endblock %}

    {% block assets deferred %}
        {{ assets.css()|raw }}
        {{ assets.js()|raw }}
    {% endblock %}
    </head>

    <body>
    ...

    {% block bottom %}
        {{ assets.js('bottom')|raw }}
    {% endblock %}
    </body>
</html>

Тег twig block stylesheets просто определяет область, которую можно заменить или добавить в шаблоны, расширяющие ее. Внутри блока вы увидите несколько вызовов do assets.addCss().

Тег {% do %} на самом деле встроен в Twig, и это позволяет вам манипулировать переменными без генерации вывода.

Метод addCss() добавляет CSS-ресурсы в менеджер ресурсов. Если вы зададите второй числовой параметр, то он установит приоритет таблицы стилей. Если вы не укажете приоритет, то приоритет добавления ресурсов будет диктовать порядок их отображения. Вы заметите использование PHP stream wrapper theme://, чтобы обеспечить простой способ для Grav определить относительный путь текущей темы.

Коллекция assets.addJs('jquery', 101) будет включать коллекцию jquery, определенную в глобальной конфигурации ресурсов. Опциональный параметр здесь 101 устанавливает достаточно высокий приоритет, чтобы обеспечить его рендеринг в первую очередь. Приоритет по умолчанию, когда он не предоставляется, равен значению 10. Более гибким способом написания было бы assets.addJs('jquery', {priority: 101}). Это позволяет добавлять другие параметры наряду с приоритетом.

Вызов assets.css()|raw делает CSS-ресурсы HTML-тегами. Так как в этом методе параметр не задан, то по умолчанию группа имеет значение head. Обратите внимание, как это обернуто в бло assets deferred. Это новая функция в Grav 1.6, которая позволяет вам добавлять средства из других Twig шаблонов, которые включены дальше по странице (или в любом другом месте на самом деле), и всё же убедиться, что они могут отрисовывать в этом блоке head, если это необходимо.

Блок bottom в самом конце вывода вашей темы отображает JavaScript, входящий в группу bottom.

Добавление активов⚓︎

add(asset, [options])⚓︎

Метод добавления делает всё возможное, чтобы соответствовать активу, основанному на расширении файла. Это удобный метод, лучше вызвать один из прямых методов для CSS, Link, JS или JS-модуля. Подробности см. в разделе «Прямые методы».

Массив параметров - предпочтительный подход для передачи нескольких параметров. Однако, как и в предыдущем примере с jquery, вы можете использовать ярлык и передать целое число для второго аргумента в метод, если всё, что вы хотите установить, это приоритет.

addCss(asset, [options])⚓︎

Этот метод добавит ресурсы в список ресурсов CSS. По умолчанию приоритет 10, если он не указан. Более высокое число означает, что оно будет отображаться перед ресурсами с более низким приоритетом. Опция pipeline контролирует, должен ли этот ресурс быть включен в конвейер объединения/минимизации. Если не конвейерный, опция loading контролирует, должен ли ресурс отображаться как ссылка на внешнюю таблицу стилей или его содержимое должно быть встроено во встроенный тег стиля.

Этот метод добавит ресурсы в список ресурсов Link, в виде тега <link>. Он полезен для добавления тегов ссылок в head из любого места вашего сайта, не являющегося файлами CSS. Приоритет по умолчанию равен 10, если он не указан. Большее число означает, что он будет отображаться перед ресурсами с более низким приоритетом.

В отличие от других методов добавления активов, link() не поддерживает конвейеризацию и не поддерживает inline.

addInlineCss(css, [options])⚓︎

Позволяет добавить строку CSS внутри встроенного тега стиля. Полезно для инициализации или чего-нибудь динамического. Чтобы встроить содержимое обычного файла ресурсов, см. параметр { 'loading': 'inline' } методов addCss() и css().

addJs(asset, [options])⚓︎

Этот метод добавит ресурсы в список ресурсов JavaScript. По умолчанию приоритет 10, если он не указан. Более высокое число означает, что оно будет отображаться перед ресурсами с более низким приоритетом. Опция pipeline контролирует, должен ли этот ресурс быть включен в конвейер объединения/минимизации. Если не конвейерно, опция loading определяет, должен ли ресурс отображаться как ссылка на внешний файл скрипта или его содержимое должно быть встроено во внутренний тег скрипта.

addInlineJs(javascript, [options])⚓︎

Позволяет добавить строку JavaScript во встроенный тег скрипта. Полезно для инициализации или чего-нибудь динамического. Чтобы встроить содержимое обычного файла ресурсов, см. параметр { 'loading': 'inline' } методов addJs() и js().

addJsModule(asset, [options])⚓︎

Этот метод добавит ресурсы в список ресурсов модулей JavaScript. Приоритет по умолчанию равен 10, если он не указан. Большее число означает, что он будет отображаться перед ресурсами с более низким приоритетом. Параметр pipeline контролирует, должен ли этот ресурс быть включен в конвейер для объединения/минификации. Если он не конвейерный, параметр loading определяет, должен ли ресурс отображаться как ссылка на внешний файл скрипта или его содержимое должно быть вставлено во внутренний тег скрипта.

addInlineJsModule(javascript, [options])⚓︎

Позволяет добавить строку JavaScript внутри тега скрипта встроенного модуля. Чтобы вставить содержимое обычного файла активов, см. опцию { 'loading': 'inline' } методов addJsModule() и js().

registerCollection(name, array)⚓︎

Позволяет вам зарегистрировать массив ресурсов CSS и JavaScript с именем для последующего использования методом add(). Особенно полезно, если вы хотите зарегистрировать коллекцию, которая может использоваться несколькими темами или плагинами, такими как jQuery или Bootstrap.

Параметры⚓︎

При необходимости вместо этого можно передать массив параметров ресурса. Основные параметры:

Для CSS⚓︎

  • priority: Целочисленное значение (значение по умолчанию - 10)

  • position: pipeline по умолчанию, но также может быть before или after.

  • loading: inline если этот ресурс должен выводиться скорее встроенным (по умолчанию: ссылка на таблицу стилей). Следует использовать вместе с position: before или position: after, так как это не повлияет на position: pipeline (по умолчанию).

  • group: строка для указания уникального имени группы для ресурса (по умолчанию head)

Для JS и JS-модулей⚓︎

  • priority: Целочисленное значение (значение по умолчанию - 10)

  • position: pipeline по умолчанию, но также может быть before или after.

  • loading: поддерживает любой тип загрузки, например async, defer, async defer или inline. Следует использовать вместе с position: before или position: after, так как это не повлияет на position: pipeline (по умолчанию).

  • group: строка для указания уникального имени группы для ресурса (по умолчанию head)

Другие атрибуты⚓︎

Вы также можете передать все, что угодно, в массив параметров, и если они не являются этими стандартными типами, они будут просто отображаться как атрибуты, такие как {id: 'custom-id'} будут отображаться как id="custom-id" в теге HTML. Это также можно использовать для включения структурированных данных, таких как json-ld, через addInlineJs(), используя {type: 'application/ld+json'}.

Примеры⚓︎

Например:

{% do assets.addCss('page://01.blog/assets-test/example.css?foo=bar', { priority: 20, loading: 'inline', position: 'before'}) %}

Будет отрендерено как:

<style>
h1.blinking {
    text-decoration: underline;
}
</style>
<link.....

Другой пример:

{% do assets.addJs('page://01.blog/assets-test/example.js', {loading: 'async', id: 'custom-css'}) %}

Будет отрендерено как:

<script src="/grav/user/pages/01.blog/assets-test/example.js" async id="custom-css"></script>

Пример вставки тега link:

{% do assets.addLink('theme://images/favicon.png', { rel: 'icon', type: 'image/png' }) %}
{% do assets.addLink('plugin://grav-plugin/build/js/vendor.js', { rel: 'modulepreload' }) %}

Будет отрендерено как:

<link rel="icon" type="image/png" href="/user/themes/quark/images/favicon.png">
<link href="/user/plugins/grav-plugin/build/js/vendor.js" rel="modulepreload">

Рендеринг активов⚓︎

Следующее позволяет отображать текущее состояние ресурсов CSS и JavaScript.

Визуализирует CSS-ресурсы, добавленные в группу менеджера ресурсов (по умолчанию head). Варианты таковы

  • loading: inline если все ресурсы в этой группе должны быть встроены (по умолчанию: отображать каждый ресурс в соответствии с его опцией position)

  • link attributes, см. ниже (по умолчанию: {'type': 'text/css', 'rel': 'stylesheet'}). Эффективен, только если inline не используется в качестве параметра рендеринга этой группы

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

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

Если конвейерная обработка включена в конфигурации, ресурсы в позиции конвейера объединяются в том порядке, в котором были добавлены ресурсы, а затем обрабатываются в соответствии с конфигурацией конвейера.

Каждый ресурс отображается либо как ссылка таблицы стилей, либо как встроенный, в зависимости от параметра loading ресурса и от того, используется ли для рендеринга этой группы параметр {'loading':inline'}. CSS, добавленный с помощьюaddInlineCss(), по умолчанию будет отображаться в позицииafter, но вы можете настроить его для рендеринга перед конвейерным выводом с помощьюposition: before`

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

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

js(group, [options], include_js_module = true)⚓︎

Renders JavaScript assets that have been added to an Asset Manager's group (default is head). Options are

  • loading: inline если все ресурсы в этой группе должны быть встроены (по умолчанию: отображать каждый ресурс в соответствии с его опцией position)

  • script attributes, см. ниже (по умолчанию: {'type': 'text/javascript'}). Эффективен, только если inline не используется в качестве параметра рендеринга этой группы

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

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

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

Каждый ресурс отображается либо как ссылка таблицы стилей, либо как встроенный, в зависимости от параметра loading ресурса и от того, используется ли для рендеринга этой группы параметр {'loading':inline'}. Обратите внимание, что единственный способ встроить конвейер JS — это использовать встроенную загрузку в качестве опции методаjs(). JS, добавленный с помощьюaddInlineJs(), по умолчанию будет отображаться в позицииafter, но вы можете настроить его для рендеринга перед конвейерным выводом с помощьюposition: before`

jsModule(group, [options])⚓︎

Работает точно так же, как рендерер js(), но для модулей JavaScript. Атрибутом типа скрипта по умолчанию является type="module", даже при рендеринге inline.

all(group, [options])⚓︎

Выравнивает все вышеперечисленные ресурсы в порядке их следования: css(), link(), js(), jsModule().

Это рекомендуемый способ включения отложенных ресурсов в ваш основной файл twig (обычно base.html.twig).

{% block assets deferred %}
  {{ assets.all()|raw }}
{% endblock %}

Именованные ресурсы и коллекции⚓︎

Теперь у Grav есть мощная функция named assets, которая позволяет вам регистрировать коллекцию CSS и JavaScript ресурсов по имени. Затем вы можете просто добавить эти ресурсы в менеджер ресурсов через имя, под которым вы зарегистрировали коллекцию. Grav поставляется с предварительно настроенным jQuery, но имеет возможность определять собственные коллекции в файле system.yaml, которые будут использоваться любой темой или плагином:

assets:
  collections:
    jquery: system://assets/jquery/jquery-2.1.3.min.js
    bootstrap:
        - https://maxcdn.bootstrapcdn.com/bootstrap/3.3.4/css/bootstrap.min.css
        - https://maxcdn.bootstrapcdn.com/bootstrap/3.3.4/css/bootstrap-theme.min.css
        - https://maxcdn.bootstrapcdn.com/bootstrap/3.3.4/js/bootstrap.min.js

Вы также можете использовать метод registerCollection() программным способом.

$assets = $this->grav['assets'];
$bootstrapper_bits = [https://maxcdn.bootstrapcdn.com/bootstrap/3.3.4/css/bootstrap.min.css,
                      https://maxcdn.bootstrapcdn.com/bootstrap/3.3.4/css/bootstrap-theme.min.css,
                      https://maxcdn.bootstrapcdn.com/bootstrap/3.3.4/js/bootstrap.min.js];
$assets->registerCollection('bootstrap', $bootstrap_bits);
$assets->add('bootstrap', 100);

Пример этого действия можно найти в плагине bootstrapper.

Коллекции с атрибутами⚓︎

Иногда может потребоваться указать пользовательские и/или другие атрибуты для определённых элементов коллекции, например, если вы загружаете ресурсы с удаленного CDN и хотите включить проверку целостности (SRI). Это возможно, если рассматривать значение именованного ресурса как массив, где ключом является местоположение актива, а значением — список дополнительных атрибутов. Например:

assets:
  collections:
    jquery_and_ui:
        https://cdnjs.cloudflare.com/ajax/libs/jquery/3.6.0/jquery.min.js:
            integrity: 'sha512-894YE6QWD5I59HgZOGReFYm4dnWc1Qt5NtvYSaNcOP+u1T9qYdvdihz0PPSiiqn/+/3e7Jo4EaG7TubfWGUrMQ=='
            group: 'bottom'
        https://cdnjs.cloudflare.com/ajax/libs/jqueryui/1.12.1/jquery-ui.min.js:
            integrity: 'sha512-uto9mlQzrs59VwILcLiRYeLKPPbS/bT71da/OEBYEwcdNUk8jYIy+D176RYoop1Da+f9mvkYrmj5MCLZWEtQuA=='
            group: 'bottom'

Затем, после того как вы добавите JS в свой twig через {% do assets.addJs('jquery_and_ui', { defer: true }) %}, ресурсы будут загружаться как:

<script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/3.6.0/jquery.min.js" defer="1" integrity="sha512-894YE6QWD5I59HgZOGReFYm4dnWc1Qt5NtvYSaNcOP+u1T9qYdvdihz0PPSiiqn/+/3e7Jo4EaG7TubfWGUrMQ=="></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/jqueryui/1.12.1/jquery-ui.min.js" defer="1" integrity="sha512-uto9mlQzrs59VwILcLiRYeLKPPbS/bT71da/OEBYEwcdNUk8jYIy+D176RYoop1Da+f9mvkYrmj5MCLZWEtQuA=="></script>

Обратите внимание, что атрибут defer был определен на уровне twig и применен ко всем ресурсам в коллекции. Это связано с тем, что Grav объединит атрибуты как из twig, так и из определения yaml, отдавая приоритет тем, которые указаны в определении yaml.

Если бы ресурс jquery-ui.min.js также включал атрибут defer: null, тогда этот атрибут имел бы приоритет над defer: 1.

Сгруппированные активы⚓︎

Менеджер ресурсов позволяет вам передавать необязательную группу (group) как часть массива параметров при добавлении активов. Хотя это не очень важно для CSS, это особенно полезно для JavaScript, где вам может потребоваться указать некоторые файлы JS или встроенный JS в заголовке, а некоторые - в нижней части страницы.

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

{% do assets.addJs('theme://js/example.js', {'priority':102, 'group':'bottom'}) %}

Затем, чтобы эти ресурсы в нижней группе отображались, вы должны добавить в свою тему следующее:

{{ assets.js('bottom') }}

Если для ресурса не определена группа, то по умолчанию используется группа head. Если ни одна группа не настроена для рендеринга, то будет отрисована группа head. Это гарантирует, что новая функциональность на 100% обратно совместима с существующими темами.

То же самое относится и к CSS файлам:

{% do assets.addCss('theme://css/ie8.css', {'group':'ie'}) %}

и рендеринг:

{{ assets.css('ie') }}

Изменение атрибутов визуализируемых ресурсов CSS/JS⚓︎

CSS по умолчанию добавлен с использованием атрибута rel="stylesheet" и type="text/css", в то время как JS имеет type="text/javascript".

Чтобы изменить настройки по умолчанию или добавить новые атрибуты, необходимо создать новую группу ресурсов и сказать Grav, чтобы она отобразила его с этим атрибутом.

Пример редактирования атрибута rel на группе активов:

{% do assets.addCSS('theme://whatever.css', {'group':'my-alternate-group'}) %}
...
{{ assets.css('my-alternate-group', {'rel': 'alternate'}) }}

Встраивание активов⚓︎

Встраивание позволяет размещать критический код CSS (и JS) непосредственно в документе HTML, что позволяет браузеру немедленно отображать страницу, не дожидаясь загрузки внешней таблицы стилей или скрипта. Это может заметно улучшить производительность сайта для пользователей, особенно в мобильных сетях. Подробности можно найти в этой статье об оптимизации доставки CSS.

Однако прямая вставка кода CSS или JavaScript в шаблон страницы не всегда возможна, например, когда используется Sass-совместимый CSS. Хранение ресурсов CSS и JS в отдельных файлах также упрощает обслуживание. Использование встроенных возможностей Asset Manager позволяет оптимизировать скорость без изменения способа хранения ваших активов. Могут быть встроены даже целые конвейеры.

Чтобы встроить содержимое файла ресурса, используйте опцию {'loading': 'inline'} с addCss() или addJs(). Вы также можете встроить все ресурсы при рендеринге группы с помощью js() или css(), которые предоставляют тот же параметр.

Пример использования system.yaml для определения коллекций ресурсов, названных в соответствии с требованиями к загрузке ресурсов, при этом app.css является файлом CSS, сгенерированным Sass:

assets:
  collections:
    css-inline:
      - 'http://fonts.googleapis.com/css?family=Ubuntu:400|Open+Sans:400,400i,700'
      - 'theme://css-compiled/app.css'
    js-inline:
      - 'https://use.fontawesome.com/<embedcode>.js'
    js-async:
      - 'theme://foundation/dist/assets/js/app.js'
      - 'theme://js/header-display.js'

Шаблон вставляет каждую коллекцию в соответствующую группу, а именно head и head-link для CSS, head и head-async для JS. Группа по умолчанию head используется для последовательной загрузки в каждом случае:

{% block stylesheets %}
    {% do assets.addCss('css-inline') %}
    {% do assets.addCss('css-link', {'group': 'head-link'}) %}
{% endblock %}
{{ assets.css('head-link') }}
{{ assets.css('head', {'loading': 'inline'}) }}
{% block javascripts %}
    {% do assets.addJs('js-inline') %}
    {% do assets.addJs('js-async', {'group': 'head-async'}) %}
{% endblock %}
{{ assets.js('head-async', {'loading': 'async'}) }}
{{ assets.js('head', {'loading': 'inline'}) }}

Статические активы⚓︎

Иногда возникает необходимость ссылки на ресурсы без использования Менеджера активов. Для этого имеется вспомогательный метод url(). Примером может служить, если вы хотите сослаться на изображение из темы. Синтаксис для этого:

<img src="{{ url("theme://" ~ widget.image) }}" alt="{{ widget.text|e }}" />

Метод url() принимает необязательный второй параметр true или false, чтобы включить URL для включения чертежа и домена. По умолчанию предполагается, что это значение false, в результате чего получается только относительный URL. Например:

url("theme://some/extra.css", true)