References to Global fields

Global fields references in ACF are meant as puzzle pieces for building your field definitions for a specific scope, making it easy to reference content that would otherwise be replicated across many products or collections, etc. For example. you have a set of features with an icon and a description common to your products defined as Global fields:

You can then use a global reference field to point to the section or any of the fields (and even specific occurrences within both), allowing for a single point of maintenance of the underlying data. So if a feature icon or description changes, you just update the global field and the change will be reflected on all your products instantly.

Tip: If a repeatable section contains a field of type Text, the content of the first in the sequence will be included after each occurrence's index number ("Organic" and "Vegan" in the example) for easier selection of the correct occurrence

What is stored in the reference field?

The underlying Metafield value when selecting global fields will always be a JSON object with a single .references property containing an iterable array of JSON objects with either a .field or a .section property (depending on what is being referenced) and optionally either an .index or .key property. The .key property is only used for repeatable section references and only when the global section being referenced has its "Use sticky references" setting enabled (see below). If just a single field or section is selected, the array will have just one entry. This allows for consistent use of Liquid's array filters such as first, last, where, etc. Example structure:

{ references: [
    { field: "field_name",
      section: "section_name",
      index: <number>,
      key: "internal_random_key"
    }]
}

You can query the .references array for either the .field or .section property being present to detect what is being referenced as well as the .index property to detect if a specific occurrence is being referenced.

Resolving field references

When one or more fields are being referenced, each field reference (an element in the .references array) will contain the field's name in the .field property and you can resolve the reference in Liquid like this:

{% assign reference_to = product.metafields.accentuate.features.references | first %}
{% assign referenced_global_field = shop.metafields.globals[reference_to.field] %}

<p>{{ referenced_global_field }}</p>

Or, if you have selected multiple fields references:

{% assign references_to = product.metafields.accentuate.features.references %}
{% for reference_to in references_to %}
  {% assign referenced_global_field = shop.metafields.globals[reference_to.field] %}
  <p>{{ referenced_global_field }}</p>
{% endfor %}

If you are referencing repeatable fields, please see the related article "Repeatable fields" for instructions about how to loop over these

Resolving field references with indexes

A global reference may point to specific occurrences of repeatable fields. When this is the case, the referenced index is stored in the .index property. This example covers a single field reference to a specific occurrence:

{% assign reference_to = product.metafields.accentuate.features.references | first %}
{% assign referenced_global_field = shop.metafields.globals[reference_to.field][reference_to.index] %}
<p>{{ referenced_global_field }}</p>

Detecting the referenced field type

If you need to check which type of field is being referenced, you can cross-reference the .field selection against the field definitions for the global scope, like this:

{% assign reference_to_type = shop.metafields.acf_settings.global.fields | where: "name", reference_to.field | map: "type" | first %}

<p>The type of field being referenced is '{{ reference_to_type }}'</p>

Resolving section references

If the global reference field is referencing a .section, you can go via the field definitions to find the section's fields (see related article below), like this:

{% assign reference_to = product.metafields.accentuate.features.references | first %}
{% assign referenced_fields = shop.metafields.acf_settings.global.fields | where: "section_name", reference_to.section %}

{% for referenced_field in referenced_fields %}
  {% assign referenced_global_field = shop.metafields.globals[referenced_field.name] %}
  <p>{{ referenced_field.label }}: {{ referenced_global_field }}</p> 
{% endfor %}

If you are referencing a repeatable section, please see the related article "Repeatable fields" for instructions about how to loop over these

Resolving section references with indexes (i.e. the non-sticky way)

Reference fields may point to specific occurrences of repeatable sections. When this is the case, the referenced index is stored in the .index property and is valid for accessing the relevant part of the section's fields. This example covers a single reference to a section's specific occurrence (like "Features #1" in the above selection) which then is resolved to the contained fields dynamically:

{% assign reference_to = product.metafields.accentuate.features.references | first %}
{% assign referenced_fields = shop.metafields.acf_settings.global.fields | where: "section_name", reference_to.section %}

{% for referenced_field in referenced_fields %}
  {% assign referenced_global_field = shop.metafields.globals[referenced_field.name][reference_to.index] %}
  <p>{{ referenced_global_field }}</p> 
{% endfor %}

Usually, though, you'll be selecting specific sections and just want to use the index of the section being referenced (like "Features #1" and "Features #2" in the above selection), so you can loop the reference field selections and code the fields directly in Liquid using the index property:

{% assign references_to = product.metafields.accentuate.features.references %}
{% for reference_to in references_to %}

  <p>{{ shop.metafields.globals.feature_title[reference_to.index] }}</p> 
  <p>{{ shop.metafields.globals.feature_description[reference_to.index] }}</p> 

{% endfor %}

Resolving section references with keys (i.e. the sticky way)

Same as above, reference fields may point to specific occurrences of repeatable sections but can optionally store a "sticky" reference to the selected occurrences' index. This happens automatically when the global section being referenced has its "Use sticky references" setting enabled. When this is the case, the referenced "index" is stored indirectly in the .key property and the correct index can then be determined dynamically in Liquid.

This is the recommended way to use section references because it ensures that the references are always up to date even if the occurrences within the global section are rearranged after selections have been stored in the reference field.

This example covers a single reference to a section's specific occurrence (like "Features #1" in the above selection) via a key. The actual occurrence index is then resolved in Liquid via the 'assign index =' statement:

{% assign reference_to = product.metafields.accentuate.features.references | first %}
{% assign index = shop.metafields.globals[reference_to.section] | where: "key", reference_to.key | map: 'index' | first %} 
  
<p>{{ shop.metafields.globals.feature_title[index] }}  
</p> 
<p>{{ shop.metafields.globals.feature_description[index] }}</p> 

If you get lost in field references and resolving to global fields, try outputting the involved fields using Liquid's json filter. This will often reveal any issues