Grav - Theme Variables

In this chapter let's study about Theme Variables. Objects and variables are accessed from twig templates while designing your theme and these objects & variables are read and manipulated by Twig Templating Framework.

Core Objects

Twig template has many core objects, each object has set of variables and functions.
Following table shows variables with brief description.

S.N.	Variables	Description
1	{{ base_dir }}	We can get Grav installations base file directory by using this variable.
2	{{ base_url }}	The base url of the Grav site can be accessed by using this variable.
3	{{ base_url_relative }}	It returns the relative path of the base url to Grav site.
4	{{ base_url_absolute }}	It returns the absolute path of the base url to Grav site.
5	{{ theme_dir }}	It is used to return current theme's file directory folder.
6	{{ theme_url }}	It is used to return current theme's relative URL.

config object

In configuration.yaml file the config object is set to access any Grav configuration setting.

{{ config.pages.theme }}

It will return the currently configured theme.

site object

Provides an alias to config.site object, representing configurations set in site.yaml file.

stylesheets object

These objects provides an array for CSS stylesheet assets to get stored, which can be looped to add CSS to templates.

scripts object

These objects provides an array that consists of JavaScript assets, which is looped over and JavaScripts are added to the templates.

page object

Since the structure of the Grav is defined in pages/ folder, the page object is responsible for representing each page. The page object contains all the informations about the page that you are currently working on.
Following tables shows methods of the page object.

S.N.	Methods	Description	Example
1	summary([size])	It shortens your page content with specified size provided as parameter. If size is not specified then the value is obtained from summary.size variable in system/config/site.yaml file. You can also delimiter === in your content. The content before the delimiter will be used for summary.	{{ page.summary }} Or {{ page.summary(80) }}
2	content()	It is used to get the entire HTML content of the page.	{{ page.content }}
3	headers()	It returns the page headers defined in the YAML front-matter of the page.	title: About Us author: Johnson The above headers can be accessed as: The author of this page is: {{ page.header.author }}
4	media()	It is used to access all the media files such as images, videos and other files. It will return an array containing all the media associated with a page.	{% set first_image = page.media|first %} {% set my_pdf = page.media['myfile.pdf'] %} {% for image in page.media.images %} {{ image.html }} {% endfor %}
5	title()	It is set to return the title of the page which is defined in YAML headers for the page.	title: My Page
6	menu()	The value of the menu variable is returned which is specified in YAML headers of the page. If the title variable is not set, then it will defaults to title.	title: My Blog menu: my blog page
7	visible()	It is used to set the visibility of the page. Usually pages with numeric value followed by period( i.e. 01.foldername) is displayed in menu and the folder name that does not contain numeric value( i.e. foldername) are not visible. We can override it in page header.	title: About Us visible: true
8	routable()	By using this we can determine whether a page is routable or not routable meaning that whether you can receive content back while pointing your browser to the page. The pages which are not routable can be used in plugins, templates, etc, and these pages cannot be directly accessed. This is set in page headers.	title: My Page routable: true
9	slug()	By using this variable, we can get direct name as displayed in URL of the page.	my-page
10	url([include_host = false])	It is used to return the page's URL	{{ page.url }} { # could return /myfolder/mypage #} Or {{ page.url(true) }} {# could return http: //mysite.com/ myfolder/mypage #}
11	route()	It is used to return the internal routing of the page.
12	home()	Using this variable you can determine whether the page is configured as home page or not. This returns true when a page is cofigured as home page and false when not configured. You can find this setting in system.yaml file.
13	root()	It determines whether the current page is root page of the hierarchy or not. It returns true if its a root page or false if it's not root page.
14	active()	You can determine whether the browser is accessing the current page by using this variable. It returns true if browser is accessing this page or false if its not.
15	modular()	By using this variable we can determine that whether this page is modular or not. If this is a modular page then it returns true and false if its not.
16	activeChild()	This variable can determine whether this URI's URL has the URL of the active page. Or in simple words this page's URL in current URL. This is very useful when you are working on navigations and you want to know that whether the pages are iterating over same parent page.
17	find(url)	As specified by the route URL, the page object is returned by this variable.	{% include 'modular/author-detail.html.twig' with {'page': page.find('/authors/ john-bloggs')} %}
18	collection()	This variable is used to return the group of pages for a 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 %}
19	isFirst()	If the current page is first of its sibling page, then it returns true else returns false.
20	isLast()	If the current page is last of its sibling page, then it returns true else returns false.
21	nextSibling()	With reference to the current position, it returns the next sibling page from the array.
22	prevSibling()	With reference to the current position, it returns the previous sibling page from the array.
23	children()	As defined in the pages content structure, array of child pages is returned by this variable.
24	orderBy()	The sorted children's order type is returned by this method. The values that may be included are default, title, date and folder and these values configured in page headers.
25	orderDir()	The sorted child pages order direction is returned by this method. And the values can be either asc(ascending) or desc(descending). usually these values are configured in page headers.
26	orderManual()	This method return an array consisting of manual page ordering and this ordering will be for any children of the page. This value will be typically set in page headers.
27	maxCount()	This variable tells that at most how many children pages are allowed to be returned. Usually the value is specified in page headers.
28	children.count()	This variable returns how many child pages are there for a page.
29	children.current()	This variable will return the current child item.
30	children.next()	This will return the next child item from an array of child pages.
31	children.prev()	This will return the previous child item from an array of child pages.
32	children.nth(position)	This will return the position of the child in the array of children.
33	parent()	In a nested tree structure when you want to navigate back up to the parent page, then you can use this variable. It will return the parent page object for current page
34	isPage()	By using this variable you can determine whether this page has an actual .md file or its just a folder for routing.
35	isDir()	By using this variable you can determine whether current page is only a folder for routing. It returns true or false based on it.
36	id()	This will return unique id for the page.
37	modified()	It returns timestamp of when the page was last modified.
38	date()	The date timestamp for the page is returned by this method. Usually this is configured in headers that represents the page's or post's date. If no value is provided by default modified timestamp is used.
39	filePath()	By using this you can get the full file path of the page.	/Users/yourname/sites/ grav/user/pages/ 01.home/default.md
40	filePathClean()	This will return the relative path.	user/pages/ 01.home/default.md
41	path()	This will return a full path to the directory in which the current page is present.	/Users/yourname /sites/ grav/user/pages /01.home
42	folder()	This will return folder name for the page.
43	taxonomy()	This will return an array of taxonomy which is connected with the page.

