ブループリント

ブループリントとは？

ブループリント（blueprint、青焼き図面、設計図）とは、 Grav にとって重要なものです。
テーマやプラグインと Grav の管理パネルがやりとりするために必要なベースとなるものです。
ブループリントによって、 Grav は、テーマやプラグインを識別し、その名前や GitHub のどこにあるのかなどを知ります。
また、 Grav の管理パネル内で、テーマやプラグインの設定オプションを生成します。

ブループリントは、 YAML ファイルで書かれ、一般的に、 form の定義と同じ書かれ方ができます。

ほとんどの Grav ユーザーは、ブループリントを扱うことはありません。
簡単に言うと、ブループリントは、プラグインやテーマが、サイトのバックエンドでどのように現れるかを決定するものです。
多くのユーザーにとって、この場所は、 Grav の管理パネルを使ってテーマやプラグインの設定をしたり、主要な YAML ファイルのオプション操作をするところです。

一方で、ブループリントを扱うのは、開発者です。
彼らは、新しいテーマやプラグインを作り、バックエンドのリソースオプションをカスタマイズします。
ブループリントは、強力なツールなので、リソースが何かや、 Grav がどこでアップデートを探すか、どんなオプションが設定できるかなどを決定してくれます。

ブループリントのタイプ

Grav では、ブループリントを次のように使います：

• テーマとプラグインの情報を定義する
• テーマ/プラグインの設定オプションを管理パネルプラグインで表示する
• 管理パネル画面中のページのフォームを定義する
• 管理パネルの Congiguration セクションのオプションに表示する内容を定義する
• フレックス・ディレクトリ/オブジェクトを定義する

ここで、ブループリントが Grav でどのように機能するか、詳細を説明します。

テーマとプラグイン

テーマやプラグインを使う時、慣例的に、パッケージに blurprints.yaml ファイルを置きます。
こうすることで、 Grav にそのリソースのメタデータが伝わり、管理プラグイン上で表示できるようになります。

blueprints.yaml ファイルは、あらゆるテーマやプラグインで重要です。
GPM ( Gravパッケージマネージャ) システムに不可欠です。
GPM は、ブループリントに入っている情報を使って、ユーザーがプラグインを使えるようにします。

具体例：プラグインのブループリント では、 Assets プラグインのブループリントを詳しく見ていきます。
このブループリントには、名前や、作者情報、キーワード、ホームページ、バグレポートリンク、その他のメタデータが入力されています。
また、どこでプラグインアップデートを探せるかを Grav システムに教えるだけでなく、管理プラグインからアクセス可能で便利なリソースを提供します。

ブループリントのページでは、これらのリソース情報の下に、フォームの情報が表示されます。
この情報は、 Grav のバックエンドでユーザーがアクセスできる管理フォームを作成します。
例えば、プラグインの特定の機能を有効または無効にするトグルを追加したい場合、ここに追加します。

blurprints.yaml ファイルは、プラグイン名の YAML ファイル (例: assets.yaml ) と連携して機能します。
ブループリントは、設定可能なオプションを定義します。
プラグイン名の YAML ファイルは、それぞれの具体的な値を設定します。
このプラグイン名の YAML ファイルは、後で user/config にコピーされ、デフォルト値を上書きできます。
この複製は、手動でも、管理パネルからでも行えます。

テーマやプラグインで設定オプションに関しては、 blurprint.yaml ファイルで定義し、プラグイン名（テーマ名）の YAML ファイルでその設定内容を教えてくれます。

ページ

[!訳注]
この部分は、説明が足りないと思うので、少し補足します。前の節までで解説されていたのが、テーマやプラグインのディレクトリ内にある blueprints.yaml ファイルの説明で、この節での説明は、主にテーマディレクトリ内の blueprints/ ディレクトリ内にある default.yaml ファイルや、 modular.yaml ファイルの説明です。そして次の節からは、 blueprints.yaml の説明に戻ります。 Grav では、 blueprint という言葉が、複数の意味や目的を持ち、複数のファイルを指すので、混乱しやすいです。 blueprint の意味が分からなくても、自分のサイト運営はできますし、自己用のオリジナルのテーマやプラグインを作ることもできます。自分以外の人が運営するサイトの管理パネルをカスタマイズする場合や、他者に配布するテーマやプラグインを作る場合は、 blueprint の概念を理解する必要があります。

Grav のページは、何にでもなれます。
ブログの一覧ページにもなりえますし、ブログ投稿にも、製品ページにも、イメージギャラリーにも、その他でも。

どのページが何をして、何を表すべきかを決めるのは、 ページのブループリント です。

Grav では、いくつかの基本的なページのブループリントを提供します: Default と、Modular です。
これらは、 Grav を構築する主要な2大要素です。

ページのブループリントは、テーマによって追加され、セットアップされます。
テーマは、できるだけ多くのページのブループリントを追加するかもしれませんし、特定の用途のためのページのブループリントに焦点を当てるかもしれません。

Grav のテーマは、他のプラットフォームで使われている以上に柔軟でパワフルです。

この点で、テーマは特化させられます。
たとえば、次のような目的のひとつに特化できます：

• ドキュメントサイトを作りたい（あなたが今読んでいるような）
• Eコマースサイトを作りたい
• ブログを作りたい
• ポートフォリオサイトを作りたい

テーマは同時に、これらすべてを作ることも許容します。
しかし通常は、ひとつの目的に集中してチューニングされたテーマは、何でもこなすテーマよりも、より目標を満たしてくれます。

ページファイルは、 blog.md や、 default.md 、 form.md のようなマークダウンファイルを設定することで、ページとして使われます。

それぞれのファイルは、異なるページファイルを使います。
フロントマターの template によってファイルタイプを変えることもできます。

ページで使われるテンプレートは、単にフロントエンドの “見た目や雰囲気” を決定するだけでなく、どのように管理パネルプラグインがレンダリングし、オプションやセレクトボックス、カスタム入力、トグル入力などを追加するかも決定します。

そのやり方：テーマで、blueprints/ フォルダを追加し、ページテンプレート名の YAML ファイルを追加します。
たとえば、 blog ページがある場合、 blueprints/blog.yaml を追加してください。
Antimatter テーマの例 があります。

ブループリントの構成

blueprints.yaml ファイルに書かれる情報は、2種類あります。
1種類目のメタデータ情報は、そのリソースそのもののアイデンティティです。
2つ目は、フォームに関する情報です。
これらすべてが、ひとつの blurprints.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 などです。
このセクションは、以下のような管理パネルのスクリーンショットで見られます。

次のセクションは、フォームに関する部分で、上記のデータのすぐ下にあります。
この部分は、管理パネルからプラグイン設定をするためのフォームや入力欄を生成します。
以下は、 blueprints.yaml ファイルのこの部分の簡易的な例です。

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

ファイルのこの部分は、管理パネルからアクセス可能な管理オプションを作成します。
この例では、管理画面からプラグインを有効または無効にできるシンプルなトグルを作成しています（以下の画像のようになります）

ブループリントのデバッグ

ブループリントファイルにエラーがあると、予期せぬ結果を引き起こすかもしれません。

[!Tip]
CLI コマンド で、 bin/grav yamllinter を実行すると、 yaml ファイルのエラーレポートが取得できます。 YAML ファイルを修正するときには、価値のある情報が得られるかもしれません。