Content Images Part 1

I defined "content" images as those images that are actually part of a BigCommerce store's data/storage, not a part of your theme assets. This includes images uploaded and attached to your products or categories, those used in content like web pages or Page Builder widgets, and even images directly uploaded to file storage using WebDAV.

Stencil supports custom helpers for referencing such images. Unlike with the cdn helper, these assets are always fetched directly from BigCommerce storage even in your local environment (though in that case they are proxied through the local server); the images must already be uploaded before you can use them in development.

Also uniquely, the URL patterns for content images support dynamic resizing - a feature that is used in Cornerstone for a responsive image strategy that ensures efficient page performance. We'll look at that URL pattern before we dive into the appropriate Handlebars helpers.

Dynamic Resizing

To follow along in your own store as we experiment with content image URLs, browse to your live store and find a content image. An image inserted into a web page or a Page Builder widget would mirror the URL paths we're going to look at most closely, but even a product or category image will do. Inspect the image for the src URL and browse to the image directly. Here's my example, found on my own store:

https://cdn11.bigcommerce.com/s-rc5p4ehzja/images/stencil/original/image-manager/ostrich.jpg

The image you've inspected on your own store should follow a similar pattern.

https://{cdn-domain}/{store-id}/images/stencil/{size}/{relative-path}

The {size} segment in the above pattern can be manipulated to instruct the CDN to resize the image served in the response. (The particular URL you picked out from your store might have a different value in this segment than mine did.) The possible formats include those represented by the following examples:

• original - The image retains its original size.
• 300w - The image is resized to the given width. The height is resized to maintain the original dimension ratio.
• 300x100 - The image is resized according to the width and height constraints ("{width}x{height}"). The original dimension ratio is retained, so if the given dimensions don't match the ratio of the image, it will be resized so that neither final dimension exceeds the given constraint.

Give these formats a try with your chosen image URL and observe the results.

On your local Stencil CLI environment, the same relative URL paths (minus the store ID) should resolve successfully on your localhost domain.

http://localhost:3000/images/stencil/original/image-manager/ostrich.jpg

Such images should still be sourced from the CDN but appear to be proxied through the local server.

getImageManagerImage

We're going to examine two different Handlebars helpers used to inject content images, and to understand the difference between the two, it's necessary to understand the different sources they are designed to work with.

The Image Manager is the pool of content images uploaded in your BigCommerce admin, in various WYSIWYG editor contexts. In your admin, if you browse to Storefront > Image Manager, you'll find the interface for directly managing this pool of images. You can upload new images here, but note that images uploaded in various places - the web page or blog WYSIWYG editor or the Page Builder - will be part of this same pool. (Images attached to products, categories and brands are handled differently.)

The getImageManagerImage helper can be used to inject the URL for one of these images. Simply provide it the filename as a parameter:

<img src="{{getImageManagerImage 'ostrich.jpg'}}" />

The example above would result in an absolute URL path in your local environment, but a fully qualified CDN URL in production. With no further parameters, the size segment of the URL will simply be "original".

The named width and height parameters, if passed to the helper, will result in a dynamic resize URL. If only width is provided, a size identifier like "300w" will be included, while specifying both width and height will result in a string like "300x100".

<img 
    src="{{getImageManagerImage 'ostrich.jpg' width=300 height=200}}" 
/>

The above example, in my own store, results in an image resized to 296 pixels wide and 200 high based on the "300x200" constraint.

getContentImage

Another option you have for managing images and other file assets in your BigCommerce store is via a WebDAV client. You can find WebDAV connection information in Settings > Advanced > File access (WebDAV).

If you connect to your BigCommerce storage via a WebDAV client, you'll have access to a number of different directories that serve different purposes. The content directory, specifically, is reserved for asset files that will be publicly available via a URL like https://{my-site}/content/{filename}. Images in content can also be served through the CDN with the right relative path.

Any image in the content directory of your WebDAV storage can be used in your Stencil theme with the getContentImage helper. This helper works in the same way, and supports the same parameters, as the getImageManagerImage helper.

<img 
    src="{{getContentImage 'samurai.png' width=300 height=200}}" 
/>

Practical Use Cases

If you try searching in Cornerstone, you won't find any existing examples of getImageManagerImage and getContentImage. This isn't entirely surprising, because Cornerstone could hardly be aware of specific files present in your store's Image Manager or WebDAV storage. You're usually going to find that ad-hoc content image references aren't appropriate to be tied directly to your themes.

There are, however, ways to make use of these helpers in combination with theme settings to achieve customizable theme assets. If there's a particular image used in your theme that would be useful for store owners to update, you might try creating a simple text theme setting for the filename of an image stored in Image Manager or WebDAV, then pass that setting's value in as the first parameter of getImageManagerImage or getContentImage. (There is currently no schema type allowing the direct selection of Image Manager or WebDAV images in Page Builder.)

Regardless of the possible use cases for these helpers, our examination of dynamic resizing is highly relevant to our next topic - the getImage helper.