Page Object

The {{ _page }} object holds information for building the page. It can be used for the following purposes.

Set and output Javascript files and inline Javascript

{% do _page.addJs('/path/to/file.js', {'group': 'footer'}) %}

{% inlinejs %}
$('.slideshow').start();
{% endinlinejs %}

{{ _page.js('footer') }}

Learn more

Set and output CSS files and inline CSS

{% do _page.addCss('/path/to/file.css') %}

{% inlinecss %}
body {color: blue;}
p {margin: 20px 0}
{% endinlinecss %}

{{ _page.css() }}

Learn more

Set and output meta content

{% do _page.addMeta({'name': 'robots', 'content': 'index, follow'}) %}

{{ _page.meta() }}

Add a meta tag if it doesn't already exist

{% do _page.addMetaIfMissing({'name': 'robots', 'content': 'index, follow'}) %}

Set the meta description

{% do _page.setMetaDescription('Page meta description value') %}

Set the meta robot tag

{% do _page.setMetaRobots('index, follow') %}

Set and output other HTML tags for the <head> section of a page

{% do _page.addHead('<link rel="canonical" href="http://www.mydomain.com/url">') %}

{% head %}
<link rel="canonical" href="http://www.mydomain.com/url">
{% endhead %}

{{ _page.head() }}

Set the canonical link for the page

You can manually set the canonical link as shown above, or you can use the following method.

{% do _page.setCanonicalLink('/url/to/page') %}

If the passed URL does not start with https: or http: then the base URL for the site will be added automatically.

Set or alter the page title

You can override the page title or append/prepend text to it.

Set the page title

 _page.title = 'New Title' %}

Append text to the existing page title

{% set _page.title = _page.title ~ ' New title'%}

Prepend text to the existing page title

{% set _page.title = 'New title ' ~ _page.title %}

Example scenario

One scenario would be to add the pagination page number to the title when someone is navigating through a paginated list of content.

{% if pagination.current > 1 %}
    {% set _page.title = _page.title ~ ' - Page ' ~ pagination.current %}
{% endif %}

Output the breadcrumb text

Output the full rendered breadcrumb HTML using the template under Settings -> Site Settings -> Breadcrumb Trail

{{ _page.breadcrumb() }}

You can also specify which position to start in the breadcrumb trail and where to end.

The start value specifies which position to start at. 1 is the first value, 2 is the second breadcrumb value and so on.

Output the breadcrumb HTML but skip the first one.

{{ _page.breadcrumb({start: 2}) }}

The max value can be used to set the maximum number of breadcrumb items to output.

{{ _page.breadcrumb({max: 3}) }}

You can combine the start and max values.

{{ _page.breadcrumb({start: 1, max: 2}) }}

You can also output just the breadcrumb text for the current page.

{{ _page.breadcrumbText }}

Edit the breadcrumb text

There are a few different ways that you can edit the breadcrumb content for a page.

Each breadcrumb item consists of two values:

  • text
  • url

For most of the methods below, you will be specifying both values for a breadcrumb item.

The last item in the list of breadcrumb items is treated as the active breadcrumb item for the current page.

Replace the existing breadcrumb content

This allows you to completely replace the existing breadcrumb data for a page with new information. 

Essentially you set an array of breadcrumb item values. The last item will be the active breadcrumb item for the page.

{% set _page.breadcrumb = [{'text': 'Page', 'url': '/pageurl'}, {'text': 'Sub', 'url': '/pageurl/sub' }] %}

Set the text of the active breadcrumb item

There are two ways to set the text of the active breadcrumb item.

{% set _page.breadcrumbText = 'New text' %}

{% do _page.setActiveBreadcrumbText('New text') %}

Append breadcrumb items

This will add a new breadcrumb item to the end of the current list of breadcrumb items. The last item added will be treated as the active breadcrumb item for the current page.

This is useful if you are creating custom pages using Routes.

{% do _page.appendBreadcrumb('Append text', '/append/url') %}

Prepend breadcrumb items

This will add a new breadcrumb item to the beginning of the current list of breadcrumb item.

{% do _page.prependBreadcrumb('Prepend text', '/prepend/url') %}

