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

В 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, определенную в глобальной конфигурации Assets. Опциональный параметр здесь 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 контролирует, должен ли актив отображаться как ссылка на внешнюю таблицу стилей или его содержимое должно быть встроено во встроенный тег стиля.

addLink($asset, [options])⚓︎

Этот метод добавит активы в список ресурсов 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.

Параметры⚓︎

Where appropriate, you can pass in an array of asset options. The core options are:

Для 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([group, [options], include_link = true)⚓︎

Визуализирует 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`

link(group, [options])⚓︎

Выдает ссылки на активы, которые были добавлены в группу менеджера активов (по умолчанию 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)