Image Tag HTML Objects

When you are working with images in your templates you will usually be working with an HTML Object. An example scenario would be displaying images for gallery items, store products, collection widgets or content layout images. Pretty much any time you would have an array of image information that array is actually an HTML Object.

The purpose of the HTML Object is to allow you to add or change the attributes for the image tag before outputting the image tag. Instead of having to manually build out the image tag just to set a custom alt text or class value you can set the attribute value and then simply output the image tag. This helps with readability and is often easier to write.

Instead of doing this:

<img src="{{ image.src }}" width="{{ image.width }}" height="{{ image.height }}" alt="My Alt Text">

now you can set the alt text and then simply output the code:

{% set image.alt = 'My Alt Text' %}
{{ image.tag }}

Available image attributes

Typically the following image attributes are available for you to set or change values:

  • alt
  • cdnVersion
  • class
  • height
  • loading
  • src
  • width

'class' and 'alt' may not always have values.

The cdnVersion attribute isn't output in the HTML. It's used to turn on or off CDN versioning for the individual image.

You can also set any valid HTML attribute on the image tag such as 'title' or 'data' attributes.

{% set image.title = 'My image title' %}
{% do image.set('data-custom', 'Data value') %}

See HTML Objects for more information about setting attribute values.

CDN versioning

If you have the CDN enabled then by default images will not have a versioning value added to the image URL. For example, the CDN URL for an image could be like this:

https://cdn.branchcms.com/wBxef4NRL1A-33/images/logo.svg

You may want to add CDN versioning to the file if you want to ensure that the latest version of the image is used with the CDN. With the CDN settings, you can customize the "version" value. Enabling CDN versioning on the image will add that version value before the file extension. For example, if the version value is "3" then the URL for the image could be like this:

https://cdn.branchcms.com/wBxef4NRL1A-33/images/logo.3.svg

There are a few ways to add the CDN versioning to the image.

Using the file_url filter

If you use the file_url filter then the CDN version is automatically added. This applies to images or other file URLs.

{% set image.src = image.src|file_url %}

Use the cdnVersion attribute

The cdnVersion attribute is a boolean value. You can set it to true, false, yes, or no to enable it or disable it.

{# Enable CDN versioning for the individual image #}
{% set image.cdnVersion = true %}
{% set image.cdnVersion = 'true' %}
{% set image.cdnVersion = 'yes' %}
{# Disable CDN versioning for the individual image #}
{% set image.cdnVersion = false %}
{% set image.cdnVersion = 'false' %}
{% set image.cdnVersion = 'no' %}

Use the useCdnVersion function

Instead of setting the cdnVersion attribute directly, you could use the useCdnVersion method to do the same thing.

Enable CDN versioning on the individual image using true, "yes", or no value. 

Disable CDN versioning on the individual image using false or "no".

{# Enable CDN versioning for the individual image #}
{% do image.useCdnVersion() %}
{% do image.useCdnVersion(true) %}
{% do image.useCdnVersion('true') %}
{% do image.useCdnVersion('yes') %}
{# Disable CDN versioning for the individual image #}
{% do image.useCdnVersion(false) %}
{% do image.useCdnVersion('false') %}
{% do image.useCdnVersion('no') %}

After you set the CDN versioning then you would typically output the image.

{% set image.cdnVersion = true %}
{{ image.tag }}

Lazy loading images

For performance reasons, it is recommended to lazy load images that aren't guaranteed to be in the initial viewport. Because this is an important attribute we provide a few ways to set it.

Set the "loading" attribute manually

This is probably the most straightforward method. Simply set the "loading" attribute to equal "lazy".

{% set image.loading = 'lazy' %}
or
{% do image.set('loading', 'lazy') %}

Set the "lazy" attribute to true

A slightly shorter option is to set the "lazy" attribute to true or "yes".

{# These are all equivalent #}
{% set image.lazy = true %}
{% set image.lazy = 'true' %}
{% set image.lazy = 'yes' %}
or
{% do image.set('lazy', true) %}
{% do image.set('lazy', 'true') %}
{% do image.set('lazy', 'yes') %}

You can also remove the loading="lazy" attribute in a similar way.

There are only two values for the image loading attribute

  • eager (the default value if the "loading" attribute doesn't exist)
  • lazy

Since there are only two valid values for the loading attribute, if you set it to false then we remove it.

{# These are all equivalent #}
{% set image.lazy = false %}
{% set image.lazy = 'false' %}
{% set image.lazy = 'no' %}
or
{% do image.set('lazy', false) %}
{% do image.set('lazy', 'false') %}
{% do image.set('lazy', 'no') %}

Use the image lazy() method

This is perhaps the most concise option.

{% do image.lazy() %}

You can pass true or false values if you want to either set or remove the loading="lazy" attribute. However, the "true" values aren't required since if no value is passed then lazy() defaults to true.

{# These are all equivalent #}
{% do image.lazy() %}
{% do image.lazy(true) %}
{% do image.lazy('true') %}
{% do image.lazy('yes') %}
{# These are all equivalent to remove the loading="lazy" attribute #}
{% do image.lazy(false) %}
{% do image.lazy('false') %}
{% do image.lazy('no') %}

After you enable or disable the loading="lazy" attribute then you would typically output the image.

{% do image.lazy() %}
{{ image.tag }}