Переменные темы⚓︎

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

В Twig можно вызывать методы, не принимающие параметров, просто вызывая имя метода и опуская скобки (). Если вам нужно передать параметры, вам также нужно указать их после имени метода. Вызов page.content эквивалентен вызову page.content().

Ключевые объекты⚓︎

Существует несколько ключевых объектов, которые доступны для шаблона Twig, и каждый объект имеет набор переменных и функций.

Переменная base_dir⚓︎

{{ base_dir }} возвращает каталог базового файла установки Grav.

Переменная base_url⚓︎

{{ base_url }} возвращает базовый URL сайта, независимо от значения переменной absolute_urls (опция в системной конфигурации).

Переменная base_url_relative⚓︎

{{ base_url_relative }} возвращает базовый URL-адрес сайта, без информации о хосте.

Переменная base_url_absolute⚓︎

{{ base_url_absolute}} возвращает базовый URL-адрес сайта, включая информацию о хосте.

Переменная base_url_simple⚓︎

{{ base_url_simple }} возвращает базовый URL сайта, без кода языка.

Переменная home_url⚓︎

{{ home_url }} особенно полезно использовать для обратной ссылки на домашнюю страницу вашего сайта. Это похоже на base_url, но учитывает ситуацию, когда он пуст.

Переменная html_lang⚓︎

Это вернет текущий активный язык, если он предоставлен, иначе используйте опцию site.default_lang, иначе вернитесь к en.

Переменная theme_dir⚓︎

{{ theme_dir }} возвращает папку каталога файлов текущей темы.

Переменная theme_url⚓︎

{{ theme_url }} возвращает относительный URL к текущей теме.

При связывании с такими активами, как изображения или JavaScript и CSS файлы, рекомендуется использовать функцию url() в сочетании с потоком theme://, как описано на странице Фильтры и функции Twig. Для JavaScript и CSS менеджер активов ещё проще использовать, но в некоторых случаях, например, при динамической или условной загрузке активов, она не будет работать.

Переменная html_lang⚓︎

{{ html_lang }} возвращает активный язык.

Переменная language_codes⚓︎

{{ language_codes }} возвращает список доступных языков сайта.

Объект assets⚓︎

Менеджер активов добавляет простой способ управления CSS и JavaScript на вашем сайте.

{% do assets.addCss('theme://css/foo.css') %}
{% do assets.addInlineCss('a { color: red; }') %}
{% do assets.addJs('theme://js/something.js') %}
{% do assets.addInlineJs('alert("Warming!");') %}

Подробнее о менеджере активов.

Рекомендуется использовать тег style и тег script.

Объект config⚓︎

Вы можете получить доступ к любой настройке конфигурации Grav, установленной в YAML-файлах в /user/config, через объект config. Например:

