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.
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
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 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.
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
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: path: /blog/ template: blog/blog-index anotherBlogRoute: alias: blog path: /example-blog-path/
/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
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.
blog: path: /blog/ redirect: /another-blog/
Content can be loaded into templates and controllers directly from the route configuration without any further work required.
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.
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
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.