Skip to main content

BigCommerce

Jonathan Nyborg
  • Updated

This article will demonstrate how to use ImageEngine with BigCommerce. The best way to configure ImageEngine in front of Akamai Image Manager is to edit the templates. This may be done in the BigCommerce admin interface. We also provide a JavaScript-based method to be used as an alternative. 

 

Links to specific sections:

 

To implement ImageEngine’s image optimization for BigCommerce, you will first need to sign up for an ImageEngine account, if you do not already have one. During the signup process, you’ll be asked for the website domain where you intend to use ImageEngine and origin URL for the majority of the images. For more information about signing up, please refer to this article: Getting Started: Signup.
Once signed up, you will be issued a unique delivery address following this pattern: “aabbcc.cdn.imgeng.in.” Custom delivery addresses may also be made after the initial signup process is complete. For more information, see our article here: Creating new delivery addresses

 Take note of your delivery address, as we will be needing it in the following guide.

Overview

If you have your ImageEngine address ready, the theme files referencing images must be changed. The ImageEngine address must prefix all image urls generated by BigCommerce. Typically, an image tag in the template may look like this:

<img src="//<your-unique-id>.cdn.imgeng.in/{{getImageSrcset image 1x=(default fallback_size '1080w')}}" alt="{{image.alt}}">


This will make the image urls look like this:

<img src="//<your-unique-id>.cdn.imgeng.in/https://cdn11.bigcommerce.com/path/img.jpg" alt="alt text">

 

Method one: Edit Your BigCommerce Theme

For this guide, we’ll be using one of the default themes that are available in BigCommerce: Cornerstone.

If you’re using a different theme, or a custom theme, the theme files you’ll be editing (and their contents) may be different.

The key takeaway is how to change the image references - the <img src=""> tag. This is the same procedure regardless of themes and files.

1. Make a Copy of the BigCommerce Theme

First, log on to your BigCommerce account.

From the left-hand menu, go to “Storefront” -> “My themes” and make a copy of the currently active theme under the 'Advanced" drop-down menu.

Image: BigCommerce Image CDN ImageEngine copy theme files

1-copy-bc-theme.png

Once the theme is copied, it is listed under “My themes” on the same page (you may Apply the theme again now if you want to do the changes on the “live” site).

 

2. Edit the Theme Stencil Files

The basic change needed to integrate ImageEngine is only to prefix any image url with the ImageEngine delivery address.

Next, click “Edit Theme Files.”

Image: Bigcommerce Image CDN ImageEngine Edit theme stencil with ImageEngine delivery address

2-edit-theme.png

Now you’re looking at the Stencil file editor. It looks like a file explorer window and different files are organized in folders. How files are organized in this view depends on your theme.

You can also choose to download the theme files, do the changes locally, and then upload the theme again.

 

3. Editorial Images

Editorial images, such as those used in blog posts, are not served by Akamai ImageManager and are much easier to optimize with ImageEngine. This method works regardless of the theme.

In BigCommerce, you can define custom CDN endpoints with the CDN Handlebars helper.

In your theme’s config.json file,  add the custom CDN endpoint below:

 

{
"name": "Cornerstone",
"version": "1.3.5",
"settings": {
"homepage_new_products_count": 12,
"homepage_featured_products_count": 8,
"cdn": {
"customcdn": "<your-unique-id>.cdn.imgeng.in"
}
}
}

After defining an endpoint, you can use the short name in the same way as you would use a WebDAV: abbreviation:

<img src="{{cdn 'customcdn:img/image.jpg'}}" />

 

In local development, that helper would return:

<img src="/assets/cdn/customcdn/img/image.jpg" />

 

Whereas in production, it would return:

<img src="https://<your-unique-id>.cdn.imgeng.in/img/image.jpg" />

 

As highlighted above, the helper is configured to rewrite local URLs to an assets/cdn/ subfolder. The stencil bundle command will exclude the local assets/cdn/ subfolder from the bundle it creates. This filtering circumvents the 50 MB size limit on the resulting .zip file.

You can read more about handlebar helpers to integrate ImageEngine and BigCommerce on developer.bigcommerce.com.

 

