Routes
Routes allow you to create custom URLs that load a certain template.
Some possible uses include:
- You need to handle AJAX requests from an app page to return certain data.
- You want to set up a page to show a summary of content from one or more apps. An example of this could be if you have multiple blogs and you want to have a page that shows the recent posts from all of the blogs.
- Your website was migrated from a blogging system that used dates in the URL and you want to redirect to the new BranchCMS blog post URL.
Routes are available on BranchCMS Basic and higher plans.
Create a route
To create a new route go to Settings -> Routes and then click on the "Add a new route" button.
Give the route a name, fill in the URL that the route will match, and then enter the path to the template to use with the route.
You can use the same template with multiple routes if you want.
URL to match
When entering the URL to match don't include the domain name. Just include the URL path after the domain name.
For example, to match http://www.mydomain.com/my-custom-path enter /my-custom-path.
You can match dynamic URLs by entering in special placeholders as part of the URL. See the Dynamic URLs section below.
Template to load
Enter the path to the template that should be loaded. The path will start at the templates folder within your theme folder.
For example, if your theme folder is called custom and the full path to the template including the theme folder is
/custom/templates/my-template.twig
then you would simply enter in my-template in the "Template to load" field.
You can store templates in subfolders as well. For example, if you wanted to create a route for the blog app and you have your template in the blog template folder like this:
/custom/templates/blog/custom-route.twig
then your template path could look like this:
blog/custom-route
Note that in the above examples we don't include the ".twig" file extension. That's simply because it's not necessary. You can include it if you want, but it's not necessary.
Dynamic URLs
You can match dynamic URLs by entering in special placeholders as part of the URL.
Placeholders are wrapped in brackets. For example [day].
Below are the built-in placeholders:
| Placeholder | Description |
|---|---|
| [day] | A one or two digit number between 1 and 31. A single number can be prefixed with "0". The following are examples of valid values: 1
|
| [month] | A one or two digit number between 1 and 12. A single number can be prefixed with "0". The following are examples of valid values: 1 |
| [number] | Any number at any length (as long as there is at least one number). The following are examples of valid values: 1 |
| [slug] | Any text that does not include a "/". The following are examples of valid values: identifying-text |
| [year] | Any 4 digit number. The following are examples of valid values: 2010 |
Variables
The following variables are made available to the template.
- matches - an array of all the parts of the URL that matched the route
- route - the matched route URL
- routeName - the name of the matched route
- variables - an array of all matched placeholder values
Other variables
- Placeholder values
App pages
If the route starts with an app path then the system assumes that the page is an app page. Some additional variables are available.
- appKey
- appName
- appUrls
- categories (if the app supports categories)
- footer
- header
- tags (if the app supports tags)
The main app item will be available as well. For example, if the app is the Blog app then the posts variable is set.
Placeholder values
The value that matches the placeholder is made available to the template as a variable. By default, the name of the variable passed to the template will match the placeholder name.
For example, if [day] is used then a variable called day will be set to the matched value.
An array variable called variables is also set that holds all of the matched placeholders.
For example, if [day] is used then the matched value can be accessed at {{ variables.day }} in addition to the {{ day }} variable.
Custom placeholder variable names
A custom name can be set for a placeholder by adding a colon : after the placeholder name and then following that with a custom variable name.
For example: [day:myDay] will set a variable called myDay with the value matching the day placeholder.
Custom placeholder names should only contain letters and numbers. Punctuation and spaces are not allowed.
Custom placeholder names are useful if you need to use the same placeholder multiple times. If you don't use a custom placeholder name then the last matched placeholder would overwrite the previous values passed to the template.
For example, if your route URL to match is /[number]/[number]/[number]/[slug] and the URL is /12/30/2018/eat-your-veggies then the number variable will first be set to "12", then "30" and finally overwritten again to be "2018".
In the above example, if you want to access each number in the template you could either use the date placeholders ([day], [month], [year]) of you can give a custom name to each [number] placeholder.
/[number:month]/[number:day]/[number:year]/[slug]
You could also use custom placeholders:
/[postMonth]/[postDay]/[postYear]/[postKey]
Custom placeholders
Custom placeholders can also be used to match values. Any custom placeholder will simply match any text up until the next placeholder.
Custom placeholders should only contain letters and numbers. Punctuation and spaces are not allowed.
For example, the following "URL to match" value
/myurl/[key]/[anotherKey]
will match
/myurl/my-key/another-url-part
Both key and anotherKey are custom placeholders. Their values will be set to variables called key and anotherKey, respectively.
Placeholder matches
In addition to saving placeholder matches to specific variables, a matches variable is set with all of the matches for the route.
For example, if your route URL to match is /news/[month]/[day]/[year]/[slug] and the URL is /news/12/03/2017/bacon-rules then the following data is available in the matches variable.
array(
0 => /news/12/03/2017/bacon-rules
1 => 12
2 => 03
3 => 2017
4 => bacon-rules
)Page title, breadcrumb, and Open Graph data
A page title will be automatically set with the name of the matched route. You can override it in your template if desired.
{% set _page.title = 'My Title' %}
The breadcrumb text will be automatically set with the name of the matched route. You can override it if desired.
{% set _page.breadcrumbText = 'New text' %}
Basic Open Graph data is set if the Open Graph functionality is enabled.