# 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:

![](https://3940270179-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FbIlmOfNwpXqPZMStJkgh%2Fuploads%2FdmzmD3vKCVKejUOP22P7%2FCleanShot%202021-11-08%20at%2013.01.49%402x.png?alt=media\&token=dfe594ce-cea0-406e-94f7-c0d4f4b2ddb7)

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.

![](https://3940270179-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FbIlmOfNwpXqPZMStJkgh%2Fuploads%2FMnsBHTSKr56rsvS4wu5M%2FCleanShot%202021-11-08%20at%2013.02.18%402x.png?alt=media\&token=e6f47763-60f1-42b6-9a1e-c9d938dfd5d8)

{% hint style="info" %}
**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
{% endhint %}

### 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:

```json
{ 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:

```liquid
{% 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:

```liquid
{% 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&#x20;

### Resolving field references with indexes&#x20;

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:

```liquid
{% 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:

```liquid
{% 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:

```liquid
{% 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<br>

### 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:

```liquid
{% 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:

```liquid
{% 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.&#x20;

{% hint style="info" %}
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.
{% endhint %}

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:

```liquid
{% 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> 
```

{% hint style="info" %}
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
{% endhint %}