Skip to main content

774 Messages


184.8K Points

Fri, Jun 6, 2014 8:24 PM


Referencing Assets in a Theme

In May 2014, Bigcommerce stores will have their theme files moved to the Bigcommerce CDN. The Bigcommerce CDN decreases page loading time, which is crucial to your store's success. Product images and videos are already hosted on the CDN, so now all your theme’s files will get the same conversion and SEO benefits. Learn more about the CDN.
What is a Content Delivery Network?
A content delivery network (CDN) is a system that copies, or “caches”, designated images and files to many different data centres around the world. Instead of loading these files from our main data centres in Texas, they are loaded from the data centre that is closest to where your customer is viewing from. Whether you are based in the United States, Australia, or anywhere in between, your store will load equally quickly for you and your customers.

Quicker Loading = Quicker Buying
Page load times are critical to your store's conversion rate. The longer a page takes to load, the more likely your customers are to leave. Our blog can give you the statistics, but even a 1 second delay decreases customer satisfaction by 16%.

So what's actually changing?
Currently, you can customize the look and feel of a theme by changing assets such as images, css, javascript or other multimedia. In May 2014, we’ll begin caching all theme assets stored in the /template/ folder on our Content Delivery Network (CDN).

Do I need to do anything?
If you are a developer or do customizations to your store, you will need to change how you reference and store static asset files such as images, css, javascript, or other multimedia assets.

Before the CDN migration, assets could be stored in a few different areas on the server (/content, /template, Image Manager) and looked like this in the HTML:

<img src=”/templates/__custom/images/cat.jpg” />

<img src=”/content/cat.jpg” />

<img src=”/product_images/uploaded_images/cat.jpg” /> (Image Manager Path)

These static images will not be cached on the CDN.

To ensure that assets can be cached on the CDN, you'll have to:

  1. Place all assets in the /template folder via WebDav. See this article

  2. Add a small code snippet before the asset when referenced in HTML or style sheets: %%ASSET_path-to-your-asset%%

ASSET_ variable replaces the path of the /template/ folder. So if you put an image in /template/images, you would now reference the image with:

<img src="%%ASSET_images/cat.jpg%%" />

The ASSET_ variable contains the CDN URL (http://cdn-host/server_hash/template/). So your asset in the example above would be rendered as http://cdn-host/server_hash/template/.... Once this asset has been cached, it will load lightning fast on your store-front. That’s less waiting time for your customers!

You'll also notice that we record when a file has been changed with a timestamp on the URL(cache busting). The ASSET_ variable will add ?t=############ to the end of the URL. This timestamp will be updated every time you change the assets but keep the same file name. The timestamp will ensure that your customers see the most recent version of your assets. Without this feature, your customers may not be able to see the changes you’ve made to the assets.

Output Example:


After update to social.css file


Syntax Examples
Example 1: Absolute path

/template/ is alias (as shown in webdav) to /templates/__custom/

Before (using old syntax)
After (using CDN asset syntax)

url(/template/images/foo.jpg) url(/templates/__custom/images/foo.jpg) url(/template/foo/bar/font.woff)
url(%%ASSET_images/foo.jpg%%) url(%%ASSET_images/foo.jpg%%) url(%%ASSET_foo/bar/font.woff%%)

Example 2: Relative path

If stylesheet in /template/Styles/

url(../images/foo.jpg) url(../foo/bar/font.woff) url(icons/foo.ico)
url(%%ASSET_images/foo.jpg%%) url(%%ASSET_foo/bar/font.woff%%) url(%%ASSET_Styles/icons/foo.ico%%)

HTML reference asset in /template/images/

<img src="../images/foo.jpg” />
<img src="%%ASSET_images/foo.jpg%%" />

If stylesheet in /template/foo/bar/

url(../images/foo.jpg) url(../../images/foo.jpg) url(icons/foo.ico)
url(%%ASSET_foo/images/foo.jpg%%) url(%%ASSET_images/foo.jpg%%) url(%%ASSET_foo/bar/icons/foo.icon%%)

HTML reference in /template/foo/bar/

<img src="../images/foo.jpg” /> <img src="../../images/foo.jpg” />
<img src="%%ASSET_foo/images/foo.jpg%%" /> <img src="%%ASSET_/images/foo.jpg%%" />

Example 3: Fully qualified URL

url( url(
url(%%ASSET_images/foo.jpg%%) url(%%ASSET_custom/font/foo.woff%%)

HTML reference in /template/foo/bar/

<img src="” />
<img src="%%ASSET_/images/foo.jpg%%" />

Example 4: CSS Reference

<link rel="stylesheet" href="%%ASSET_Styles/mycss.css%%" />

What about assets I store outside the /template folder?
At this time the ASSET_ variable can only be used with folders and files in the /template/ folder. To take advantage of the CDN benefits, we strongly recommend moving your assets to this folder. If you need to keep assets in folders outside of /template/, the best practice is to use fully qualified URLs such as:

<img src=”http(s)://” />

<img src=” http(s):// /product_images/uploaded_images/cat.jpg” /> (Image Manager Path)

When using the absolute path it is important to know when to use http vs https. Where possible use the http version as it will produce better site performance because it does not have to pass through encryption. HTTPS should be used in all header and footer asset references or for any elements that will also show up on secure pages i.e. Checkout, sign-up, sign in, etc.

In some instances the system will generate a CDN URL for assets in folders outside /template. If you use these URLs and later update the asset, your customers may not see the updated version until the cache expires. Use the fully qualified store URL as mentioned above to avoid this scenario.

This conversation is no longer open for comments or replies and is no longer visible to community members.


No Responses!