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}}" title="{{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" title="{{alt text}}">
Method one: Edit Your BigCommerce Theme
For the purpose of 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
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
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 simply define custom CDN endpoints to use 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 that it creates. This filtering circumvents the 50 MB size limit on the resulting .zip file.
Read more about how 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 in order 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 pretty verbose. With ImageEngine this will be dramatically simplified. You can make use of any of the lazy loading features and LQIP (low-quality image placeholders) built into the theme if you want. However, in this example, we’ll simplify and focus on the image references. Feel free to build out with 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.
Click the “Save and Apply” button in the bottom right corner to save the changes.
At this point, 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">
4. Further enhancements
The next template listed above, product-view.html, is a good place to talk about 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 that you remove it entirely, this is because getImageSrcset returns a long string which doesn’t allow individual image sources to be prefixed. You can still use getImageSrcset when requesting one image size such as the example demonstrated above.
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 category listings, shopping carts, and other relevant templates in your theme.
4.1 Setting the size of the images
It is also a good idea to try to define an image size in the markup. This is not straightforward in all themes. Default sizes may be defined in the site settings (config.json). If you have a setting that is used to define sizes on product thumbnails, say productview_thumb_size_px: 200, you can set the fallback size, and an additional sizes attribute to make use of 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.
4.2 Add 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">
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
3) Wrapping up: Apply the Theme Changes
If you did the changes offline, then after you have changed all the image references, you need to activate the theme with the changes on your site.
Image: Bigcommerce Image CDN ImageEngine Enable
Do so by clicking the three horizontal dots menu and click Apply.
Once applied, check your site and make sure 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 that will serve all images through ImageEngine.
1) Create the Script in the Script Manager
-
Log on to BigCommerce Admin Panel
-
From the left hand menu, navigate to Storefront > Script Manager > Create a Script
-
Click the “Create New Script” button.
-
Fill in the fields as shown in the screenshot below
-
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>
- If you already use JQuery in your theme, you can remove the first line that references jquery.
- Depending on your theme, you may need to edit the selectors in the main script
-
Double-check that you’ve updated the variable
var imageEnginecdn = "example.cdn.imgeng.in";
to use your unique ImageEngine delivery address. -
Click the “Save” button.
3) 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.
Note again that the sample script above might not address some image urls. You may need to customize the selectors in the JavaScript.
Comments
0 comments
Please sign in to leave a comment.