Template Syntax

Each of the layout, panel, and snippet files in a theme uses variables (also called placeholders) to show external content or content fetched from the database (such as the name of a product).

Template variables are enclosed within %% markers. These types of variables are available for use in templates: global variables, string variables, panel references, snippet references, and file includes.

Global-Variables References

Global variables are used to render dynamic content into a template. Global variables are referenced using the following syntax:

%%GLOBAL_[placeholder_name]%%

For example:

%%GLOBAL_ProductName%%

Specific variables’ availability depends on the layout template that you’re editing. For example, the variable for a product’s description is available on the product details page, but not on the category view/product listing page.

Panel References

Panels are the different blocks used by BigCommerce to build a page. Panels are referenced both inside layout files and inside other panel files.

Panels are referenced in templates as follows, where [panel_name] is a placeholder for the name of a file in the theme’s Panels directory:

%%Panel.[panel_name]%%

For example:

%%Panel.HomeFeaturedProducts%%

This panel reference will load in the content from the Panels/HomeFeaturedProducts.html panel file.

Snippet References

Snippets are templates containing HTML, which you can use multiple times on one page – either by using them in different parts of the template, or by including them a loop. For example, a loop might build a list of products on the page, with each product in the list being a repeated version of the same snippet.

Snippets are referenced in templates as follows:

%%SNIPPET_[snippet_name]%%

In most cases, this will correspond to a similarly named file in the theme’s Snippets directory. For example:

%%SNIPPET_HomeFeaturedProducts%%

This snippet reference will contain repeated copies of Snippets/HomeFeaturedProductsItem.html, one for each featured product to be shown in the list.

Referencing Distributed Theme Assets

After the Blueprint framework was first released, BigCommerce added the ability to reference theme assets that are stored remotely on a CDN (content delivery network). This section provides examples that map first-generation Blueprint syntax to updated syntax for distributed assets.

You can use WebDAV to upload your own custom theme assets (JavaScripts, stylesheets, images, fonts, etc). In your HTML, reference these assets that aren’t present in the base theme using the ASSET syntax:

%%ASSET_[path_to_asset]%%

This syntax will output an absolute URL like:

http://cdn-host/templates/__custom/path_to_asset?t=timestamp`

This loads the custom asset from our CDN server, and includes a cache-busting querystring.

For example:

%%ASSET_Styles/myownstyle.css%%

…will be output as:

http://cdn-host/templates/__custom/Styles/myonwstyle.css?t=123

Syntax Examples

The following tables map earlier to current syntax:

Assets in CSS Files
Previous Syntax Updated Syntax (CDN)
url(/template/images/foo.jpg) url(%%ASSET_images/foo.jpg%%)
url(/templates/__custom/images/foo.jpg) url(%%ASSET_images/foo.jpg%%)
url(/template/foo/bar/font.woff) url(%%ASSET_foo/bar/font.woff%%)
url(../images/foo.jpg) url(%%ASSET_images/foo.jpg%%)
url(icons/foo.ico) url(%%ASSET_Styles/icons/foo.ico%%)
url(//mystore.com/template/images/foo.jpg) url(%%ASSET_images/foo.jpg%%)
Assets in HTML Files
Previous Syntax Updated Syntax (CDN)
<img src="../images/foo.jpg" /> <img src="%%ASSET_images/foo.jpg%%" />
<img src="//mystore.com/template/images/foo.jpg"> <img src="%%ASSET_images/foo.jpg%%" />
<link href="/template/Styles/foo.css" /> <link href="%%ASSET_Styles/foo.css%%" />
<script src="/template/js/foo.js%%"></script> <script src="%%ASSET_js/foo.js%%"></script>
Assets Outside of the /template/ Directory

The ASSET variable can be used only with files and folders inside the /template/ directory. To take advantage of a CDN’s benefits, we strongly recommend moving your assets to the /template/ directory. However, if you need to keep assets outside of the /template/ directory, the best practice is to use protocol-relative, absolute or fully qualified, URLs. Here are some examples:

<img src="//mystore.com/content/images/foo.jpg" />
url(//mystore.com/content/images/foo.jpg")
<link href="//mystore.com/content/foo.css" rel="stylesheet" type="text/css" />

File Includes

You can include another file within a template, using file include variables. This practice is extremely useful for external files such as banners or site-network headers.

Includes are referenced within template files as follows:

%%Include.http://www.example.com/remote_file.html%%
%%Include.https://www.example.com/secure_remote_file.html%%

Notes: Included external links will not follow redirects (http status code 301 or 302). So if a redirect is encountered, it will not include the content.