Схемы¶

Что такое схема?¶

Схемы — важная часть Grav. По сути, это основа взаимодействия темы или плагина с админкой Grav. Они сообщают Grav, что представляет собой тема или плагин, как он называется, где его можно найти на GitHub и т. д. Кроме того, схема формирует параметры конфигурации темы или плагина в админке Grav.

Схема определяется в файле YAML и обычно может содержать свойства, а также определения форм.

Подавляющему большинству пользователей Grav никогда не придётся работать со схемами. Проще говоря, они определяют, как плагины и темы выглядят в административной части сайта. Для большинства пользователей всё начинается именно здесь: они настраивают темы и плагины через админку Grav или меняют параметры в основном файле YAML темы или плагина.

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

Типы схем¶

Grav использует схемы, чтобы:

• определять сведения о темах и плагинах;
• определять параметры конфигурации темы или плагина, отображаемые в админке;
• определять формы страниц в админке;
• определять параметры, показанные в разделе Configuration админки;
• определять директории и объекты Flex.

Теперь разберём подробнее, как схемы работают в Grav.

Темы и плагины¶

При использовании с темами и плагинами принято помещать в пакет файл blueprints.yaml. Это сообщает Grav метаданные ресурса и представляет его в админке Grav.

Файл blueprints.yaml — важная часть любой темы и плагина. Он необходим для системы GPM (Grav Package Manager). GPM использует сведения из схемы, чтобы сделать плагин доступным пользователям.

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

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

![Формы в админке](blueprints_1.png?classes=shadow)

Файл blueprints.yaml работает вместе с именованным файлом YAML плагина (например, assets.yaml). Схема задаёт, какие параметры можно настраивать, а именованный файл YAML ресурса задаёт их значения. Затем этот именованный файл YAML копируется в раздел user/config экземпляра Grav, чтобы переопределить значения по умолчанию — вручную или через админку Grav.

Итак, для любого параметра конфигурации темы или плагина файл blueprints.yaml определяет сам параметр, а именованный файл YAML этого ресурса сообщает, какое значение в нём установлено.

Страницы¶

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

Что определяет, что должна делать страница и как она должна выглядеть, — это схема страницы.

Grav предоставляет несколько базовых схем страниц: Default и Modular. Это два основных строительных блока Grav.

Дополнительные схемы страниц добавляет и настраивает тема — она может добавить сколько угодно схем страниц или сосредоточиться на нескольких, ориентированных на её задачи.

Тема Grav гораздо гибче и мощнее, чем вы, возможно, привыкли на других платформах.

Это позволяет делать темы под конкретное применение. Например, тема может специализироваться на одной из целей:

• создание сайта документации, как тот, который вы сейчас читаете;
• создание сайта интернет-магазина;
• создание блога;
• создание сайта-портфолио.

Тема также может позволять создавать всё перечисленное, но обычно тщательно настроенная тема под одну цель лучше справляется с задачей, чем универсальная.

Файл страницы используется страницей путём указания имени её markdown-файла, например blog.md, default.md или form.md.

Каждый из этих файлов использует свой файл страницы. Тип файла также можно изменить, используя свойство заголовка template.

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

Как это сделать: в своей теме добавьте папку blueprints/ и файл YAML с именем добавленного шаблона страницы. Например, если вы добавили шаблон страницы blog, добавьте файл blueprints/blog.yaml. Пример такой папки можно найти в теме Antimatter.

Составные части схемы¶

В файле blueprints.yaml представлены два набора сведений. Первый — метаданные самого ресурса, второй — сведения о формах. Всё это хранится в одном файле blueprints.yaml в корне каждого плагина и темы.

Вот пример части метаданных файла blueprints.yaml:

name: GitHub
slug: github
type: plugin
version: 1.0.1
description: "This plugin wraps the [GitHub v3 API](https://developer.github.com/v3/) and uses the [php-github-api](https://github.com/KnpLabs/php-github-api/) library to add a nice GitHub touch to your Grav pages."
icon: github
author:
  name: Team Grav
  email: devs@getgrav.org
  url: https://getgrav.org
homepage: https://github.com/getgrav/grav-plugin-github
keywords: github, plugin, api
bugs: https://github.com/getgrav/grav-plugin-github/issues
license: MIT

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

![Формы в админке](blueprints_2.png?classes=shadow)

Следующий раздел — область форм, она находится чуть ниже перечисленных данных. Эта часть схемы создаёт формы и поля, используемые для настройки плагина из админки Grav. Вот краткий пример этой части файла blueprints.yaml.

form:
  validation: strict
  fields:
    enabled:
        type: toggle
        label: Plugin status
        highlight: 1
        default: 1
        options:
            1: Enabled
            0: Disabled
        validate:
            type: bool

Эта часть файла создаёт административные параметры, доступные в админке Grav. В данном случае мы создали простой переключатель Plugin Status, который позволяет пользователю включать или отключать плагин из админки (см. изображение ниже).

![Формы в админке](blueprints_3.png?classes=shadow)

Отладка схем¶

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