Using Macros to Structure Asset Folders in Crafter CMS

Using Macros to Structure Asset Folders in Crafter CMS


Static assets are media (images, videos, etc.) or any document/binary files which are used in your site. A Crafter CMS site stores all assets under `/static-assets` directory of Studio. To learn more about Crafter CMS Assets, check out this documentation.

If your site is growing, there is a chance that you and your team will need to upload and manage a huge number of assets. Without a well-designed directory structure, this may lead to authoring usability and performance issues.

In this tutorial, we introduce how to use a macro to structure static assets directory. This will help authors upload files to designated folders or even select which folder to upload to without the need of understanding the below form control.

Introducing Macros

Note: “Macro” in this tutorial is defined as Macros for Data Sources, Do not confuse it with the Freemarker macro directive.

Data Sources are pickers that help pull in content from internal or external storage/systems. For example, data sources include desktop video uploaders, desktop image uploaders, and so on. Crafter CMS ships with a number of out-of-the-box data sources and you can also create your own by reading Build a Form Engine Data Source.

While working with Data Sources, Crafter CMS also provides helpful macros which dynamically selects folder paths to store assets. This is convenient for site users to structure static assets while pulling content from internal or external storages.

As of current Crafter CMS version 3.1.x, the following macros are supported by default:

Using Macros

Let’s look at more detail on each macro with some examples of how to use it.

For this tutorial, we create a site from the blueprint “Website Editorial Blueprint” on the Crafter Marketplace. Macros work on any site but we’ll use this blueprint, “Website Editorial Blueprint” because it comes with a default sample Page with macros for reference.

Default Usage from “Website Editorial Blueprint

After you create a new site using “Website Editorial Blueprint”, open Content-Type “Page - Article”.

On Data Source > Upload Images, notice that we have Repository Path with following content: /static-assets/item/images/{yyyy}/{mm}/{dd}/

This is a basic macro usage, any file upload will be saved to /static-assets/item/images/ + uploading date.

When we create a new Page with the type “Page - Article” on 2021/04/20, all images will be uploaded to the following directory: /static-assets/item/images/2021/04/20.

Use Object ID

This macro inserts a Globally Unique Identifier, or GUID (aka UUID). It is convenient if we want to separate asset folders for each Page:

Using /static-assets/page/images/{objectId} for Repository Path:

In the above example, we use`{objectId}` for a 32 characters length string. We can also use shorter versions with only 4 or 2 characters strings.

Use /static-assets/page/images/{objectGroupId} to generate the first 4 characters of a GUID:

Use /static-assets/page/images/{yyyy}/{mm}/{objectGroupId2} to generate the first 2 characters of a GUID. 

Note that we also use a combination of other macros `{yyyy}` and `{mm}`:

Using Parent Path Macro

An interesting macro is {parentPath}, which can be used to insert the parent path of the component/page containing the upload controls. This macro can be used, for example, if we want to structure an assets folder similar to what we have for the Page itself. Let’s say we want to upload assets to a `marketing` folder for marketing pages:

In this case, following Repository Path can be used:


All marketing related assets then will be uploaded to directories under /static-assets/page/images/articles/marketing/....

Multiple Data Sources

Crafter CMS is super flexible. As developers, we can even design multiple data sources to give authors the permission to select a particular folder for storing assets.

Let’s say we need to design a form that authors will upload images for a thumbnail, a mobile version, and a desktop version. In this case, we can have a multiple data source form and each data source can also use the different macro:

Create a sample page:

Then images are uploaded to a different location:


In this tutorial, we explain Macros for Data Sources and provide some example use cases for them. These macros are useful to organize static assets (and other types of content) for Crafter CMS sites. Macros help us build a more structured information architecture which ultimately leads to better CMS usability and performance.

Share This Article :

Phi Nguyen

Phi Nguyen

Phil Nguyen is a member of Customer Success Team at Crafter Software, contributing to the success of Crafter's enterprise customers, open source community users, and certified partners. He also helps with Crafter Cloud DevOps, product roadmap and feature recommendations, and promoting Crafter CMS. Phil has 9 years of software development as a full stack web developer. Before joining Crafter Software, Phil worked as a technical leader at one of the biggest e-commerce companies in Japan and also contributed to the open source Crafter CMS project.