4. Product Images

In the case of the Cornerstone theme, we will need to edit these files to update the image references for product images:

  • templates > components > common > responsive-img.html
  • templates > components > products > product-view.html

The procedure is the same for all template files with product images, so we’ll focus on responsive-img.html. In Cornerstone, this template is responsible for displaying most of the images.

The default content of the file is lengthy. With ImageEngine, this will be dramatically simplified. You can use lazy loading features and LQIP (low-quality image placeholders) built into the theme. However, in this example, we’ll simplify and focus on the image references. Feel free to build out additional features.

 

Take note of {{getImageSrcset}} and {{image.alt}}. We’ll need these parts in the updated image tag.

 

Next, replace all content in the template with this:

<img src="//<your-unique-id>.cdn.imgeng.in/{{getImageSrcset image 1x=(default fallback_size '1080w')}}" alt="{{image.alt}}" title="{{image.alt}}">

 

Replace <your-unique-id>.cdn.imgeng.in with the ImageEngine delivery address obtained above.

Since the resulting URL string will be prefixing the Original URL with the delivery address, ensure the `Allow Prefixing` option for your Engine's Delivery Address is enabled. Instructions for enabling this in the ImageEngine Control Panel may be found here: Engine Settings - Enable Prefixing

Click the “Save and Apply” button in the bottom right corner to save the changes.

All images rendered with the responsive-img.html, like the hero images in the carousel in the Cornerstone theme, are now served through ImageEngine. You’ll notice that the image tag looks something like this if you view the source of the page:

<img src="//<your-unique-id>.cdn.imgeng.in/https://cdn11.bigcommerce.com/s-owncnz90jw/images/stencil/1280w/image.jpg?c=1" alt="alt text" title="alt text">

 

5. Further enhancements

The next template listed above, product-view.html, is a good place to discuss changes that need to happen in all templates referencing images. Where and how many templates this is, depends on your theme. A tip is to go through templates and look for {{getImage ...}} references or {{getImageSrcset this use_default_sizes=true}}

To handle {{getImage ...}} prefix it with the ImageEngine delivery address: //<your-unique-id>.cdn.imgeng.in/{{getImage ... }}. Then ImageEngine will serve the images.

For references similar to {{getImageSrcset this use_default_sizes=true}}, it is recommended to remove it entirely because getImageSrcset returns a long string that doesn’t allow individual image sources to be prefixed. You can still use getImageSrcset when requesting one image size, such as in the above example.

More specifically, in product-view.html, you want to change (or prefix) these variables using {{getImageSrcset}} with your ImageEngine delivery address:

  • data-zoom-image
  • data-image-gallery-new-image-url
  • data-image-gallery-zoom-image-url

Remove entirely because it outputs the entire string of the srcset:

  • data-image-gallery-new-image-srcset

Look through all templates displaying images and look for similar references.

Double-check templates for your theme's category listings, shopping carts, and other relevant templates.

 

5.1. Setting the size of the images

Defining an image size in the markup is also a good idea. Default sizes may be defined in the site settings (config.json). If you have a setting that defines sizes on product thumbnails, say productview_thumb_size_px: 200, you can set the fallback size, and an additional sizes attribute to use ImageEngine’s Client Hints support.

{{> components/common/responsive-img
image=product.main_image
fallback_size= theme_settings.productview_thumb_size
width=theme_settings.productview_thumb_size_px
img_compression=70
}}


To make use of width you’ll have to update responsive-img.html by adding this attribute to the image tag: width="{{width}}". The img_compression example above shows how you can pass values to ImageEngines directives. This is an example of a custom compression level. To make use of the snippet above, the tag must be updated to :

<img src="//<your-unique-id>.cdn.imgeng.in/w_auto,{{width}/cmpr_{{img_compression}}/{{getImageSrcset image 1x=(default fallback_size '1080w')}}">

 

You can use the same method to make use of all ImageEngine directives.

Unfortunately, there is no way to enable client hints for image optimization in BigCommerce.

 

5.2. Add Client Hints and Resource Hint

