Переменные темы¶
При создании темы Grav предоставляет доступ к различным объектам и переменным из шаблонов Twig. Шаблонизатор Twig предоставляет мощные способы чтения и обработки этих объектов и переменных. Это полностью описано в его документации и кратко изложено в нашей документации.
Совет
В Twig можно вызывать методы без параметров, просто указав имя метода и опустив скобки (). Если методу нужны параметры, их также указывают после имени. page.content эквивалентно page.content().
Основные объекты¶
В шаблоне Twig доступны несколько основных объектов, и у каждого есть набор переменных и функций.
Переменная base_dir¶
Переменная {{ base_dir }} возвращает базовую папку файлов установки Grav.
Переменная base_url¶
{{ base_url }} возвращает базовый URL сайта Grav. Показывается ли полный URL, зависит от параметра absolute_urls в конфигурации системы.
Переменная base_url_relative¶
{{ base_url_relative }} возвращает базовый URL сайта Grav без информации о хосте.
Переменная base_url_absolute¶
{{ base_url_absolute }} возвращает базовый URL сайта Grav, включая информацию о хосте.
Переменная base_url_simple¶
{{ base_url_simple }} возвращает базовый URL сайта Grav без языкового кода.
Переменная 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 ещё проще использовать менеджер ресурсов, но в некоторых случаях, например при динамической или условной загрузке ресурсов, он не подойдёт.
Переменная 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!");') %}
Подробнее о менеджере ресурсов.
Предупреждение
СОВЕТ: рекомендуется использовать вместо этого тег styles и тег script.
Объект config¶
Через объект config можно получить любую настройку Grav, заданную в YAML-файлах в /user/config. Например:
Объект 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.
или
Третий вариант — использовать ручной разделитель === в контенте. Всё, что стоит до разделителя, попадёт в сводку.
content()¶
Возвращает весь HTML-контент страницы.
header()¶
Возвращает заголовки страницы, заданные в YAML-метаданных страницы. Например, страница с такими заголовками:
может использоваться так:
media()¶
Возвращает объект Media, содержащий все медиафайлы страницы: изображения, видео и другие файлы. Методы медиафайлов описаны в документации по медиафайлам. Поскольку объект ведёт себя как массив, к нему можно применять фильтры и функции Twig. Примечание: SVG-изображения считаются файлами, а не изображениями, потому что их нельзя обрабатывать фильтрами изображений Twig.
Получить конкретный файл или изображение:
Получить первое изображение:
Перебрать все изображения и вывести HTML-тег для каждого:
title()¶
Возвращает заголовок страницы, заданный в переменной title YAML-заголовков самой страницы.
menu()¶
Возвращает значение переменной menu из YAML-заголовков страницы. Если она не задана, используется title.
visible()¶
Возвращает, видима ли страница. По умолчанию страницы с числовым значением и точкой видимы (01.somefolder1), а страницы без него (subfolder2) не считаются видимыми. Это можно переопределить в заголовках страницы:
routable()¶
Возвращает, маршрутизируема ли страница в Grav. Это значит, можно ли открыть страницу в браузере и получить контент. Немаршрутизируемые страницы можно использовать в шаблонах, плагинах и т. д., но напрямую к ним не обратиться. Это задаётся в заголовках страницы:
slug()¶
Возвращает непосредственное имя, отображаемое в URL страницы, например my-blog-post.
url([include_host = false])¶
Возвращает URL страницы, например:
или
{{ page.url(true)|e }} {# может вернуть http://my-site.example/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-маршрутом.
collection()¶
Возвращает коллекцию страниц для текущего контекста, определённую заголовками страницы коллекции.
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()¶
Возвращает массив таксономии, связанной со страницей. По нему можно перебирать. Особенно полезно для вывода таких элементов, как теги:
Объект pages¶
Объект pages — это корневая страница, представляющая вложенное дерево всех объектов page, известных Grav. Особенно полезно для создания карты сайта, навигации или поиска конкретной страницы.
Внимание
Этот объект не совпадает с grav.pages, который является экземпляром класса Pages.
Метод children¶
Возвращает непосредственные дочерние страницы в виде массива объектов page. Поскольку объект pages представляет всё дерево, можно рекурсивно обойти каждую страницу в папке pages/ Grav.
Получить страницы верхнего уровня для простого меню:
Объект media¶
Это новый объект, который позволяет из Twig обращаться к медиафайлам вне объектов Page через потоки PHP. Он работает аналогично подключению изображений в контенте: потоки используются для доступа к изображениям, а обработка медиафайлов — для управления ими.
Объект uri¶
Внимание
Полный список методов объекта Uri доступен на сайте API. Ниже перечислены методы, которые пригодятся чаще всего.
У объекта Uri есть несколько методов для доступа к частям текущего URI. Для полного URL http://example.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://example.com/grav/section/category/page или uri.route() = /section/category/page)
params()¶
Возвращает часть параметров URL: (например, 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 = example.com)
base()¶
Возвращает базовую часть URL. (например, uri.base = http://example.com)
rootUrl([include_host = false])¶
Возвращает корневой URL экземпляра Grav. (например, uri.rootUrl() = http://example.com/grav)
referrer()¶
Возвращает информацию о реферере для этой страницы.
Объект header¶
Объект header — псевдоним page.header() исходной страницы. Удобный способ получить доступ к заголовкам исходной страницы, когда вы перебираете другие объекты page дочерних страниц или коллекций.
Строка content¶
Объект content — псевдоним page.content() исходной страницы.
Чтобы вывести контент страницы, используйте:
Объект taxonomy¶
Глобальный объект Taxonomy, содержащий всю информацию о таксономии сайта. Подробнее см. в разделе Таксономия.
Объект browser¶
Внимание
Полный список методов объекта Browser доступен на сайте API. Ниже перечислены методы, которые пригодятся чаще всего.
Grav умеет программно определять платформу, браузер и версию пользователя.
Объект user¶
Текущего авторизованного пользователя можно получить через объект Grav. Так доступны данные username, fullname, title и email:
{{ grav.user.username|e }} # admin
{{ grav.user.fullname|e }} # Billy Bloggs
{{ grav.user.title|e }} # Administrator
{{ grav.user.email|e }} # billy@bloggs.com
Добавление пользовательских переменных¶
Пользовательские переменные можно легко добавлять разными способами. Если переменная нужна на всём сайте, добавьте её в файл user/config/site.yaml и обращайтесь к ней так:
Если переменная нужна только на конкретной странице, добавьте её в YAML-метаданные страницы и обращайтесь через объект page.header. Например:
можно использовать так:
Добавление пользовательских объектов¶
Продвинутый способ добавить пользовательские объекты — использовать плагин, который добавляет объекты в объект Twig. Это продвинутая тема, подробнее описанная в главе о плагинах.