Insert a breadcrumb item before the active one

This will add a new breadcrumb item before the last breadcrumb item (the active breadcrumb item).

{% do _page.insertBreadcrumb('Insert text', '/insert/url') %}

Replace the last breadcrumb item

This will completely replace the last breadcrumb item, which is also the active breadcrumb item for the current page.

{% do _page.replaceActiveBreadcrumb('New Text', '/new/url') %}

Set and access cookie values

You can set cookie values to use on your site, or you can access cookie values that are set with Javascript. Below are some examples.

 Get a cookie value.

 {{ _page.cookies.myCookie }}

Test for a cookie value.

{% if _page.cookies.myCookie %}
{% endif %}

or

{% if _page.cookies.myCookie is defined %}
{% endif %}

Test to see if a cookie is not set,

{% if _page.cookies.myCookie is not defined %}
{% endif %}

Set a cookie value.

{% set _page.cookies.myCookie = 'cookie value' %}

Set a cookie value with expiration data.

{% do _page.cookies.set('myCookie', 'cookie value', '1000') %}

Chain set multiple cookie values.

{% do _page.cookies.set('anotherCookie', 'Cookie Value', 1000).set('chaincookie', 'chain cookie value') %}

Output page content

Each page is has one or more content areas that the Pages app or other apps can set content for. 

All pages have a main content area. There are two ways to output that area. You can use just the {{ _page.content() }} tag. If you don't pass an area key to that method, then the main content is automatically outputted.

{{ _page.content() }}

Or, you could pass the 'main' content area key.

{{ _page.content('main') }}

You can pass the key for another content area to output that one. Say that you had a content area called Sidebar with a key of sidebar. The following is how you would output the content for that area.

{{ _page.content('sidebar') }}

Test whether or not the page is the home page

You can test to see if the current page is the home page with following code.

{% if _page.isHome %}
{% endif %}

An example use case could be to include specific CSS for the home page. 

{% if _page.isHome %}
   <link type="text/css" rel="stylesheet" href="/path/to/file.css">
{% endif %}

Test and see if the page is not the home page.

{% if _page.isHome == false %}
    <p>This is not the home page.</p>
{% endif %}

An example could be to only include the breadcrumb text if the current page is not the home page.

{% if _page.isHome == false %}
    {{ _page.breadcrumb() }}
{% endif %}

Get app data for the page

If the page is for an app like a blog or store then information about the app page is set.

If the page is an app category page, then the full category information will be held in {{ _page.app.category }}.

{{ _page.app.urls }} holds an array of available app URLs.

If the page is for an app item like a blog post, gallery item or store product then that app item information will be held in {{ _page.app.item }}.

{{ _page.app.pageType }} holds the app page type for all apps except for the Pages app.

If the page is an app tag page then the full tag information will be held in {{ _page.app.tag }}.

The following information is set for all app pages, including the Pages app.

{{ _page.app.instanceKey }} holds the app instance key. 

{{ _page.app.instanceName }} holds the name of the app instance.

{{ _page.app.name }} Holds the name of the app. It will be all in lower case. For example, if the app is a blog then for all blog instances {{ _page.app.name }} will hold 'blog'.

Access the URL, GET and POST information for the page request

The {{ _page.request }} object holds information about the current page request.

GET parameters

If there are any parameters in the URL then they will be held in the {{ _page.request.get }} array. (You can alternately use the {{ _page.request.query }} variable.)

An example use could be to pass parameters in the URL to set a form field value. In this example, if the URL is:

http://www.mysite.com/contact?subject=Contact+Support

In the contact form there is a field called "subject". In the form template you could do the following:

{% set form.fields.subject.value = _page.request.get.subject %}

You can also access the GET parameters as a string at {{ _page.request.queryString }}.

POST parameters

If the page request is a form submission the post values are available in the {{ _page.request.post }} array.

IP address

The current IP address for the request is held in the {{ _page.request.ip }} variable.

Current URL

The current URL for the page request is held in the {{ _page.request.url }} variable. The _page.request.url value includes the URL path and the query string if it exists.

If you want to ensure that you are getting just the URL path then use {{ _page.request.path }}.

