Global field references

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 and optionally an .index property. 

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>
    }]
}

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 

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 (see related article below) 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 need to 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 references with indexes

Reference fields may point to specific occurrences of both repeatable fields and repeatable sections. 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>

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 sections being referenced (like "Features #1" and "Features #2" in the above selection), so you can loop the reference field's 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 %}

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

Did this answer your question? Thanks for the feedback There was a problem submitting your feedback. Please try again later.

Still need help? Contact Us Contact Us