pages object

Pages object is represented as a nested tree of page objects. This nested tree is very useful while creating navigations, sitemap or finding a particular page.

children method

This returns an array of page objects consisting of child pages.The page object with a tree like structure you can iterate over every page in the folder.
In order to get the top level pages for menu, use the following code.

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

uri object

The part of the current URI can be accessed by using several methods of Uri object.

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

The following table shows methods of Uri object.

S.N.	Methods	Description	Example
1	path()	The part of the current url can be accessed by using this method.	uri.path = /section/category/page
2	paths()	The array of path elements is returned by this method.	uri.paths = [section, category, page])
3	route([absolute = false][, domain = false])	This method returns route with a either absolute or relative URL.	uri.route(true) = http://mysite.com/grav/ section/category/page Or uri.route() = /section/category/page)
4	params()	This will return the parameter portion in the URL.	uri.params = /param1:foo/param2:bar
5	param(id)	This will return the value of the param.	uri.param('param1') = foo
6	query()	The query portion of the URL can be accessed by using this method.	uri.query = query1=bar&query2=qux
7	query(id)	Using this you can access the specific query item.	uri.query('query1') = bar
8	url([include_host = true])	This returns the full URL which may or may not contain host.	uri.url(false) = grav/section/ category/page/param:foo?query=bar
9	extension()	This will return the extension or if not provided, then it will return the html.	uri.extension = json)
10	host()	This return the host of the URL.	uri.host = mysite.com
11	base()	This will return the base part of the URL.	uri.base = http://mysite.com
12	rootUrl([include_host = true])	This will return the grav instance's root URL.	uri.rootUrl() = http://mysite.com/grav
13	referrer()	The referrer information of the page is returned by this method.

header object

It is an alternate for page.header() of the original page. It is more appropriate to use the original page header when you are looping through the child pages.

content object

It is an alternate for page.content() of the original page.

taxonomy object

All the taxonomy informations of the site are contained in the global taxonomy object.

browser object

Grav programmatically determines the platform, browser and version of the user by using built-in support.

{{ browser.platform}}   # windows
{{ browser.browser}}    # chrome
{{ browser.version}}    # 24

Adding Custom Variables

Custom variables are added in several ways. If you are using site-wide variable, then put it in user/config/site.yaml file and you can access it as shown below.

{{ site.my_variable }}

If variable is only for a particular page then you can add it in YAML front-matter and access it by using page.header object.
For example:

title: My Page
author: John

Author name can be accessed as

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

Adding Custom Objects

By using plugins you can add custom objects to the Twig object. This is advanced topic and will see more information in plugins chapter.