To make the browser connect to ImageEngine as soon as possible, add this line inside the <head> element on the site:

<link rel="preconnect" href="//<your-unique-id>.imgeng.in">

To enable Client Hints support, this meta tag must be added inside the <head> element:

<meta http-equiv="delegate-ch" 
content="sec-ch-dpr https://<your-unique-id>.imgeng.in; 
content="ch-viewport-width https://<your-unique-id>.imgeng.in; 
content="ch-width https://<your-unique-id>.imgeng.in; 
content="ect https://<your-unique-id>.imgeng.in;">

Again, depending on your theme, you’ll need to find where the <head> content is defined. In the case of the Cornerstone theme, it is located in templates > layouts > base.html

 

6. Wrapping up: Apply the Theme Changes

If you did the changes offline, you need to activate the theme with the changes on your site after you have changed all the image references.

Image: Bigcommerce Image CDN ImageEngine Enable

4-applytheme.png

Do so by clicking the three horizontal dots menu and `Apply`.

Once applied, please check your site and ensure image URLs are prefixed with the ImageEngine delivery address.

 

 

Method two: Alternative JavaScript implementation

If changing template files is not an option for your site, ImageEngine can also be implemented using the Script Manager in BigCommerce. 

Although BigCommerce has a flexible template system, a JavaScript-based implementation of ImageEngine may be beneficial both from an implementation and performance perspective. This guide will demonstrate how to implement JavaScript to serve all images through ImageEngine.

 

1. Create the Script in the Script Manager

  1. Log on to BigCommerce Admin Panel

  2. From the left-hand menu, navigate to Storefront > Script Manager > Create a Script

  3. Click the “Create New Script” button.

  4. Fill in the fields as shown in the screenshot below


  5. Paste this script into the “Script contents” box:

    <script src="https://ajax.googleapis.com/ajax/libs/jquery/3.5.1/jquery.min.js"></script> 

<script>
/* 
Change this variable to use your unique ImageEngine Delivery Address
*/ 
var imageEnginecdn = "​example.cdn.imgeng.in​";

$(function(){$(".productView-img-container").hover(function(){var i=(i=$(".easyzoom-flyout img").attr("src")).replace("cdn11.bigcommerce.com",imageEnginecdn);$(".easyzoom-flyout img").attr("src",i)}),$(".productView-img-container .easyzoom-flyout").remove(),$(".productView-img-container img").removeAttr("srcset"),$(".productView-img-container img").removeAttr("data-srcset"),$(".card-img-container img").removeAttr("srcset"),$(".card-img-container img").removeAttr("data-srcset"),$(".productView-images img").removeAttr("srcset"),$(".productView-images img").removeAttr("data-srcset"),$(".card").each(function(){var i=(i=$(".card-img-container img",this).attr("src")).replace("cdn11.bigcommerce.com",imageEnginecdn);$(".card-img-container img",this).attr("src",i)}),$(".productView-thumbnails li").each(function(){var i=(i=$(".productView-thumbnail-link img",this).attr("src")).replace("cdn11.bigcommerce.com",imageEnginecdn);$(".productView-thumbnail-link img",this).attr("src",i)});var i=(i=$(".productView-img-container img",this).attr("src")).replace("cdn11.bigcommerce.com",imageEnginecdn);$(".productView-img-container img",this).attr("src",i)}),$(document).ready(function(){$(".card-img-container img").show(),$(".productView-images img").show()});
</script>
    • You can remove the first line referencing jquery if you already use JQuery in your theme.
    • Depending on your theme, you may need to edit the selectors in the main script

  6. Double-check that you’ve updated the variable var imageEnginecdn = "​example.cdn.imgeng.in​"; to use your unique ImageEngine delivery address.

  7. Click the “Save” button.

2. Check your Site

Visit the storefront on a product page and verify that images are loaded through ImageEngine. Look inside the <head> on the markup and verify that the newly added script is there.

How to Inspect Images to verify ImageEngine Optimization

Note that the sample script above might not address some image urls. You may need to customize the selectors in the JavaScript.

Related articles

Comments

0 comments

Please sign in to leave a comment.