テーマ変数

テーマをデザインするとき、 Twig のテンプレート内のすべての種類のオブジェクトや変数が使えます。
Twig テンプレートエンジンは、これらオブジェクトや変数を強力に読み取り、計算します。
このことは、 Twig ドキュメントに書かれていますし、私たちのドキュメントでも概要を説明しました。

[!Warning]
Twig では、引数の必要がない場合、カッコ () を除いても、メソッド名のみでそのメソッドを呼び出せます。引数を渡す必要があるときは、メソッド名の後にカッコが必要です。 page.content は、 page.content() と同じです。

コア・オブジェクト

Twig テンプレートで使える、いくつかの コア・オブジェクト があります。
それぞれのオブジェクトは、変数や関数を持ちます。

`base_dir` 変数

Grav がインストールされているベースのディレクトリを返します。

`base_url` 変数

Grav サイトのベースの URL を返します。
絶対 URL を返すかどうかは、 system.yaml の設定で、absolute_urls をどのように設定しているか次第です。

`base_url_relative` 変数

Grav サイトのベース URL を、ホスト情報無しで返します。

`base_url_absolute` 変数

Grav サイトのベース URL を、ホスト情報を含んで返します。

`base_url_simple` 変数

Grav サイトのベース URL を、言語コード無しで返します。

`home_url` 変数

サイト上で、ホームに戻るリンクを使うときに便利です。
base_url に似ていますが、こちらは、その時アクティブになっている言語を考慮に入れた URL が返ります。

`html_lang` 変数

その時点でアクティブになっている言語を返します。
もし無ければ、 site.default_lang の設定値を返します。
それもなければ、 en を返します。

`theme_dir` 変数

現在有効化されているテーマのディレクトリを返します。

`theme_url` 変数

現在有効化されているテーマの相対URLを返します。

[!Info]
画像や、 JavaScript 、 CSS ファイルにリンクしたい時、おすすめの方法は、 url() 関数を theme:// ストリームと組み合わせて使うことです。カスタム関数で解説しています。 JavaScript と CSS については、アセット管理の方が、かんたんに使えます。ただし、動的に（もしくは条件付きで）読み込みたいような場合は、機能しないこともあります。

