Insites Docs Developers guide Pages and LayoutsContent and LayoutsPages

Pages

Last updated on August 06, 2024.

Pages are the essential components of our platform that define content displayed at a given path. A single file with a extension represents each page. All pages have to be located in the directory.

Routing mechanism for pages

Each page is accessible on the URL indicated by its location in the codebase if not otherwise specified in the page configuration property. For example, the page deployed to the domain is automatically accessible at .

Note

In the examples, we often add the property to show where the page is accessible, even if it is not required because it is the same as the default.

Named parameters

You can use named parameters in the slug. For example, a slug resolves a URL like https://example.com/projects/1, and you can access the named parameter using . In this example, returns .

For optional parameters, use syntax. For example, resolves all three types of URLs:

  • ( and resolve to nulls)
  • ( resolves to )
  • ( resolves to and resolves to ).

For backward compatibility, named parameters are also available at the corresponding name.

Page configuration

page configuration elements

The page configuration is made up of two elements, with sub-sections:

  • YAML
  • Content
YAML

YAML stands for Yet Another Markup Language and defines the configuration of the page. The sub-sections of the pages YAML are:

  • Properties - The page properties define the structure of the page and are optional.
  • Metadata - The metadata properties are required to have the page shown within the Insites Instance Admin (IIA).
Content

The content of your page contains the HTML, Liquid and JavaScript (or other relevant code) to be rendered on your page.

Here is a sample page configuration file:

app/views/pages/my-page.liquid

Explanation:

  • : The page uses the layout .
  • : Specifies the slug of the page.

Available properties

The table below displays all the available properties for creating a page.

Property Options Default Required Description
No An array of authorization policies run before rendering the page
markdown No
No Defines which layout from you would like to use for pages with HTML format.

If you don't want to use any layout, set it to an empty string. The system behaves as if you are just rendering page content.

Note: Excluding this property altogether causes the page to use the layout last used for the current page. It uses the default layout if no layout has been used.
positive integer 3 No Defines what the intended nesting level of the slug is. For example, if the slug is and is set to '1', then a path like results in a 404. If set to '2', however, it renders the page. Using this property is useful for SEO to avoid duplicated content.
No An object that you can define and access via in different places
  • get
  • post
  • put
  • delete
 get No
  • 301
  • 302
 302 No A status that a user should add to an HTTP response
No URL to a page you want to redirect
No JSON object that you can define to override most of the HTTP headers
The default slug is automatically created based on the page's location in the codebase. For example, a page has the default slug . No Use the property to overwrite the default slug.

Everything after the front matter is the body of the page.

Available metadata

The table below displays all the available metadata for creating a page.

Property Options Default Required Description
application Yes Title of the page.
Yes Name of the page.
  • content
  • system
  • file
 Yes Type of page.
  • published
  • archived
 published Yes Status of the page, whether active or archived.
  • none
  • secure_zone
  • api_keys
 none No Type of security used by the page.
No Description of the page.
No Meta title used by the page.
No The name of your site when sharing across Facebook, Twitter, LinkedIn and other Social Media platforms.
No Title of the page in Open Graph.
No A sentence snippet that shows on your post when sharing across Facebook, Twitter, LinkedIn and other Social Media platforms.
No The URL that is associated with your content when sharing across Facebook, Twitter, LinkedIn and other Social Media platforms.
No The type of content when shared across Facebook, Twitter, LinkedIn and other Social Media platforms.
No Image used when sharing the content across Facebook, Twitter, LinkedIn and other Social Media platforms.
No Schema markup used by the page.
No Canonical URL used by the page
No Order of the URL in relation to other URLs in the same priority value. Similar priority URLs are sorted in ascending order.

Boolean

  • true
  • false
 No Adds the page to the system sitemap if the value is 'Enabled'
No The priority of this URL relative to other URLs on the site. Valid values range from 0.0 to 1.0. URLs are sorted in descending order.
  • always
  • hourly
  • daily
  • weekly
  • monthly
  • yearly
 No Frequency that web crawlers should check the page for changes.

Boolean

  • true
  • false
 No Enabling this adds meta name='robots' content='noindex' to the head of the page

Homepage

The Homepage slug is which works for both https://example.com and https://example.com/. The slug of the file defaults to . This sample file configures the home page:

app/views/pages/index.liquid

Subdomains

You can add subdomains in the header of a page like this:

The page matches the current request and is only displayed if the specified subdomain matches the subdomain of the request. You can specify any subdomain parts, and the system attempts to match the subdomains of the request from left to right.

This means matches a request for the domain . Meanwhile, matches a request for the domain .

Formats

To define which format the endpoint is available for, place before the file extension.

Format name Example filename
html about-us.html.liquid
xml orders.xml.liquid
csv users-report.csv.liquid
json coordinates.json.liquid
rss feed.rss.liquid
css datepicker.css.liquid
js server-constants.js.liquid
txt notes.txt.liquid
ics calendar.ics.liquid

Accessing different formats

You can access multiple pages simultaneously with the same slug but in different formats.

For example, you can have both , , and versions of a page with :

app/views/pages/hello.html.liquid

Is accessible under the URL:

app/views/pages/hello.csv.liquid

Is accessible under the URL:

Is accessible under the URL:

Note that the format is implicit; by default, you don't need to specify it in the URL or the file name.

Method

To define to which method the endpoint responds, define in the Page configuration. One page can respond to exactly one method.

POST/PUT/PATCH/DELETE methods and Cross-Site Request Forgery attacks

To protect against Cross-Site Request Forgery (CSRF) attacks, the use of a CSRF Token for all non-GET requests is enforced. This security measure prevents attackers from tricking users into unknowingly executing unauthorized endpoints. When a request is made without a valid CSRF Token, the returns null, indicating that the user session has been invalidated. To ensure access to , it is essential to provide a valid CSRF Token.

Forms, are handled automatically by adding a hidden parameter with the name . However, suppose you manually trigger a POST/PUT/PATCH/DELETE AJAX request. In that case, you must remember to populate the header with a value from and specify the header.

Common practice is to include a tag in the layout, for example, and use this value to execute an AJAX request.

If you are building a JSON API, for example, for a mobile app, you can authenticate users using JWT tokens.

Related topics

Have a suggestion for this page?

Didn't quite find what you are looking for or have feedback on how we can make the content better then we would love to hear from you. Please provide us feedback and we will get back to you shortly.