Accentuate Custom Fields
  • Welcome!
  • Introduction
    • Getting started with ACF
    • Field scopes
    • How to show fields in your storefront
  • Dashboard
    • Reference Manager
      • Creating a new reference within Reference Manager
    • Filter & Group
      • Filter editor
      • Filter usage
    • Activity log
    • App settings
  • Field Definitions
    • Fields & Sections
    • Deciding on a field type
    • ACF Field types
      • Text
      • Markdown text
      • HTML
      • Checkbox
      • Selection
      • Tags
      • Number
      • Date
      • Color
      • Media v1 (legacy)
      • Media v2
      • Custom Object (JSON)
      • Multi-language Text
      • Reference fields
      • References to Global fields
    • Shopify Field types
      • Shopify » Single line text
      • Shopify » Multi-line text
      • Shopify » Boolean
      • Shopify » Color
      • Shopify » Custom objects (JSON)
      • Shopify » URL
      • Shopify » Date
      • Shopify » Date and Time
      • Shopify » Integer
      • Shopify » Decimal
      • Shopify » Weight
      • Shopify » Volume
      • Shopify » Dimensions
      • Shopify » Reference fields
    • Automatic tagging
    • Large sets
    • Field contexts
    • Field context filters
    • Copy and paste fields
    • Change field name and type
    • Import existing fields
    • Linking multiple stores
  • The Editor
    • Using the editor
    • Promote fields to sidebar
    • Layouts
    • Hide from search
    • Repeatable fields
    • Version control
    • Update value on order creation
  • Bulk Import & Export
    • Export custom field values
    • Import custom field values
    • Metaobject export / import
  • METAOBJECTS
    • What are Metaobjects?
    • Metaobject Definitions
    • Metaobject instances / values
    • Displaying Metaobjects on your storefront
    • Metaobject export / import
  • THEME EXTENSIONS
    • SEO keywords
    • Sticky promo bar
    • Products promotion
  • Liquid Guides
    • Learning Liquid
    • Resize & crop images
    • Check for empty values
    • Access field definitions
    • Order notifications
    • Allow customers to change their field values
  • OTHER
    • Webhooks
    • API
      • Access to custom fields
      • Endpoints
  • Help
    • FAQ
      • Why are one of my products no longer showing in my reference field?
      • I have multiple products/variants with the same name
      • How do I make changes to my field values in bulk?
      • I added a new field definition but it is not showing in my storefront
      • How do I copy my field setup to another store?
      • My fields are still showing after I have deleted their field definition
      • Why are none of my fields showing in the editor?
      • My newly created object in Shopify is not available in ACF
      • Reference lists are empty?
      • Why am I seeing a "value cannot exceed 100,000 characters" error when saving?
      • Why can't I name my field "first", "last" or "size"?
    • Need help?
  • Product
    • Changelog
    • Feedback & Suggestions
Powered by GitBook
On this page
  • Multiple selections
  • Variant reference fields
  • File reference fields
  • Resource reference fields
  • Media reference fields
  1. Field Definitions
  2. ACF Field types

Reference fields

PreviousMulti-language TextNextReferences to Global fields

Last updated 10 months ago

A reference type custom field is a specialized version of a 'Selection' type which will list all available objects of its type:

The values shown specifically for product and variant selections can be customized to show additional information, making it easier to search and filter for the correct items.

You can find the available options in your settings in the admin side menu

Once a value is selected, the Metafield will contain the referenced Shopify object's handle as its value (see special cases for file, resource, and variant reference fields below). You can use this handle as a reference to a Shopify object via a Liquid global object depending on the type.

{{ blogs[product.metafields.accentuate.related_blog].title }}  
{{ articles[product.metafields.accentuate.related_article].title }}  
{{ pages[product.metafields.accentuate.related_page].title }}  
{{ collections[product.metafields.accentuate.related_collection].title }}  
{{ all_products[product.metafields.accentuate.related_product].title }}  
{{ linklists[product.metafields.accentuate.related_linklist].links }}

Shopify global objects only return values for published products, collections, pages, etc. Be sure to check if the returned object is valid in case the reference suddenly points to a deleted or archived object.

Shopify imposes a restriction on how many calls to "all_products" you can make from a single Liquid page. This is currently set to 20 unique handles per page