`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!");') %}

くわしくは、アセット管理をお読みください。

[!Tip]
代わりに、 styles タグ や、script タグ の使用をおすすめします。

`config` オブジェクト

これを使えば、 /user/config ディレクトリ内の YAML ファイルに設定されているすべての設定にアクセス可能です。

{{ config.system.pages.theme }}{# returns the currently configured theme #}

`site` オブジェクト

config.site オブジェクトの別名です。
site.yaml ファイル内に設定した内容にアクセスできます。

`system` オブジェクト

config.system オブジェクトの別名です。
system.yaml ファイル内に設定した内容にアクセスできます。

`theme` オブジェクト

config.theme オブジェクトの別名です。
現在有効になっているテーマで設定した内容にアクセスできます。
プラグインに設定したものは、 config.plugins から取得できます。

`page` オブジェクト

Grav では、 pages/ フォルダ内のフォルダ構造を使うので、それぞれのページは、pageオブジェクト として利用できます。

page オブジェクト は、おそらく一番重要なオブジェクトで、現在のページのすべての情報を持っています。

[!Info]
Page オブジェクトのメソッドの全体リストは、 API サイトで利用できます。ここでは、最も便利なメソッドを紹介します。

summary([size])

コンテンツの概要を返します。
size を引数に渡すと、それを最大文字数とする概要になります。
代わりに、何も引数を渡さないときは、 site.yaml 設定の summary.size 変数が適用されます。

{{ page.summary|raw }}

もしくは

{{ page.summary(50)|raw }}

3つ目のオプションは、コンテンツ中を === で区切ることです。
この区切り文字の前にあるものが、概要として使われます。

content()

ページの HTML コンテンツ全体を返します。

{{ page.content|raw }}

ページのフロントマターに定義したものを返します。
たとえば、以下のようなフロントマターを書いたとします。

title: My Page
author: Joe Bloggs

次のように使えます：

The author of this page is: {{ page.header.author|e }}

media()

ページに関連するすべてのメディアを含む 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|raw }}
{% endfor %}

title()

ページのタイトルを返します。
ページのフロントマターで、 title 変数として設定したものです。

title: My Page

ページのフロントマターで、 menu 変数として設定した値を返します。
もしなければ、デフォルトでは 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|e }} {# could return /my-section/my-category/my-blog-post #}

もしくは、

{{ page.url(true)|e }} {# could return http://mysite.com/my-section/my-category/my-blog-post #}

permalink()

ホスト情報を含んだ URL を返します。
どこからでもアクセス可能なリンクが必要なときに、とくに便利です。

canonical()

そのページの ‘望ましい’ バージョンもしくはリンクの URL を返します。
この値は、ページのフロントマターで canonical で上書きしていなければ、通常のURLです。

route()

ページの内部的なルーティングを返します。
主に、内部的なルーティングとページの割り当てに使われます。

home()

そのページが、 ホーム かどうかを返します。
system.yaml ファイルで、ホームとなるページを設定できます。

root()

そのページが、ツリー階層のルート（root）ページかどうかを返します。

active()

そのページが、ブラウザでアクセスしているページと同じかどうかを返します。
ナビゲーションメニューで、そのページがアクティブかどうかを知りたいときに、特に便利です。

modular()

そのページが、モジュラーページかどうかを返します。

activeChild()

その URI の URL に、アクティブページの 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()

そのページが、兄弟ページの中で一番最初のページかどうかを返します。

isLast()

そのページが、兄弟ページの中で一番最後のページかどうかを返します。

nextSibling()

現在の場所に対して、次の兄弟のページを返します。

prevSibling()

現在の場所に対して、前の兄弟のページを返します。

[!Info]
nextSibling() と、prevSibling() は、スタック（後入れ先出し）形式でページを並べます。これは、ブログなどで最も役に立つもので、一番始めに並ぶブログ投稿について、 nextSibling は null で、prevSiblig は過去のブログ投稿となります。もしこの順番付けが難しいと感じるなら、 nextSibling の代わりに、 page.adjacentSibling(-1) を使ってください。また、テーマ内で使う定数を決めることもできます。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)

子ページの配列の中から、1つの position を持つ子ページを返します。
この position は、 0 から、 children.count() - 1 までの間の整数値です。

children.sort(orderBy, orderDir)

orderBy (default, title, date そして folder) と、 orderDir (asc もしくは desc) によって、子ページを並べかえます。

parent()

そのページの親ページのオブジェクトを返します。木構造になったページで、上にナビゲーションで移動したいときにとても便利です。

isPage()

そのページが、ただルーティングのためのフォルダではなく、 .md ファイルを持ったページであるかどうかを返します。

isDir()

そのページが、ルーティングのためだけのフォルダーかどうかを返します。

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 オブジェクトは、 Grav が確認できるすべての page オブジェクトのツリー構造を表したルートページです。
サイトマップや、ナビゲーション、特定の page を探すようなときに、特に便利です。

[!Info]
このオブジェクトは、Pages クラスのインスタンスである grav.pages とは違うものです。

children メソッド

page objects の配列から、直接の子ページを返します。
pages オブジェクトは、すべての木構造を表すので、再帰的にすべての pages/ フォルダ内のページを取得可能です。

シンプルなメニューを作るため、トップレベルのページを取得してみます：

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

`media` オブジェクト

ページオブジェクトの外にあるメディアに、 Twig から PHP ストリームを使ってアクセスできるオブジェクトです。
これは、画像リンクと似たような方法で機能します。
ストリームを使って画像やメディアにアクセスし、テーマを操作します。

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

`uri` オブジェクト

[!Info]
Uri オブジェクトのすべてのメソッドは API site を参照してください。ここでは、特に便利なものを列挙します。

Uriオブジェクトには、現在のURIの部分にアクセスするメソッドがあります。
完全なURIは：

http://mysite.com/grav/section/category/page.json/param1:foo/param2:bar/?query1=baz&query2=qux

とします:

path()

URLi のパス部分を返します： (例 uri.path = /section/category/page)

paths()

パスの要素の配列を返します： (例 uri.paths = [section, category, page])

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

絶対URLもしくは相対URLのルーティングを返します。 (例 uri.route(true) = http://mysite.com/grav/section/category/page or 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 = mysite.com)

base()

URL のベース部分を返します。 (例 uri.base = http://mysite.com)

rootUrl([include_host = false])

Grav インスタンスのルートとなる URL を返します。 (例 uri.rootUrl() = http://mysite.com/grav)

referrer()

このページに対するリファラ情報を返します。

`header` オブジェクト

ヘッダーオブジェクトは、オリジナルページの page.header() の別名です。
子ページやコレクションをループして、 page オブジェクトを扱う場合に、オリジナルのページヘッダーにアクセスできるのは便利です。

`content` 文字列

content オブジェクトは、オリジナルページの page.content() の別名（エイリアス）です。

ページのコンテンツを表示するには、次のようにします：

{{ content|raw }}

`taxonomy` オブジェクト

グローバルのタクソノミーオブジェクトは、サイトのタクソノミー情報をすべて持っています。
より詳しくは、タクソノミーをご覧ください。

`browser` オブジェクト

[!Info]
ブラウザオブジェクトのすべてのメソッドは、 API site をご覧ください。ここでは、最も便利なメソッドを列挙します。

Grav は組み込みで、ユーザーのプラットフォームや、ブラウザ、バージョンを調べるようにプログラムされています。

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

`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 ファイルに追加できます。
そして、以下のようにアクセスできます。

{{ site.my_variable|e }}

一方、特定のページでのみ必要な変数であれば、ページの YAML フロントマターで変数を追加できます。
page.header オブジェクトでアクセスできます。
たとえば：

title: My Page
author: Joe Bloggs

上記のように定義したとき、以下のように使えます：

The author of this page is: {{ page.header.author|e }}

カスタムオブジェクトを追加

Twig オブジェクトにカスタムオブジェクトを追加するのは、発展的な方法で、プラグインを使います。
これは発展的なトピックで、より詳しい内容は、プラグインの章で解説します。

テーマ変数

目次

コア・オブジェクト

`base_dir` 変数

`base_url` 変数

`base_url_relative` 変数

`base_url_absolute` 変数

`base_url_simple` 変数

`home_url` 変数

`html_lang` 変数

`theme_dir` 変数

`theme_url` 変数

`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()