{{ config.system.pages.theme }}{# Возвращает текущую настроенную тему #}

Объект site⚓︎

Псевдоним объекта config.site. Представляет конфигурацию, установленную в файле site.yaml.

Объект system⚓︎

Псевдоним объекта config.system. Представляет конфигурацию в основном файле system.yaml.

Объект theme⚓︎

Псевдоним объекта config.theme. Представляет конфигурацию для текущей активной темы. Настройки плагина доступны через config.plugins.

Объект page⚓︎

Поскольку Grav построен с использованием структуры, определенной в папке pages/, каждая страница представлена объектом page.

Объект page, вероятно, является самым важным объектом, с которым вы будете работать, поскольку он содержит всю информацию о текущей странице, на которой вы находитесь.

Полный список методов объекта page доступен на странице API. Вот список наиболее полезных для вас методов.

summary([size])⚓︎

Возвращает усеченную или укороченную версию вашего контента. Вы можете задать опциональный параметр size, чтобы указать максимальную длину резюме, в символах. В качестве альтернативы, если размер не указан, значение можно получить через переменную summary.size в масштабе всего сайта из вашей конфигурации site.yaml.

{{ page.summary }}

или

{{ page.summary(50) }}

Третий вариант - использовать разделитель === в вашем содержании. Всё, что перед разделителем, будет использовано в качестве тизера.

content()⚓︎

Возвращает все HTML содержимое вашей страницы.

{{ page.content }}

При этом возвращаются заголовки страниц, определённые в YAML-фронтальной материи страницы. Например, страница со следующими заголовками:

title: My Page
author: Joe Bloggs

можно использовать:

Автором этой страницы является: {{ page.header.author }}

media()⚓︎

Возвращает массив, содержащий все медиа, связанные со страницей. К ним относятся изображения, видео и другие файлы. Вы можете получить доступ к медиа-методам, как описано в главе Медиа для контента. Поскольку это массив, можно использовать фильтры и функции Twig. Примечание: .svg обрабатываются как файлы, а не изображения, потому что ими нельзя управлять с помощью фильтров изображений Twig.

Получаем конкретный файл или изображение:

{% set my_pdf = page.media['myfile.pdf'] %}

Получаем первое изображение:

{% set first_image = page.media.images|first %}

Просматриваем все изображения и выводим HTML-тег для их отображения:

{% for image in page.media.images %}
   {{ image.html }}
{% endfor %}

title()⚓︎

Возвращает заголовок страницы, установленный в переменной title заголовков YAML для самой страницы.

title: My Page

Возвращает значение переменной menu в заголовках YAML страницы. Если ничего не указано, по умолчанию используется title.

title: My Page
menu: my-page

visible()⚓︎

Возвращает, видна ли страница. По умолчанию страницы с числовым значением, за которым следует точка, по умолчанию видны (01.somefolder1), тогда как страницы без (subfolder2) не считаются видимыми. Это можно изменить в заголовках страниц:

title: My Page
visible: true

routable()⚓︎

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

title: My Page
routable: true

slug()⚓︎

Возвращает прямое имя, как отображается в URL для этой страницы, например, my-blog-post.

url([include_host = false])⚓︎

Возвращает, например, URL на страницу:

{{ page.url }} {# может вернуть /my-section/my-category/my-blog-post #}

или

{{ page.url(true) }} {# может вернуть http://mysite.com/my-section/my-category/my-blog-post #}

permalink()⚓︎

Возвращает URL-адрес с информацией о хосте. Особенно полезно, когда нужна быстрая ссылка, к которой можно получить доступ из любого места.

canonical()⚓︎

Возвращает URL-адрес, который является «предпочтительной» версией или ссылкой на конкретную страницу. Это значение по умолчанию будет обычным URL-адресом, если страница не переопределила параметр заголовка страницы canonical:.

route()⚓︎

Возвращает внутреннюю маршрутизацию для страницы. Это в основном используется для внутренней маршрутизации и отправки страниц.

home()⚓︎

Возвращает true или false в зависимости от того, настроена ли эта страница как домашняя. Этот параметр находится в файле system.yaml.

root()⚓︎

Возвращает true или false в зависимости от того, является ли эта страница корневой страницей древовидной иерархии или нет.

active()⚓︎

Возвращает true или false в зависимости от того, является ли эта страница в настоящее время страницей, к которой обращается ваш браузер. Это особенно полезно при навигации, чтобы узнать, является ли текущая страница активной.

modular()⚓︎

Возвращает true или false в зависимости от того, является ли эта страница модульной.

activeChild()⚓︎

Возвращает, содержит ли этот URL-адрес URI URL-адрес активной страницы. Или, другими словами, это URL-адрес этой страницы в текущем URL-адресе. Опять же, это полезно при построении вашей навигации, и вы хотите знать, является ли страница, которую вы повторяете, родительской для активной дочерней страницы.

find(url)⚓︎

Возвращает объект страницы, указанный в URL-адресе маршрута.

{% include 'modular/author-detail.html.twig' with {'page': page.find('/authors/billy-bloggs')} %}

collection()⚓︎

Возвращает коллекцию страниц для этого контекста, как определено заголовками страниц коллекции.

{% for child in page.collection %}
    {% include 'partials/blog_item.html.twig' with {'page':child, 'truncate':true} %}
{% endfor %}

currentPosition()⚓︎

Возвращает индекс текущей страницы относительно элементов того же уровня.

isFirst()⚓︎

Возвращает true или false в зависимости от того, является ли эта страница первым из элементов того же уровня.

isLast()⚓︎

Возвращает true или false в зависимости от того, является ли эта страница последней из элементов того же уровня.

nextSibling()⚓︎

Возвращает следующую страницу из массива элементов того же уровня на основе текущей позиции.

prevSibling()⚓︎

Возвращает предыдущую страницу из массива элементов того же уровня на основе текущей позиции.

nextSibling() и prevSibling() страницы ордеров в стек-подобной структуре. Лучше всего работает в ситуации, когда первый пост в блоге имеет nextSibling null, а prevSibling - предыдущий. Если это направление сортировки сбивает вас с толку, мы предлагаем использовать page.adjacentSibling(-1) для указания на следующую страницу вместо page.nextSibling(), чтобы уменьшить путаницу, которую может вызвать терминология. Вы также можете определить константу в теме и использовать её для лучшей читабельности, например, page.adjacentSibling(NEXT_PAGE).

children()⚓︎

Возвращает массив дочерних страниц для страницы, как определено в структуре содержимого страниц.

orderBy()⚓︎

Возвращает тип сортировки для всех отсортированных дочерних элементов страницы. Значения обычно включают в себя: default, title, date и folder. Это значение обычно настраивается в заголовках страниц.

orderDir()⚓︎

Возвращает направление сортировки для любых отсортированных дочерних страниц. Значения могут быть как asc для восходящего, так и desc для нисходящего. Это значение обычно настраивается в заголовках страниц.

orderManual()⚓︎

Возвращает массив ручной сортировки страницы для любых дочерних страниц. Это значение обычно настраивается в заголовках страниц.

maxCount()⚓︎

Возвращает максимальное количество страниц для дочерних элементов, которые могут быть возвращены. Это значение обычно настраивается в заголовках страниц.

children.count()⚓︎

Возвращает количество дочерних страниц.

children.current()⚓︎

Возвращает текущий дочерний элемент. Может использоваться во время итераций над дочерними элементами.

children.next()⚓︎

Возвращает следующий элемент в массиве дочерних элементов.

children.prev()⚓︎

Возвращает предыдущий элемент в массиве дочерних элементов.

children.nth(position)⚓︎

Возвращает дочерний элемент, идентифицируемый по position, которая является целым числом от 0 до children.count() - 1 в массиве дочерних элементов.

children.sort(orderBy, orderDir)⚓︎

Переупорядочивает дочерние элементы на основе orderBy (default,title, date иfolder) и orderDir (asc или desc)

parent()⚓︎

Возвращает объект родительской страницы для этой страницы. Это очень полезно, когда вам нужно вернуться к вложенной древовидной структуре страниц.

isPage()⚓︎

Возвращает true или false в зависимости от того, есть ли у этой страницы фактический файл .md, связанный с ней, а не просто папка для маршрутизации.

isDir()⚓︎

Возвращает true или false в зависимости от того, является ли эта страница только папкой для маршрутизации.

id()⚓︎

Возвращает уникальный идентификатор для страницы.

modified()⚓︎

Возвращает метку времени последнего изменения страницы.

date()⚓︎

Возвращает метку даты и времени для страницы. Обычно это устанавливается в заголовках для представления даты страницы или публикации. Если значение не определено явно, используется временная метка изменения файла.

template()⚓︎

Возвращает имя шаблона страницы без расширения .md. Например, default

filePath()⚓︎

Возвращает полный путь к файлу страницы. Например, /Users/yourname/sites/grav/user/pages/01.home/default.md

filePathClean()⚓︎

Возвращает относительный путь от корня сайта Grav. Например, user/pages/01.home/default.md

path()⚓︎

Возвращает полный путь к директории, содержащей страницу. Например, /Users/yourname/sites/grav/user/pages/01.home

folder()⚓︎

Возвращает имя папки для страницы. Например, 01.home

taxonomy()⚓︎

Возвращается массив таксономии, связанный со страницей. Их можно перепрограммировать. Это особенно полезно для отображения таких элементов, как теги:

{% for tag in page.taxonomy.tag %}
    <a href="search/tag:{{ tag }}">{{ tag }}</a>
{% endfor %}

Объект pages⚓︎

Объект pages — это корневая страница, которая представляет собой вложенное дерево всех объектов page, о которых знает Grav. Это особенно полезно для создания карты сайта, навигации или если вы хотите найти определённую страницу.

Этот объект не похож на grav.pages, который является экземпляром класса Pages.

Метод children⚓︎

Возвращает непосредственные дочерние страницы в виде массива объектов pages. Так как объект страниц представляет все дерево, вы можете полностью повторить каждую страницу в Grav страницах/папке.

Получите страницы верхнего уровня для простого меню:

<ul class="navigation">
    {% for page in pages.children %}
        {% if page.visible %}
            <li><a href="{{ page.url }}">{{ page.menu }}</a></li>
        {% endif %}
    {% endfor %}
</ul>

Объект media⚓︎

Появился новый объект, который позволяет вам получить доступ к media, находящимся за пределами объектов Page, через потоки PHP из Twig. Это работает аналогично связыванию изображений в содержимом с использованием потоков для доступа к изображениям и обработки мультимедиа для управления темой.

{{ media['user://media/bird.png'].resize(50, 50).rotate(90).html()|raw }}

Объект uri⚓︎

Полный список методов объекта Uri доступен на странице API. Вот список наиболее полезных для вас методов.

У объекта Uri есть несколько методов для доступа к частям текущего URI. Для полного URL http://mysite.com/grav/section/category/page.json/param1:foo/param2:bar/?query1=baz&query2=qux:

path()⚓︎

Возвращает часть пути URL-адреса: (Например, uri.path = /section/category/page)

paths()⚓︎

Возвращает массив элементов пути: (Например, uri.paths = [section, category, page])

route([absolute = false][, domain = false])⚓︎

Возвращает маршрут как абсолютный или относительный URL. (Например, uri.route(true) = http://mysite.com/grav/section/category/page или uri.route() = /section/category/page)

params()⚓︎

Возвращает часть URL-адреса params: (Например, uri.params = /param1:foo/param2:bar)

param(id)⚓︎

Возвращает значение определенного параметра. (Например, uri.param('param1') = foo)

query()⚓︎

Возвращает часть запроса URL-адреса: (Например, uri.query = query1=bar&query2=qux)

query(id)⚓︎

Вы также можете получить определённые элементы запроса: (Например, uri.query('query1') = bar)

url([include_host = true])⚓︎

Возвращает полный URL-адрес с хостом или без него. (Например, uri.url(false) = grav/section/category/page/param:foo?query=bar)

extension()⚓︎

Это вернет расширение или вернет html, если не указано: (Например, uri.extension = json)

host()⚓︎

Возвращает хост-часть URL-адреса. (Например, uri.host = mysite.com)

base()⚓︎

Возвращает базовую часть URL-адреса. (Например, uri.base = http://mysite.com)

rootUrl([include_host = false])⚓︎

Возвращает корневой URL-адрес экземпляра Grav. (Например. uri.rootUrl() = http://mysite.com/grav)

referrer()⚓︎

Возвращает информацию о реферере для этой страницы.

Объект header⚓︎

Объект заголовка является псевдонимом для page.header() оригинальной страницы. Это удобный способ получить доступ к оригинальным заголовкам страниц, когда вы петляете по другим объектам page дочерних страниц или коллекций.

Объект content⚓︎

Объект содержимого является псевдонимом page.content() оригинальной страницы.

Для отображения содержимого страницы необходимо:

{{ content|raw }}

Объект taxonomy⚓︎

Объект глобальной таксономии, содержащий всю информацию по таксономии сайта.

Объект browser⚓︎

Весь список методов объектов Браузера доступен на странице API. Вот список методов, которые вы найдете наиболее полезными.

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

{{ browser.platform}}   # macintosh
{{ browser.browser}}    # chrome
{{ browser.version}}    # 41

Объект user⚓︎

Вы можете получить доступ к текущему объекту пользователя, вошедшему в систему, косвенно через объект Grav. Это позволяет получить доступ к таким данным, как username, fullname, title и email:

{{ grav.user.username }}  # admin
{{ grav.user.fullname }}  # Вася Иванов
{{ grav.user.title }}     # Администратор
{{ grav.user.email }}     # vasja@ivanoff.com

Добавление своих переменных⚓︎

Вы можете легко добавлять пользовательские переменные разными способами. Если переменная является переменной для всего сайта, вы можете поместить её в свой файл user/config/site.yaml, а затем получить к нему доступ через:

{{ site.my_variable }}

В качестве альтернативы, если переменная нужна только для определенной страницы, вы можете добавить её в предварительную часть YAML вашей страницы и получить к ней доступ через объект page.header. Например:

title: My Page
author: Joe Bloggs

может использоваться как:

Автор этой страницы: {{ page.header.author }}

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

Расширенный способ добавления пользовательских объектов - использовать плагин для добавления объектов в объект Twig. Это сложная тема, которая более подробно рассматривается в главе о плагинах.

Переменные темы⚓︎

Ключевые объекты⚓︎

Переменная base_dir⚓︎

Переменная base_url⚓︎

Переменная base_url_relative⚓︎

Переменная base_url_absolute⚓︎

Переменная base_url_simple⚓︎

Переменная home_url⚓︎

Переменная html_lang⚓︎

Переменная theme_dir⚓︎

Переменная theme_url⚓︎

Переменная html_lang⚓︎

Переменная language_codes⚓︎

Объект assets⚓︎

Объект config⚓︎

Объект site⚓︎

Объект system⚓︎

Объект theme⚓︎

Объект page⚓︎

summary([size])⚓︎

content()⚓︎

header()⚓︎

media()⚓︎

title()⚓︎

menu()⚓︎

visible()⚓︎

routable()⚓︎

slug()⚓︎

url([include_host = false])⚓︎

permalink()⚓︎

canonical()⚓︎

route()⚓︎

home()⚓︎

root()⚓︎

active()⚓︎

modular()⚓︎

activeChild()⚓︎

find(url)⚓︎

collection()⚓︎

currentPosition()⚓︎

isFirst()⚓︎

isLast()⚓︎

nextSibling()⚓︎

prevSibling()⚓︎

children()⚓︎

orderBy()⚓︎

orderDir()⚓︎

orderManual()⚓︎

maxCount()⚓︎

children.count()⚓︎

children.current()⚓︎

children.next()⚓︎

children.prev()⚓︎

children.nth(position)⚓︎

children.sort(orderBy, orderDir)⚓︎

parent()⚓︎

isPage()⚓︎

isDir()⚓︎

id()⚓︎

modified()⚓︎

date()⚓︎

template()⚓︎

filePath()⚓︎

filePathClean()⚓︎

path()⚓︎

folder()⚓︎

taxonomy()⚓︎

Объект pages⚓︎

Метод children⚓︎

Объект media⚓︎

Объект uri⚓︎

path()⚓︎

paths()⚓︎

route([absolute = false][, domain = false])⚓︎

params()⚓︎

param(id)⚓︎

query()⚓︎

query(id)⚓︎

url([include_host = true])⚓︎

extension()⚓︎