User Guides

Routes Configuration

The routes config allows you to define routes on your website. Routes define how a request should be handled, whether that be rendering a template or passing the request to a controller to be processed.


Basic Example

The following shows a basic example that registers two routes, the first route simply renders a template, the other route passes the request through to a controller for further processing.

# This route renders a template
templateRoute:
  path: /some-path/
  template: path/to/template

# This route passes the request to the someFunction method in the SomeController controller
controllerRoute:
  path: /some-other-path/
  controller: SomeController/someFunction

Dynamic Segments

Routes can be defined with dynamic segments in the path, this allows data to be passed into a request.

When dynamic segments are defined, you must also define the type of data that you expect to receive through that segment. This is done using a token, tokens validate the data inputted into the URL ensuring that only valid data can be passed into the request.

For example, the route below for a blog post accepts a dynamic segment named postSlug. The postSlug dynamic segment has defined its token as slug which will ensure that the data passed into the dynamic segment can consist of only alpha-numeric characters and hyphens.

blogPost:
  path: /blog/post/[postSlug:slug]/
  template: blog/blog-post

In the event that invalid data is passed into the dynamic segment, the route will not match and therefore will not be handled unless it is caught by another route definition.

For a list of all of the available token types, see the Tokens Configuration section.


Parent Routes

Routes can have a parent route assigned to them, this allows the parent route to marked as active while you are viewing a child route. This is useful in circumstances when you have sub pages within a section. If for example you had a blog section, you may want the blog link in the menu to remain active even when you were reading one of the blog posts.

This can be achieved by passing the name of the route that you would like to be assigned as the parent route to the parent attribute of the child parent, for example:

blog:
  path: /blog/
  template: blog/blog-index

blogPost:
  parent: blog
  path: /blog/post/[slug:postSlug]/
  template: blog/blog-post

Alias Routes

A route can be defined as an alias of another route, this allows a single route to be located at multiple URLs. When a route is defined as an alias, a canonical meta tag is also placed into the page in order to prevent issues with SEO as a result of content duplication.

For example, the follow routes both load the blog/blog-index template.

blog:
  path: /blog/
  template: blog/blog-index

anotherBlogRoute:
  alias: blog
  path: /example-blog-path/

Visiting /example-blog-path/ would actually load the blog/blog-index template as defined in the blog route, the only difference being that there would be a canonical meta tag set pointing towards /blog/.


Redirects

Temporary redirects can be defined within the route config file, enabling you to temporarily redirect traffic from a particular route to the specified destination URL. The destination URL can either be a relative to the websites root or an absolute URL.

Example:

blog:
  path: /blog/
  redirect: /another-blog/

Route Content

Content can be loaded into templates and controllers directly from the route configuration without any further work required.

Loading Sections

If you had defined a section named 'Blog', and wanted to access the content from that section within either a template or a controller, you would do the following:

blog:
  path: /blog/
  template: blog/blog-index
  vars:
    Blog:
      type: section
      section: Blog

There would now be an instance of the Blog section accessible via Blog variable in the blog/blog-index template which could then be used to access the content defined in the Blog section. For details on how to access the content within a section, see Sections.

In controllers, the Blog variable would be accessible from the vars property of the request.

Loading Collection Items

Expanding on the blog post example in the 'Dynamic Segments' section. If you had a collection named blogposts, and wanted to retrieve a post using the slug that had been provided in the URL, you would do the following:

blogPost:
  path: /blog/post/[slug:postSlug]/
  template: blog/blog-post
  vars:
    blogPost:
      type: collection
      collection: blogposts
      slug: postSlug

This would take the value from the postSlug dynamic segment and attempt to find an item in the blogposts collection that had a slug that matched the value in the blogPost segment.

Meta Data

Sections and collection items can also define meta data that may be used by a route. This can be achieved by simply setting the meta property to 'true' on the section / collection item that you wish to pull the meta data from.

For example, the following config displays how you would pull meta data from a section named 'Blog':

blog:
  path: /
  template: blog/blog-index
  vars:
    Blog:
      type: section
      section: Blog
      meta: true

This can also be applied to collection items as follows:

blogPost:
  path: /blog/post/[slug:postSlug]/
  template: blog/blog-post
  vars:
    blogPost:
      type: collection
      collection: blogposts
      slug: postSlug
      meta: true

If you have multiple vars with the meta property set to true, only the last one will be taken into account.