URL Templates

Writing links to internal content manually is time-consuming and error-prone, especially once content in multiple languages is involved, so one of the most common features in any traditional content management system is to make this process as easy and secure as possible. Unfortunately, a headless CMS has no concept of how these URLs should look, since it might not even deal with traditional URLs found in links on websites.

To help you map the URL structure of your project into Mattrbld so your Content Editors can confidently create links to other internal content without having to worry about the specifics, you can define custom URL templates for your Collections. In this article, you’ll learn how they are constructed and what options you have.

Structure

A URL template is a string of characters that can contain dynamic content that is dependent on the content item being linked. These dynamic parts of the string are prefixed with a colon : and terminated by any non-word character other than ., - and _. You also have the option to access specific items in an array, nested object properties and parts of dates using the following syntax:

• Nested properties can be accessed by a period .: some.nested.property

• Items can be retrieved from an array by using brackets [] and the index of the item to retrieve: someArray[0]

• Nested properties and array retrievals can be combined: someArray[0].some.nested.property

• Parts of valid dates can be extracted by using [day], [month] or [year] respectively. Days and months are zero-padded if they are below 10 by default. You can disable this feature by using [_day] and [_month] respectively

All dynamic parts are slugified according to the options set in the project settings, all other parts of the string will be retained as-is, so make sure they’re URL-safe!

Dynamic Parts

The dynamic parts have to correspond to keys in the content item’s Schema. You can query any field in the content item, unless it’s the field with the special key content in Markdown content files.

If the field is marked as localised, Mattrbld will automatically extract the value in the language matching the content. You can override this behaviour by specifying the language you want to retrieve as a nested property, e.g. localisedProperty.en-GB.

Special Dynamic Fields

Unless overwritten by a field with that key in the content item’s Schema, the following fields can be queried in addition to the fields of the content item:

• filename: the name of the file without the extension

• fileExtension: the extension of the file (without a leading .)

• filepath.collection: the path of the file within the content directory of the Collection (e.g. docs/url-templates)

• filepath.content: the path of the file including the content directory of the Collection (e.g. pages/docs/url-templates)

• filepath.full: the full path of the file within the project

Example

You are using Mattrbld to manage content for your personal blog. The SSG you use generates the URLs for your different blog posts based on their title and the date they were published prefixed by “blog”, so for example:

/blog/2021/08/24/hello-world/

To map this structure out as an URL template for your “Blog Posts” Collection in Mattrbld, you’d write it the following way (assuming your Schema stores the title and publishing date in properties with the keys title and date respectively):

/blog/:date[year]/:date[month]/:date[day]/:title/

When linking a blog post from another part of your project, say another blog post, Mattrbld would load the post being linked, extract and slugify the title, as well as the date and assemble the URL.

If instead of the slash you wanted it to end with .html, you’d have to adjust the template as follows:

/blog/:date[year]/:date[month]/:date[day]/:title\.html

Notice how the period is escaped with a backslash? That is to prevent Mattrbld from trying to look up the (likely non-existing) “html” property within the “title” property.

With Collections, file formats Mattrbld supports, and how to write custom URL templates all covered, the final article in the Data Modelling section will be all about multi-language content and the internationalisation features built into Mattrbld.