Image Field & Image Manipulation

Overview

The Image Field is a flexible field for image storage with several configuration options and the ability to manipulate images in code.

Note, images may also be stored in File Fields. One of the advantages to using Image Fields is the display of the image as a preview, as well as data storage options and the ability to store alternative text with the image (see below).

Field Creation Form

During the creation of the field, two options must be set that cannot be changed later. 

The first option that can't be changed later is how the data is stored. The options here control what raw data is stored directly in the Metafield in Shopify. The options are to store the data as an HTML image tag, or to simply store the path to the file. The path to the file is generally more flexible, but storing a complete image tag enables the alternative text field. It's not possible to store alternative text when using the "path to file" option. 

The second option that can't be changed later is the Repeat option. This option changes the underlying field in Shopify to store the data in JSON rather than in simple text.

Content Entry Form

The screenshot below shows content entry when the field is not repeatable and is using the image tag storage option. 

The screenshot below shows the content entry form when the field is repeatable and is using the image tag storage option. Note the "reorder" option on the right.

Repeatable

As mentioned above, this field can be set to repeatable, but the option must be selected during field creation.

File Storage 

Image files are usually stored in a separate theme in your Shopify store with the name "Custom Fields Assets". The app stores images there so that stores can safely change themes without losing Custom Fields images. This presents an issue though, since it's not possible to use Shopify image filters on files outside of the current theme. See Image Manipulation below for a workaround.

Some stores may choose to save files in an Amazon S3 bucket through the app, in which case the asset theme would not be used and image manipulation described below would not work. In that case, a developer could use image manipulation built into Amazon AWS.

Image Manipulation & Image Display Settings

It is often desirable for images to be rendered at specific sizes or with other automatic adjustments. Usually this is done in themes using Shopify's img_url filter described in this article.

All img_url filters are available when storing images in Custom Fields. The filters are simply called in code a different way. 

The app includes a built-in tool to write the specific code needed to manipulate images. To use the tool, navigate to the Code page for any field and generate a template. Once the template has been generated, a new interface appears.

When the form is used, the code below it is automatically updated to use the settings with the proper syntax.

Heads Up!

The form respects your customizations. If you've changed the default template code in any way, changing form settings will not change the code your custom code. You may want to generate the template in a separate theme or save customizations and reset the template to the original if you'd like to use the form and have made customizations to the template.

Tips for working with cf-image.liquid

The cf-image.liquid file acts as a translator to allow themes to use Shopify's image filters. 

You can pass in an image URL or an <img> tag. Note that image URLs that do not use Shopify's CDN will not be able to use the crop/size/scale/format modifiers.

Example: Print an image tag with alt and class attributes.

{% render 'cf-image' with image: IMAGE, tag_alt: "My alt text", tag_class: "my-image-class" %}

Example: Print a modified image that is cropped and scaled.

{% render 'cf-image' with image: IMAGE, size: "400x100", crop: "top", format: 'pjpg', scale: 2, tag_alt: "My alt text", tag_class: "my-image-class" %}

The "cf-image" snippet accepts the following parameters:

  • image: The image URL or an image tag. Can be provided from a metafield value.
  • size: Size dimensions, such as 100x100, x200, or 300x.
  • crop: Accepts top, center, bottom, left, and right.
  • scale: Either 2 or 3.
  • format: Accepts jpg or pjpg (for a progressive jpeg image)
  • print: Defaults to "tag". Accepts url, tag, or none. Setting to "none" will not render anything automatically (see below).
  • tag_alt: Alt text for the image tag.
  • tag_class: CSS class for the image tag.

Setting the path as a variable rather than printing

To use the image tag or url without printing it automatically, include the print parameter set to none:

{% render 'cf-image' with image: IMAGE, print: "none", size: "1920x1080", crop: "center" %}

This will set the variable cf_image to the image URL.

<div style="background-image:url('{{ cf_image }}');"</div>

Problems Loading the cf-image.liquid Snippet

If you see an error in your template such as Liquid error: Could not find asset snippets/cf-image.liquid your theme may be missing the file. You can find the latest version of the file here. Simply copy the code and paste into a new theme snippet call cf-image.liquid.