Чертежи⚓︎

Что такое чертеж?⚓︎

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

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

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

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

Типы чертежей⚓︎

Grav использует чертежи для:

• определять темы и информацию о плагинах.
• определить параметры конфигурации темы/плагина, которые будут отображаться в админке.
• определить формы страниц в админке.
• определите параметры, показанные в разделе «Конфигурация админки».
• определите flex-каталоги/объекты.

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

Темы и плагины⚓︎

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

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

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

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

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

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

Страницы⚓︎

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

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

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

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

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

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

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

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

Файл подкачки используется страницей путем установки имени файла разметки, например blog.md, default.md или form.md.

Каждый из этих файлов будет использовать отдельный файл подкачки. Вы также можете изменить тип файла, используя свойство заголовка шаблона.

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

Как это сделать: в своей теме добавьте папку 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 Admin. Вот краткий пример этой области файла blueprints.yaml.

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

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

Отладка чертежей⚓︎

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