The base URL (the scheme and host) is held in the {{ _page.request.baseUrl }} variable. For example, for this current page, the base URL would be "https://www.branchcms.com". There is no trailing slash with the base URL value.

The host portion of the URL is held in the {{ _page.request.host }} variable. For example, for this current page, the host value would be "www.branchcms.com".

Referring URL

The URL that the visitor came from (if available) is held in the {{ _page.request.referrer }} variable.

Access the request headers

You can access the request headers from the browser in your templates. Use the {{ _page.request.headers }} variable to do so.

The {{ _page.request.headers }} variable holds an array of request headers. They are identical to the original request headers with one exception, any "-" characters are removed from the header name so that the data can be more easily used with Twig syntax.

For example, the "User-Agent" header is accessed using "UserAgent" instead of "User-Agent".

{{ _page.request.headers.UserAgent }}

Note that the case of the header name is important.

Most requests will probably include the following header values. Depending on the client making the request other headers could be included.

Array
(
  [Host] => www.branchcms.com
  [Connection] => keep-alive
  [CacheControl] => max-age=0
  [UserAgent] => Mozilla/5.0 (Macintosh; Intel Mac OS X 10_13_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/68.0.3440.106 Safari/537.36
  [Accept] => text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8
  [Referer] => https://www.branchcms.com/contact
  [AcceptEncoding] => gzip, deflate, br
  [AcceptLanguage] => en-US,en;q=0.9,la;q=0.8
  [Cookie] => cookieName=cookieValue
)

An example use case could be to detect if the user agent is a mobile device to redirect to another page or to show/hide certain content.

NOTE - User agent detection is brittle. However, this is a decent example of how to use the request headers.

The code below makes use of the regex_match filter. The code is based on a StackOverflow solution for Javascript user agent testing. It is by no means complete and you'd want to do some testing with specific user agents in order to confirm completeness.

{% if _page.request.headers.UserAgent|regex_match('/windows phone/i')|length > 0 %}
    <p>Windows</p>
{% elseif _page.request.headers.UserAgent|regex_match('/android/i')|length > 0 %}
    <p>Android</p>
{% elseif _page.request.headers.UserAgent|regex_match('/iphone|ipad|ipod/i')|length > 0 %}
    <p>IOS</p>
{% else %}
    <p>UNKNOWN Device</p>
{% endif %}

Test whether or not the request is an AJAX request

You can test and see if the request is an AJAX request with the following code.

{% if _page.request.isAjax %}
    {# Do something here such as output the content as JSON instead of HTML #}
{% else %}
    {# Do something else here such as output the content as HTML #}
{% endif %}

Test whether or not the page is a secure page

You can test whether or not HTTPS is being used on the current page with the {{ _page.request.isSecure }} variable.

{% if _page.request.isSecure %}
    {# Do something here #}
{% else %}
    {# Do something else here #}
{% endif %}

Test whether or not the request is a POST request

You can test whether or not the request type for the current page is a POST request with the {{ _page.request.isPost }} variable.

An example use case could be to show additional help information on a login page if the user is having trouble logging in.

{% if _page.request.isPost %}
    {# Do something here #}
{% else %}
    {# Do something else here #}
{% endif %}

Mobile and desktop links

If you are using mobile-specific templates then you may want to provide a link for the visitor to view the desktop template or the mobile template.

While we provide functionality for having mobile-specific templates, strongly recommend that you use responsive design techniques to make your website accessible to all screen sizes.

Mobile link

Outputs the link to view the site using mobile templates. 

<a href="{{ _page.mobileLink }}">View mobile site</a>

Desktop link

Outputs the link to view the site using mobile templates. 

<a href="{{ _page.mobileLink }}">View mobile site</a>

Set open graph data

While you can set open graph data when you edit content or through the site settings, you can also set it programmatically in your templates.

{% do _page.openGraph.setTitle('Page title') %}

Learn more

Template Name

You can get the name, full path, and directory path of the template used to render the entire page.

Tag Description
{{ _page.template.directory }}

The directory path to the template within the theme template folder.

This does not include the path to the theme template folder.

If the full path to your template is blog/post.twig then the directory will be blog.
{{ _page.template.name }}

The name of the template file. It does not include any file extensions.

If the full path to your template is blog/post.twig then the directory will be post.
{{ _page.template.path }}

The full path to the template minus the file extension of the template file.

This does not include the path to the theme template folder.

If the full path to your template is blog/post.twig then the path will be blog/post.

Body tag attributes

When you're editing a page you can set a specific class, id, or onload attribute value. Use the {{ _page.body }} object to access those values.

Below are the tags to output the body tag attributes.

Tag Description
{{ _page.body.attributes() }}

The full attributes string for the body tag.

<body{{ _page.body.attributes() }}>

If there are any attributes then a space will be added to the beginning of the attributes.
{{ _page.body.class }}

Outputs just the class attribute value if there is one.

<body class="{{ _page.body.class }}">
{{ _page.body.class.attr }}

Outputs the entire class attribute if an attribute value exists. If there is no attribute value then nothing is outputted.

<body{{ _page.body.class.attr }}>
{{ _page.body.id }}

Outputs just the id attribute value if there is one.

<body id="{{ _page.body.id }}">
{{ _page.body.id.attr }}

Outputs the entire id attribute if an attribute value exists. If there is no attribute value then nothing is outputted.

<body{{ _page.body.id.attr }}>
{{ _page.body.onload }}

Outputs just the onload attribute value if there is one.

<body class="{{ _page.body.onload }}">
{{ _page.body.onload.attr }}

Outputs the entire id attribute if an attribute value exists. If there is no attribute value then nothing is outputted.

<body{{ _page.body.onload.attr }}>
{{ _page.body.tag }}

Outputs the whole <body> tag along with any attributes.

Setting body tag attributes

If you want to use the {{ _page.body }} object to hold body tag attributes then you can also set attributes. The <body> tag attributes that you set are not limited to the class, body, or onload attributes.

You just have to set the values before you use them in your template.

Below are some different examples of setting values. 

{% set _page.body.class = 'myClassValue' %}

{# Append a value to the existing class value if there is one #}
{% set _page.body.class = _page.body.class ~ ' anotherClassValue' %}

{% set _page.body.id = 'idValue' %}
{% set _page.body.onload = 'codeToRun();' %}

{# Set a custom attribute #}
{% set _page.body.onunload = 'unloadFunction()' %}

{# Access just a custom attribute #}
<body{{ _page.body.onunload.attr }}>
<body onunload="{{ _page.body.onunload }}">

Output code after the opening <body> tag

Under Settings -> Analytics & Custom Code in the administration, you can set some custom code to output after the opening <body> tag.

A common use could be some tracking code to show on all pages. Or, you may need to set a portion of the Google Tag Manager code.

In order to use that code in your templates, you must set the following tag somewhere in your templates.

{{ _page.bodyStartCode() }}

Set the opening <body> tag code in your templates.

You can also add code to be output after the opening <body> tag in your templates. This code will only be output with the {{ _page.bodyStartCode() }} tag.

There are two methods to add the code. 

If your code is short or saved to a variable then you can do the following.

{% do _page.addBodyStartCode('MY_CODE_HERE') %}

If your code is multiple lines then you can do the following.

{% bodyStartCode %}
<script>
  const var = 'Some longer code here';
</script>
{% endBodyStartCode %}

Output code before the closing </body> tag

Under Settings -> Analytics & Custom Code in the administration, you can set some custom code to output before the closing </body> tag. 

An example use case would be if you need to set the Javascript code to use a chat tool.

In order to use that code in your templates, you must set the following tag somewhere in your templates.

{{ _page.bodyEndCode() }}

Set the closing </body> tag code in your templates.

You can also add code to be output before the closing </body> tag in your templates. This code will only be output with the {{ _page.bodyEndCode() }} tag.

There are two methods to add the code. 

If your code is short or saved to a variable then you can do the following.

{% do _page.addBodyEndCode('<script>Some code here</script>') %}

If your code is multiple lines then you can do the following.

{% bodyEndCode %}
<script>
  const var = 'Some longer code here';
</script>
{% endBodyEndCode %}