Using reference types, we can also get the Metafields from the referenced objects using the handle. This is just as easy as getting the URL or title as shown above.

{{ all_products[product.metafields.accentuate.related_product].metafields.accentuate.isbn }}

Multiple selections

As is the case for the basic type 'Selection', if you have opted for multiple selections for your reference type, each object's handle is listed with the "pipe" symbol ("|") as a separator token. You can use Liquid's 'split' filter on the Metafield to separate the handles - like this:

{% assign selected_handles = product.metafields.accentuate.selection | split: '|' %}
{% for selected_handle in selected_handles %}
  <p><a href="{{ all_products[selected_handle].url }}">{{ all_products[selected_handle].title }}</a></p>
{% endfor %}

Variant reference fields

In Shopify, individual product variants don't have handles, so we need to rely on the product's handle combined with the id of the referenced variant. Therefore variant references are stored as product_handle:variant_id for easy access to both the product object and the underlying variant, like this:

{% assign product_handle = product.metafields.accentuate.referenced_variant | split: ':' | first %}
{% assign variant_id = product.metafields.accentuate.referenced_variant | split: ':' | last | plus: 0 %}

{% assign referenced_product = all_products[product_handle] %}
{% assign referenced_variant = referenced_product.variants | where: "id", variant_id | first %}

<p>The referenced variant is {{ referenced_product.title }} {{ referenced_variant.title }}</p>

Note the use of the Liquid filter "plus: 0" which converts a string to a number for use in the "where" filter.

Variant references cannot successfully be transferred to other stores due to the use of internal Shopify ids, which will vary across stores. Shopify does not offer a way to uniquely identify a specific product variant across store boundaries

File reference fields

{% assign url = product.metafields.accentuate.referenced_file | file_url %}
<a href="{{ url }}">Click to download</a>
{{ assign image = images[product.metafields.accentuate.referenced_file] }}

Resource reference fields

Using a Resource reference field, you can reference any of the following Shopify objects: collections, products, pages, blogs, or articles. A resource reference is stored as a partial URL to the selected resource - like /products/example or /pages/contact, so you may redirect your visitor to the relevant page using links, buttons, etc.:

{% assign url = product.metafields.accentuate.referenced_resource %}
<a href="{{ url }}">Please see here</a>

Media reference fields

Media references don't contain references to Shopify objects such as products and collections. Instead, they contain internal references to ACF Media v2 type field values defined under either the "shop" or "globals" scope. Defining a media reference field allows you to reference a globally defined media from any scope like a specific product or collection. If, for example, you have a collection of vendor logos, icons or author avatars and would like to associate these with specific products or articles, you can define a Media v2 field under the "shop" or "globals" scope and use a media reference field to point to any of the uploaded media, allowing for a single point of maintenance of the media itself. The media reference field itself will contain the referenced media's handle and you can do a lookup in Liquid like this:

{% assign referenced_media = shop.metafields.globals.vendor_logos | where: "handle", product.metafields.accentuate.vendor_logo_ref | first %}
<img src="{{ referenced_media.src }}" alt="{{ referenced_media.alt }}"/>

Or, if you have multiple media references selected:

{% assign selected_handles = product.metafields.accentuate.vendor_logo_ref | split: '|' %}
{% for selected_handle in selected_handles %}
  {% assign referenced_media = shop.metafields.globals.vendor_logos | where: "handle", selected_handle | first %}
  <img src="{{ referenced_media.src }}" alt="{{ referenced_media.alt }}"/>
{% endfor %}

Note the use of the Liquid filter "first" to pull the first element from the resulting array.

When updating a media being referenced by one or more media reference fields, you must ensure that the references stay valid by doing a "replace" operation rather than deleting and reloading the media (which will break the reference). This is available as an option button when hovering over the media:

When updating a media referenced by one or more media reference fields, you must ensure that the references stay valid by doing a "replace" operation rather than deleting and reloading the media (which will break the reference). This is available as an option button when hovering over the media:

The above examples use

Using a File reference field, you can reference a file or an image uploaded to Shopify (under Settings > Files) A file reference is stored as the filename, so you can get a fully qualified URL pointing to the file within Shopify's CDN using the

Also, the filename (of an image) can be used as a lookup value to the images global object in Liquid to get an of the file:

Shopify Global Objects
Liquid filters file_url or file_img_url:
image object