Grav - Theme Variables


Advertisements

In this chapter, let us understand Theme Variables in Grav. 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 a set of variables and functions.

The following table shows variables with brief description.

Sr.No. Variable & 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 the 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 the configurations set in the site.yaml file.

stylesheets object

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

scripts object

These objects provide 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 information about the page that you are currently working on.

Following table shows methods of the page object.

Sr.No. Method & Description Example
1

summary([size])

It gives a gist of the page content with the specified size provided as a 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 default 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 the 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 configured 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 the root page of the hierarchy or not. It returns true if it's 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 it's not.

15

modular()

By using this variable, we can determine whether this page is modular or not. If this is a modular page then it returns true and false if it's 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 it's sibling page, then it returns true else returns false.

20

isLast()

If the current page is last of it's 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, the 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 returns 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 the current page.

34

isPage()

By using this variable, you can determine whether this page has an actual .md file or it’s 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 the 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 the 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 the 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 can be iterated 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 the Uri object.

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

The following table shows the methods of Uri object.

Sr.No. Method & 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 using this method.

uri.paths = [section, category, page])
3

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

This method returns route with 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 information 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 the 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 an advanced topic and we will see more information in the plugins chapter.

Advertisements