Assets Introduction

Last updated on June 26, 2024.

Assets are files that an HTTP web server can serve without backend/server processing. They are usually Javascript files, stylesheets (CSS), images, documents (PDF, doc), fonts, or media (audio, video) files.

Note

This document details how assets are stored, managed, and accessed on Insites at the code level. Please visit the Assets documentation for Instances for a complete guide on managing and accessing assets using the Insites Admin.

Assets directory

The directory for assets is:

The directory for assets in a module is:

To correctly communicate with the Insites engine and API, you should organize your codebase into a specific directory structure. The root directory of your project should contain the directory, and you should place assets into the directory inside .

Although only the directory is required, we recommend you further organize your assets into subdirectories inside the directory, e.g. , for Javascript files, for CSS files, etc. This directory structure will be reflected in the codebase created by the command.

Content Delivery Network

Assets are uploaded to a Content Delivery Network (CDN). The CDN directory structure corresponds to the required directory structure of your codebase, except for the beginning of the URL.

Example

Location of the image asset in the codebase:

URL of the image asset on CDN:

URL of the image asset on your vanity domain with no CDN involved (it is slower, a CDN solution is recommended):

Note

CDN host and Instance ID are dynamic and specific to your instance and region.

Busting browser cache

When you use the or filters, paths to files will be suffixed with an parameter and a number (). This number is an epoch timestamp indicating when the file was updated most recently. This mechanism forces the browser to use the newer version from the CDN instead of the locally cached version. This way, you don't have to change the file name every time your content changes. You can, but you don't have to.

The system will not add the parameter to files that do not exist because the server doesn't know when it was last updated, since it doesn't exist.

Accessing assets

You can access assets using three different ways:

  • Accessing assets using the relative path on the CDN
  • Accessing assets using the 'asset_url' liquid filter
  • Accessing assets using the 'asset_path' liquid filter

Accessing assets using the relative path on the CDN

This method is usually used in CSS files to access fonts and images.

Example

Accessing an image in from a CSS file located at :

Accessing assets using the 'asset_url' liquid filter

The Liquid filter returns the absolute URL to the CDN with the parameter.

Example

Accessing a JavaScript file located in from a Liquid file:

File has been found:

File does not exist:

Important

Be careful not to use a leading in your path when using the filter.

Accessing assets using the 'asset_path' liquid filter

The Liquid filter returns a relative path to the Instance domain (no CDN, worse performance for end users) with the parameter.

Example

File has been found:

File does not exist:

Important

Be careful not to use a leading in your path when using the filter.

Accessing assets placed in modules

Assets in modules are namespaced to not conflict with each other. They are also accessed by prefixing the path with the prefix. It does not matter whether you try to access the files from a module or not; the path to the asset is the same. This arrangement means that only the location of the asset file matters, not where you write the code that references it.

Examples

File location:

Asset URL filter access:
Asset path filter access:

Removing assets

Currently, there is no way to remove assets/files from S3. If, for example, you only want one header image out of 6 to be present on the server, you should name the file the same while working on it — this way, the system will override it.

Related topics

Please refer to the following links for related information on Assets:

Have a suggestion for this page?

Didn't quite find what you are looking for or have feedback on how we can make the content better then we would love to hear from you. Please provide us feedback and we will get back to you shortly.