Referencing Assets in a Theme (Blueprint)

What We'll Cover

The template assets only apply to Blueprint Themes and requires familiarity with code.
Don't feel comfortable adjusting your design or want to work with an expert? Check out our BigCommerce approved agencies or our Community. Due to our Design Policy, our Techincal Support is unable to edit code or make design changes.

If you are a developer or make customizations to your store, you will probably be using asset files such as images, stylesheets, javascript, or other multimedia assets. The way you need to reference these in your code will differ slightly depending on where the files are stored. 

Assets can be stored in three locations, accessible through WebDAV:

  • template folder — uses the CDN (recommended)
  • product_images/uploaded_images folder — corresponds to the Image Manager in the Control Panel
  • content folder — used for PDFs and other non-design files

Only the template folder uses the CDN. We therefore recommend storing all static assets in the template folder.

For more information and examples, visit our Template Syntax on the Developer Portal.

Template Assets

We recommend all assets (with the exceptions listed above) be stored in the template folder or the appropriate subfolder. You can then reference these assets with the following format: %%ASSET_[path-to-your-asset]%%

The %%ASSET_[path-to-your-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/image.jpg%%" /> (HTML)
or
background-image: url(%%ASSET_images/image.jpg%%); (CSS)

Here's a breakdown of what's happening in this reference:

  • INPUT: %%ASSET_images/image.jpg%%
  • OUTPUT: http://cdn-host/templates/__custom/images/image.jpg?t=12345
  •  
  • CDN URL — the URL of the asset on the CDN
  • Time stamp ("cache buster") — the record of which version of the asset is being used; ensures your customers see the most recent version of your assets

Using %%ASSET_[path-to-your-asset]%% means you don't need to change the reference every time you make a change to the file, but can still utilize the benefits of the CDN.

For more details and examples, see our Template Syntax documentation.

Other Assets

If you need to keep assets in folders outside of /template/, the best practice is to use fully qualified URLs:

<img src="//yourstore.com/content/image.jpg" />

<img src="//yourstore.com/product_images/uploaded_images/image.jpg" />

Images in the Image Manager will have a CDN URL. You can locate this URL by viewing it in its own window or tab.

<img src="//cdn-host/templates/__custom/Styles/myownstyle.css?t=12345" />

Was this article helpful?