テーマを設計しているとき、Grav は Twig テンプレート内からあらゆる種類のオブジェクトや変数にアクセスできるようにします。Twig テンプレート・フレームワークは、これらのオブジェクトと変数を読み、操作するための強力な方法を提供します。これは Twig のドキュメントで完全に説明されており、我々のドキュメントでも簡潔にまとめられています。
Twig では、パラメータを取らないメソッドを呼び出すには、括弧() を省略します。パラメータを渡す必要がある場合は、メソッド名の後にそれらを記述する必要があります。page.content は page.content() と同じです。
Twig テンプレートで利用可能ないくつかのコア・オブジェクトがあり、各オブジェクトは変数と 関数を提供します。
{{ base_dir }} は、Grav をインストールしたのベース・ファイル・ディレクトリを返します。
{{ base_url }} は、Grav サイトのベース URL を返します。完全なURLを返すかどうかは、システム設定の absolute_urls option in the system configuration オプションに依存します。
{{ base_url_relative }} は、ホスト情報を除いたGravサイトのベースURLを返します。
The {{ base_url_absolute }} returns the base URL to the Grav site, including the host information.
The {{ base_url_simple }} returns the base URL to the Grav site, without the language code.
The {{ home_url }} is particularly useful to use to link back to the homepage of your site. It is similar to base_url but takes the currently active language into account.
This will return the current active language if provided, else use the site.default_lang configured option, else fall back to en.
The {{ theme_dir }} variable returns the file directory folder of the current theme.
The {{ theme_url }} returns the relative URL to the current theme.
When linking to assets like images or JavaScript and CSS files, it's recommended to use the url() function in combination with the theme:// stream as described on the Twig Filters & Functions page. For JavaScript and CSS, the Asset Manager is even easier to use but in some cases like dynamic or conditional loading of assets, it will not work.
The {{ html_lang }} returns the active language.
The {{ language_codes }} returns list of available languages of the site.
Asset Manager adds an easy way to manage CSS and JavaScript in your site.
{% 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!");') %}Read more about Asset Manager.
TIP: It is recommended to use styles tag and script tag instead.
You can access any Grav configuration setting set in the YAML-files in /user/config via the config-object. For example:
{{ config.system.pages.theme }}{# returns the currently configured theme #}config.site オブジェクトのエイリアスです。site.yaml ファイルの設定内容を返します。
config.system オブジェクトのエイリアスです。system.yaml ファイルの設定内容を返します。
config.theme オブジェクトのエイリアスです。アクティブなテーマの設定を返します。プラグインの設定は config.plugins で設定可能です。
Because Grav is built using the structure defined in the pages/ folder, each page is represented by a page object.
ページ・オブジェクトは、あなたが表示中のページに関するすべての情報を含んでいるので、おそらくあなたが扱う中で最も重要なオブジェクトと思われます。
Pageオブジェクトのメソッドの全リストは、API ページに公開されています。ここでは、最も有用と思われるメソッドをリストアップしています。
This returns a truncated or shortened version of your content. You can provide an optional size parameter to specify the maximum length of the summary, in characters. Alternatively, if no size is provided, the value can be obtained via the site-wide variable summary.size from your site.yaml configuration.
{{ page.summary|raw }}or
{{ page.summary(50)|raw }}A third option is to use a manual delimiter of === in your content. Anything before the delimiter will be used for the summary.
ページの HTML 全体を返します。
{{ page.content|raw }}ページの、YAML で定義されたページヘッダーを返します。以下のようなページ・ヘッダーが記述されている場合。
title: My Page
author: Joe Bloggs以下のように扱えます。
The author of this page is: {{ page.header.author|e }}This returns a Media object containing all the media associated with a page. These include images, videos, and other files. You can access media methods as described in the media documentation for content. Because it acts as an array, Twig filters and functions can be used. Note: SVG images are treated as files, not images, because they can not be manipulated using twig image filters.
Get a specific file or image:
{% set my_pdf = page.media['myfile.pdf'] %}Get the first image:
{% set first_image = page.media.images|first %}Loop over all images and output the HTML tag to display it:
{% for image in page.media.images %}
{{ image.html|raw }}
{% endfor %}This returns the title of the page as set in the title variable of the YAML headers for the page itself.
title: My PageThis returns the value of the menu variable of the YAML headers of the page. If none is provided, it defaults to the title.
title: My Page
menu: my-pageThis returns whether or not the page is visible. By default pages with numeric value followed by a period are visible by default (01.somefolder1) while those without (subfolder2) are not considered visible. This can be overridden in the page headers:
title: My Page
visible: trueThis returns whether or not a page is routable by Grav. This means if you can point your browser to the page and receive content back. Non-routable pages can be used in templates, plugins, etc, but cannot be reached directly. This can be set in the page headers:
title: My Page
routable: trueThis returns the direct name as displayed in the URL for this page, for example my-blog-post.
This returns the URL to the page, for example:
{{ page.url|e }} {# could return /my-section/my-category/my-blog-post #}or
{{ page.url(true)|e }} {# could return http://mysite.com/my-section/my-category/my-blog-post #}This returns the URL with host information. Particularly useful when needing a quick link that can be accessed from anywhere.
This returns the URL that is the 'preferred' version or link to a particular page. This value will default to the regular URL unless the page has overridden the canonical: page header option.
This returns the internal routing for a page. This is primarily used for internal routing and dispatching of pages.
This returns true or false based on whether or not this page is configured as the home page. This setting is found in the system.yaml file.
This returns true or false based on whether or not this page is the root page of the tree hierarchy.
This returns true or false based on whether or not this page is currently the page your browser is accessing. This is particularly useful in navigation to know if the page you are on is the active page.
This returns true or false based on whether or not this page is modular.
This returns whether or not this URI's URL contains the URL of the active page. Or in other words, is this page's URL in the current URL. Again this is useful when building your navigation and you wish to know if the page you are iterating over is the parent of an active child page.
This returns a page object as specified by a route URL.
{% include 'modular/author-detail.html.twig' with {'page': page.find('/authors/billy-bloggs')} %}This returns the collection of pages for this context as determined by the collection page headers.
{% for child in page.collection %}
{% include 'partials/blog_item.html.twig' with {'page':child, 'truncate':true} %}
{% endfor %}This returns the index of the current page in relation to its siblings.
This returns true or false based on whether this page is the first of its siblings.
This returns true or false based on whether this page is the last of its siblings.
This returns the next page from the array of siblings based on the current position.
This returns the previous page from the array of siblings based on the current position.
nextSibling() and prevSibling() order pages in a stack-like structure. It works best in a blog situation, where the first blog post has nextSibling null and prevSibling is the previous blog post. If this ordering direction confuses you, we suggest using page.adjacentSibling(-1) to point to the next page instead of page.nextSibling() to reduce the confusion that the terminology might make. You can also define a constant in the theme and use that for better readability, like page.adjacentSibling(NEXT_PAGE)
This returns an array of child pages for the page as defined in the pages content structure.
This returns the order type for any sorted children of the page. Values typically include: default, title, date and folder. This value is typically configured in page headers.
This returns the order direction for any sorted children of the page. Values can be either asc for ascending or desc for descending. This value is typically configured in page headers.
This returns an array of manual page ordering for any children of the page. This value is typically configured in page headers.
This returns the maximum number of children pages that are allowed to be returned. This value is typically configured in page headers.
This returns the number of child pages of the page.
This returns the current child item. Can be used while iterating over the children.
This returns the next child in the array of children.
This returns the previous child in the array of children.
This returns the child identified by the position which is an integer from 0 to children.count() - 1 in the array of children.
Reorders the children based on an orderBy (default, title, date and folder) and orderDir (asc or desc)
This returns the parent page object for this page. This is very useful when you need to navigate back up the nested tree structure of pages.
This returns true or false based on whether this page has an actual .md file associated with it rather than just a folder for routing.
This returns true or false based on whether this page is only a folder for routing.
This returns a unique identifier for the page.
This returns a timestamp of when the page was last modified.
This returns the date timestamp for the page. Typically this is set in the headers to represent the date of a page or post. If no value is defined explicitly, the file modified timestamp is used.
This returns the name of the page template without the .md extension. For example default
This returns the full file path of the page. For example /Users/yourname/sites/grav/user/pages/01.home/default.md
This returns the relative path from the root of the Grav site. For example user/pages/01.home/default.md
This returns the full path to the directory containing the page. For example /Users/yourname/sites/grav/user/pages/01.home
This returns the name of the folder for the page. For example 01.home
This returns an array of the taxonomy associated with a page. These can be iterated over. This is particularly useful for displaying items such as tags:
{% for tag in page.taxonomy.tag %}
<a href="search/tag:{{ tag }}">{{ tag }}</a>
{% endfor %}The pages object is the root page which represents a nested tree of every page object that Grav knows about. This is particularly useful for creating a sitemap, navigation or if you wish to find a particular page.
This object is not the same as grav.pages which is an instance of Pages class.
This returns the immediate child pages as an array of page objects. As the pages object represents the entire tree, you can fully recurse over every page in the Grav pages/ folder.
Get the top-level pages for a simple menu:
<ul class="navigation">
{% for page in pages.children %}
{% if page.visible %}
<li><a href="{{ page.url }}">{{ page.menu }}</a></li>
{% endif %}
{% endfor %}
</ul>There is a new object that allows you to access media that is outside of Page objects via PHP streams from Twig. This works in a similar manner to image linking in content by using streams to access images, and media processing to manipulate theme.
{{ media['user://media/bird.png'].resize(50, 50).rotate(90).html()|raw }}The whole list of the Uri object methods is available on the API site. Here's a list of the methods you'll find most useful.
The Uri object has several methods to access parts of the current URI. For the full URL http://mysite.com/grav/section/category/page.json/param1:foo/param2:bar/?query1=baz&query2=qux:
This returns the path portion of the URL: (e.g. uri.path = /section/category/page)
This returns the array of path elements: (e.g. uri.paths = [section, category, page])
This returns the route as either an absolute or relative URL. (e.g. uri.route(true) = http://mysite.com/grav/section/category/page or uri.route() = /section/category/page)
This returns the params portion of the URL: (e.g. uri.params = /param1:foo/param2:bar)
This returns the value of a particular param. (e.g. uri.param('param1') = foo)
This returns the query portion of the URL: (e.g. uri.query = query1=bar&query2=qux)
You can also retrieve specific query items: (e.g. uri.query('query1') = bar)
This returns the full URL with or without the host. (e.g. uri.url(false) = grav/section/category/page/param:foo?query=bar)
This returns the extension, or will return html if not provided: (e.g. uri.extension = json)
This returns the host portion of the URL. (e.g. uri.host = mysite.com)
This returns the base portion of the URL. (e.g. uri.base = http://mysite.com)
This returns the root url to the grav instance. (e.g. uri.rootUrl() = http://mysite.com/grav)
This returns the referrer information for this page.
The header object is an alias for page.header() of the original page. It's a convenient way to access the original page headers when you are looping through other page objects of child pages or collections.
The content object is an alias for the page.content() of the original page.
To display page content you should:
{{ content|raw }}The global Taxonomy object that contains all the taxonomy information for the site. For more information, see Taxonomy.
The whole list of the Browser object methods is available on the API site. Here's a list of the methods you'll find most useful.
Grav has built-in support for programmatically determining the platform, browser, and version of the user.
{{ browser.platform|e }} # macintosh
{{ browser.browser|e }} # chrome
{{ browser.version|e }} # 41You can access the current logged in user object indirectly via the Grav object. This allows you to access such data as username, fullname, title, and email:
{{ grav.user.username|e }} # admin
{{ grav.user.fullname|e }} # Billy Bloggs
{{ grav.user.title|e }} # Administrator
{{ grav.user.email|e }} # billy@bloggs.comYou can easily add custom variables in a variety of ways. If the variable is a site-wide variable, you can put the variable in your user/config/site.yaml file and then access it via:
{{ site.my_variable|e }}Alternatively, if the variable is only needed for a particular page, you can add the variable to your page's YAML front-matter, and access it via the page.header object. For example:
title: My Page
author: Joe Bloggscould be used as:
The author of this page is: {{ page.header.author|e }}An advanced way to add custom objects is to use a plugin to add objects to the Twig object. This is an advanced topic and is covered in more detail in the plugins chapter.