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

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.

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.

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:

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.