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.

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
04
14
23
31

 

[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
04
10
12

[number]

Any number at any length (as long as there is at least one number).

The following are examples of valid values:

1
08
32
230
520303

[slug]

Any text that does not include a "/".

The following are examples of valid values:

identifying-text
sometexthere
text with spaces
text_with_underlines-and-dashes
mix-OF-uPPercase-anD-LOWERcase

[year]

Any 4 digit number.

The following are examples of valid values:

2010
2018
1987
2122
9999
0000

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.

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
)