{{ shop.metafields.types.care_instructions[product_type_handle] }}
``` # How to show fields in your storefront ### Showing your custom fields To actually show your custom fields' values on your storefront, you need to edit your Shopify theme. Your theme determines where and how various Shopify bits and pieces go on which pages. "Bits and pieces" also include your new custom fields a.k.a Metafields.\ \ There are several ways to edit a theme, but the most straightforward way is to use the built-in theme editor in your Shopify admin:  If you click on "Edit code" under the "Actions" button, you'll be taken to the theme editor. {% hint style="info" %} Editing a theme requires some proficiency with HTML/CSS as well as the [Liquid](https://shopify.dev/api/liquid) templating language. If you are not comfortable doing this and do not have a developer on hand, we can recommend getting in touch with an ACF Expert or a [Shopify Expert](https://experts.shopify.com/services/development-and-troubleshooting/add-custom-features-or-code). Either way will get you connected with skilled Shopify developers in no time. {% endhint %} As you know, you can choose from a wide range of themes from the Shopify Theme Store and also have a given theme customized to your specific needs. Or you can have a theme completely custom-built for your store.\ \ As a result, every theme structure is different and every one of our customers' field setups and needs are different. \ \ In this help center, we provide you with small general snippets of code as examples of how to use Shopify Metafields in different contexts and leave the actual implementation details (theme changes) up to you as the store owner and/or your developers. Please see Shopify's [Editing theme code](https://help.shopify.com/en/manual/using-themes/change-the-layout/theme-code) article on the subject.\ \ Too specific and detailed instructions for which theme files you should edit in your theme could potentially be misleading, but we'll give a simple example here anyway. Just note, that your theme's list of files and the contents of those will almost certainly be different from our examples but the overall principle is the same. {% hint style="success" %} Before making any changes, it is a good idea to [duplicate your theme](https://help.shopify.com/en/manual/using-themes/managing-themes/duplicating-themes) to create a backup copy. This makes it easy to discard your changes and start again if you need to {% endhint %} ### Example In this example, we have created a "Washing Instructions" HTML type field for products called *accentuate.washing\_instructions* (namespace-dot-name syntax) and we want to display it below the product description already present in the theme.  Open your theme editor and it looks something like this:  Click on the **product.liquid** file under **Templates**:  This file determines the overall structure of how a product is displayed on your storefront and we can see that it is comprised of a single section called **product-template**. So we find the **product-template.liquid** file under **Sections** and can now see a bunch of HTML code mixed with Liquid instructions:\ \ In this file, we need to find where the display of the product's description is handled. In our example, this is in lines 158-160:  We don't change how the product description is displayed but need to add in our new field, but only where there actually is something to display. Add the following code: ```liquid {% if product.metafields.accentuate.washing_instructions %}
{{ product.metafields.accentuate.washing_instructions }}
{% endif %}
```
making the final code look like this:
Save your changes and that's it! Your products now show washing instructions where these are available.
# Reference Manager
**Reference manager** is a tool that allows you to bulk apply references to your existing Metaobjects for selected items (products). This feature is ideal for merchants who manage large catalogs and need to quickly update references without manually editing each item individually.
### What is the Reference Manager used for?
{% hint style="info" %}
A **Metaobject reference** acts as a bridge, linking your items to data stored in your shop’s Metaobjects
{% endhint %}
Imagine you run an online clothing store with separate size charts for men's, women's, and children's clothing. Before Reference Manager, adding the men's size chart to each product had to be done manually, one by one. Now, with Reference Manager, you can assign it to all relevant men's products in one go.
Simply select all the men's products and apply the men's size chart Metaobject to them in one action. In just a few clicks, every product displays the correct sizing information. It's designed to handle simple and complex references.
To access the feature, simply navigate to the sidebar within your Shopify admin, and click on **Reference Manager** under the **Accentuate** app section.
# Creating a new reference within Reference Manager If you want to make a **new reference** within the Reference Manager, click on the “Create new reference” button in the upper-right corner.
# Filter usage When you save the filter, it will be added to the filter list. From here, you can see all the necessary info about the filter itself, including the filter's name, scope and the number of affected items.
{{ shop.metafields.types.care_instructions[product_type_handle] }}
``` # Fields & Sections ## **Fields** Fields are the essence of ACF. They are called "Metafields" and are stored as information tied directly to your own individual objects such as your products, collections, pages, etc.  You can use fields to store information, media, references, etc. that are relevant to help you better describe your objects in your storefront. Also, you can use it as an admin tool to store important backend information related to your exact business processes - the use cases can be whatever you want them to be essentially. ### Adding a new field definition Before being able to add any values to a field, it first needs to be defined with a name, field type, and any relevant settings related to the chosen type. 1. Click on "Add field" from the top menu bar 2. Give your field a relevant label. The field's name will automatically be generated based on this, but you can also edit that if you want.  3\. On the next page you can choose the field's data type:  You can read more about the various field types [here](/metafield-definitions/deciding-on-a-field-type). 4\. On the last page you can select various settings related to your chosen field type.  5\. Click on "Done" and then be sure to hit the "Save" button in the right sidebar. Your field is then ready to use in the editor. {% hint style="success" %} If you are looking for inspiration for what you can do with your custom fields, try having a look at our various [field types](/metafield-definitions/deciding-on-a-field-type). If you have a certain feature in mind, and you are unsure how to set up your fields in order to achieve it, reach out to us. We would be happy to help you figure out the optimal solution for you. {% endhint %} ## **Sections** Sections are used for two purposes: 1. To visually and logically group fields in the editor and to control the section's fields when the section is defined as [repeatable](/the-editor/repeatable-fields) 2. To group fields for the purpose of creating a [custom layout](/the-editor/layouts) per individual object (e.g. a page or a product) {% hint style="info" %} Sections are not custom fields (Metafields) in their own right but rather control elements for the value and layout editor respectively. If you need to loop over the contained fields, please see [this article](/liquid-guides/access-field-definitions). {% endhint %} ### Adding a new section To add a new section you can click on the "Add section here" on a field definition to add a section below the field. If you do not have any fields for the scope, the "Add section" button will also be available in the top menu bar.  {% hint style="info" %} You can prefix a section's title with a "-" (dash) if you need the section to appear visually as a "sub-section" of another section in the editor {% endhint %} # Create a Metafield definition ### **Fields** Fields are the essence of ACF. They are called "Metafields" and are stored as information tied directly to your own individual objects such as your products, collections, pages, etc.  You can use fields to store information, media, references, etc. that are relevant to help you better describe your objects in your storefront. Also, you can use it as an admin tool to store important backend information related to your exact business processes - the use cases can be whatever you want them to be essentially. ### Anatomy of a Metafield The image below illustrates the full anatomy of a Metafield. While this may look complex at first glance but don’t worry! We’ll walk through each element in detail over the next few articles to ensure you fully understand how Metafields work and how to use them effectively.# Field data type When defining a custom field, selecting the correct **field data type** is essential because it determines **what kind of data** you want to store. ACF supports a wide variety of field types, including: simple **text** fields, **images**, **URLs**, **HTML**, **rich text**, **file uploads**, **number** inputs, **dropdowns**, **references** and more. Each serves a specific purpose depending on the kind of data you need to capture. For example: * Want to upload a product demo video? Use a **Media v2** field. * Need a short description? Use a **Single-line text** field. * Referencing another object like a global FAQ? Use a **Reference** field. {% hint style="info" %} When adding a new field, ACF may restrict its field type to a specific selection. If you have a Shopify Metafield definition in place for the chosen name and namespace combination, this definition will determine your field's type for you, so the Shopify and ACF field definitions are aligned (as they should be). {% endhint %} To help you visualize your options, here’s a preview of the field type selector in ACF:
{{ product.metafields.accentuate.subtitle.value }}
``` ### Repeatability {% hint style="warning" %} While Shopify » ... (List) types are repeatable by definition, they cannot be part of a repeatable section. This is a restriction in ACF, which will be addressed in an upcoming version. {% endhint %} ### Transferability {% hint style="warning" %} Shopify **reference field** values cannot successfully be transferred to other stores due to the use of internal Shopify ids, which will vary across stores. **File reference** fields are an exception here if the same file names exist in the target store. {% endhint %} # Shopify » Single line text A Shopify Single line text works similar to the ACF type Text.\ \ There is no functional difference, but the Liquid code has a new syntax. Being a Shopify data type, that returns a [Metafield object](https://shopify.dev/api/liquid/objects/metafield), the *value* property returns the actual value: ```liquid{{ product.metafields.accentuate.subtitle.value }}
``` # Shopify » Multi-line text A Shopify Multi-line text works similar to the ACF type Text (with its "Lines" setting set to more than 1 line).\ \ There is no functional difference, but the Liquid code has a new syntax. Being a Shopify data type, that returns a [Metafield object](https://shopify.dev/api/liquid/objects/metafield), the *value* property returns the actual value: ```liquid{{ product.metafields.accentuate.subtitle.value }}
``` {% hint style="info" %} A Shopify Multi-line text cannot store more than 65,535 characters (this includes any HTML tags) {% endhint %} ### Storing HTML in a Multi line text field Since the Shopify field types don't yet offer a 'html' option, we have made it possible to treat the Multi line text field as HTML:liquid  With this setting enabled, you get the same editing functionality from ACF as for our [native HTML field type.](/metafield-definitions/create-a-metafield-definition/field-data-type/acf-field-types/html) # Shopify » Boolean A Shopify Boolean works similar to the ACF type Checkbox\ \ There is no functional difference, but the Liquid code has a new syntax. Being a Shopify data type, that returns a [Metafield object](https://shopify.dev/api/liquid/objects/metafield), the *value* property returns the actual value: ```liquid {% if product.metafields.accentuate.display_vendor.value %}{{ product.vendor }}
{% endif %} ``` # Shopify » Color A Shopify Color works similar to the ACF type Color and gives you a convenient control to select a color and store the result as a string in hex RGB format such as #000000, #e9e9e9, #ffffff etc. \ \ Example use: ```html ``` Also, you can use [Liquid Color filters](https://shopify.dev/api/liquid/filters/color-filters) to perform operations on the color such as converting to HSL, lighten or darken the color etc. {% hint style="info" %} **Note:** while the *value* property used as shown above returns a string in hex RGB format, the Shopify Color type actually returns [a Color object](https://shopify.dev/api/liquid/objects/color) with access to the selected color's underlying properties such as the *red*, *blue* and *green* components. {% endhint %} # Shopify » Custom objects (JSON) A Shopify JSON field works similarly to the ACF JSON type, albeit without restrictions regarding outermost arrays.\ \ The type allows you to enter field values as raw JSON. As long as you adhere to valid JSON syntax, you are free to define anything you like in your very own structure.\ \ Being a Shopify data type returning a [Metafield object](https://shopify.dev/api/liquid/objects/metafield), the *value* property returns the actual value in Liquid.\ \ So, if you have a JSON field with this content: ```json { "make": "Audi", "model": "RS6" } ``` You can use it directly in Liquid: ```liquid {% assign car = product.metafields.accentuate.specs.value %}My car is the brand new {{ car.make }} {{ car.model }}
``` If you need the custom field as a client-side JavaScript variable, you can do this: ```javascript ``` # Shopify » URL A Shopify Url field type basically behaves just like a Text (or Shopify Single line text) field, allowing you to enter a URL.\ \ Defining the field as a URL type ensures that the content is a fully qualified URL complete with a protocol scheme (https\://, http\:// etc.): ```liquid Click to view instructions ``` # Shopify » Date A Shopify Date works similar to the ACF type Date but always stores the date in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format (YYYY-MM-DD) without a presumed timezone.\ \ A field of type Shopify » Date can be subject to date filters in Liquid: ```liquid {{ product.metafields.accentuate.published_date.value | date: "%a, %b %d, %y" }} ``` Please see [Understanding Date Formats in Liquid and Shopify](https://www.shopify.com/partners/blog/liquid-date-format) # Shopify » Date and Time A Shopify Date and Time field always stores the date and time in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format without a presumed timezone (YYYY-MM-DDThh:mm:ss+00:00) \ \ Note that ACF doesn't allow for selection of seconds in the time part of the field - this will always be '00'.\ \ A field of type Shopify » Date and Time can be subject to date filters in Liquid: ```liquid {{ product.metafields.accentuate.published_date_time.value | date: format: 'long' }} ``` Please see [Understanding Date Formats in Liquid and Shopify](https://www.shopify.com/partners/blog/liquid-date-format) # Shopify » Integer A Shopify Integer works similar to the Decimal type, but only allows for input of a number without decimals.\ \ The *value* property returns a numeric value directly, allowing you to do numeric comparisons directly: ```liquid {% assign rrp = product.metafields.accentuate.rrp_price.value %} {% if rrp > 100 %}RRP is {{ rrp }}
{% endif %} ``` # Shopify » Decimal A Shopify Decimal works similar to the ACF type Number, allowing for input of a number with decimals.\ \ The *value* property returns a numeric value directly, allowing you to do numeric comparisons directly: ```liquid {% assign rrp = product.metafields.accentuate.rrp_price.value %} {% if rrp > 100 %}RRP is {{ rrp }}
{% endif %} ``` # Shopify » Weight A Shopify Weight type allows you to select a unit and a decimal value to go with that unit.\ \ Weight units can be any of **oz**, **lb**, **g** or **kg**.\ \ The entered weight is then available as a JSON structure with *unit* and *value* properties, for example: ```liquid {% assign weight = product.metafields.accentuate.weight.value %}The weight is {{ weight.value }}{{ weight.unit }}
``` Referencing *.value* alone will render the output as "*value*\The weight is {{ product.metafields.accentuate.weight.value }}
``` # Shopify » Volume A Shopify Volume type allows you to select a unit and a decimal value to go with that unit.\ \ Volume units can be any of **ml**, **cl**, **l**, **m3** (cubic meters), **us\_fl\_oz**, **us\_pt**, **us\_qt**, **us\_gal**, **imp\_fl\_oz**, **imp\_pt**, **imp\_qt** or **imp\_gal**.\ \ The entered volume is then available as a JSON structure with *unit* and *value* properties, for example: ```liquid {% assign volume = product.metafields.accentuate.volume.value %}The volume is {{ volume.value }}{{ volume.unit }}
``` Referencing *.value* alone will render the output as "*value*\The volume is {{ product.metafields.accentuate.volume.value }}
``` # Shopify » Dimensions A Shopify Dimension type allows you to select a unit and a decimal value to go with that unit.\ \ Dimension units can be any of **in**, **ft**, **yd**, **mm**, **cm** or **m**.\ \ The entered dimension is then available as a JSON structure with *unit* and *value* properties, for example: ```liquid {% assign dimension = product.metafields.accentuate.dimension.value %}The dimension is {{ dimension.value }}{{ dimension.unit }}
``` Referencing *.value* alone will render the output as "*value*\The dimension is {{ product.metafields.accentuate.dimension.value }}
``` # Shopify » Reference fields A Shopify Reference field works similarly to the ACF reference type.\ \ From an editor's perspective, there is no functional difference, but the Liquid code now returns the referenced object directly without the need to do a lookup via a global object using a handle.\ \ So for example a Product reference returns the referenced product directly: ```liquid {% assign ref_product = product.metafields.accentuate.ref_product.value %}The referenced product is {{ ref_product.title }}
``` If you are referencing a file or an image from your Files list in Shopify, you can get the associated URL using the [Liquid filters *file\_url* and *file\_img\_url*:](https://shopify.dev/api/liquid/filters/url-filters#file_url) ```liquid {% assign url = product.metafields.accentuate.ref_file.value | file_url %}The referenced file is {{ url }}
``` {% hint style="warning" %} Shopify reference field values cannot successfully be transferred to other stores due to the use of internal Shopify ids, which will vary across stores {% endhint %} {% hint style="success" %} However, using ACF, you can choose to export Shopify Product references and Shopify Collection references using their respective handles, which you can then import into another store assuming the handles match across your stores {% endhint %} # ACF Field types # Text The value of custom fields of type Text is represented as you may expect - as Metafields with string values matching the value of their respective custom fields ```liquid{{ product.metafields.accentuate.subtitle }}
``` If you need to display multi-line texts on your storefront, you can take advantage of the *newline\_to\_br* filter, so line breaks will be formatted correctly: ```liquid{{ product.metafields.accentuate.subtitle | newline_to_br }}
``` # Markdown text In a Markdown type field, you can enter text in [Markdown syntax](https://www.markdownguide.org/basic-syntax/) and ACF will automatically render it as HTML in a separate property in the Metafield.\ \ A Markdown field contains two properties: > markdown Your markdown as entered in the editor > html The HTML derived from your Markdown, ready to show in the browser: ```html{{ product.metafields.accentuate.markdown_title.html }}
``` # HTML Editing HTML in custom fields is done via an advanced editor - the Froala WYSIWYG editor.\ \ Via the individual HTML fields' setup or the settings dialog (available from the admin side menu), you can choose to have either the full toolbar or a simplified version.\ \ The Settings dialog also allows you to turn on "paste as plain text" so that pasting HTML from other sources (such as Word) won't carry over any formatting but will keep the structure.  ### Preserving the HTML look on your storefront Depending on the options used for aligning blocks of text, embedding videos, styling images, and tables, etc., the HTML itself may contain references to CSS classes defined by Froala.\ \ To preserve the look of the edited HTML outside of the editor (ie on your storefront) you **may have** to include the following CSS file in your theme.liquid file: ```html ``` Note the version number 3.1.0 in the URL. This can change over time, so if anything looks out of place, check your used version number vs the above.\ \ Also, make sure that you place the edited content inside an element that has the class *fr-view*: ```html
{{ product.metafields.accentuate.my_html_description }}
```
# Checkbox
A checkbox can hold two states - checked or unchecked. \
\
The Metafield value of a checked checkbox (!) is represented as a string value of "true" but an unchecked checkbox will cause the underlying Metafield to be deleted rather than contain a value of "false". \
\
Accordingly, we can test for it being checked or not this way:
```liquid
{% if product.metafields.accentuate.washable %}
{{ product.title }} can be washed
{% else %}{{ product.title }} can NOT be washed
{% endif %} ``` # Selection A field of type Selection gives you either a dropdown-style or a table-style way of selecting one or more predefined values. {% hint style="info" %} You can mark values to be suggested when editing a product, a page, etc. that doesn’t have a value for that field already. If you would like a default value of "Blue" to be suggested by default in a selection of "Red, Green, Blue", just prefix the option with a colon: ":Blue" in the field definition {% endhint %} {% hint style="info" %} You can opt to have selections use another value than the one presented in the ACF editor by separating the value and the presentation string with double colons - "value::string". To have e.g. a color code stored for a selection of a named color, enter "#0000ff::Blue". This will show the option as "Blue" in the ACF editor dropdown but actually store the value "#0000ff" in the Metafield {% endhint %} The selection is represented as a Metafield with its string value matching the selected value: ```htmlYou have selected the value: {{ product.metafields.accentuate.selection }}
``` Or, in case of multiple selected values, with each value listed using the "pipe" symbol ("|") as a separator token. \ \ You can use Liquid's 'split' filter on the Metafield to separate the values - like this: ```liquid {% assign selected_values = product.metafields.accentuate.selection | split: '|' %} {% for selected_value in selected_values %}{{ selected_value }}
{% endfor %} ``` # Tags Tags behave similarly to Selection types (see separate article) with the only difference being that you define the values for every instance of your Shopify object as opposed to the selection lists' predefined options. A tag field, where you have entered only a single value, is represented as a Metafield with its string value matching your input, and as with selections, if you have entered multiple values, each value is listed with the "pipe" symbol ("|") as a separator token. # Number All ACF custom fields are stored as strings - even numeric types like Number to allow for decimal points. \ \ Liquid handles this quite nicely with one exception: you cannot do a direct comparison between a number and a string\ \ So while this is possible: ```htmlWe have {{ product.metafields.accentuate.stock | plus: 100 }} in stock
``` You need to convert it to a number if you want to do a numeric comparison with the field's value beforehand, like this: ```liquid {% assign in_stock = product.metafields.accentuate.stock | plus: 0 %} {% if in_stock < 5 %}Product is low on stock
{% endif %} ``` {% hint style="info" %} the " | plus: 0 " converts the string into a number type in Liquid {% endhint %} # Date A custom field of type Date can be subject to date filters in Liquid: ```liquid {{ product.metafields.accentuate.published_date | date: "%a, %b %d, %y" }} ``` To ensure that Liquid's date filters work as expected, consider using a universal, numbered format like 2019-09-14 for your custom field values.\ \ More info on that subject can be found in this article: {% embed url="](https://github.com/aFarkas/lazysizes)\ ACF currently has a limit of \~50MB per single media upload. You will typically only reach this limit when uploading video files. Take care not to force your visitors to download assets of this size but consider using a streaming service for large video files (like YouTube, Vimeo, etc.) # Custom Object (JSON) Defining a field as a Custom object allows you to enter field values as raw JSON.\ \ As long as you adhere to valid JSON syntax, you are free to define anything you like in your very own structure.\ \ If you have a JSON field with this content: ```json { "make": "Audi", "model": "RS6" } ``` you can use it directly in Liquid: ```liquid {% assign car = product.metafields.accentuate.specs %}
My car is the brand new {{ car.make }} {{ car.model }}
``` If you need the custom field as a client-side Javascript variable, you can use the JSON filter: ```javascript ``` ### Restrictions JSON objects can be as simple or as complex as you need **but** if you need to create an array of JSON objects, either use repeatable fields (see separate article) or define the array as a property within the JSON object.\ \ An **outer-most array is reserved** for ACF's handling of repeatable JSON fields.\ \ So while this works well: ```json { "colors": ["Red", "Blue", "Green"] } ``` this will cause ACF to split the values after you save them ```liquid ["Red", "Blue", "Green"] ``` # Multi-language Text Three different field types are available as multi-language types: * Text * Markdown text * HTML Each of these behave as described for their "single language" counterparts (Text, Markdown, and HTML) but with an important difference as outlined here.\ \ All content for the custom field (i.e. across languages) is stored in the **same** Metafield, so it is important in Liquid to specify which language you need. If you omit this, all languages will be shown\ \ This example grabs the English (ISO code 'en') title from a custom field called "title": ```liquid {{ product.metafields.accentuate.title.en }} ``` ### Matching a language to the visitor's preference But if we always wanted to show the title in English, there would be no need for multiple languages. \ \ We can match the custom field output to any Shopify-translated content by using the language noted in the URL via shop.locale. \ \ For example, if you have [myshopifystore.com/es/products/great-shirt](https://myshopifystore.com/es/products/great-shirt), you can grab the es language and use it as a key to access your custom field snippet: ```liquid {{ product.metafields.accentuate.title[shop.locale] }} ``` We can also detect the visitor's browser language using a little [Shopify magic](https://shopify.dev/docs/liquid/reference/objects/request#request-locale) to show the "title" custom field in the language preferred by the visitor: ``` {% assign user_language = request.locale.iso_code %} {{ product.metafields.accentuate.title[user_language] }} ``` ### Showing a default value The above examples will return an empty string if no content was provided for the visitor's language. To properly test if we have some content to show and revert to a safe default, we can apply the code below. \ \ This code also showcases that the configured locales (country names' ISO codes) are available in a special Metafield shop.metafields.acf\_settings.locales for precisely this purpose: ```liquid {% assign default_language = shop.metafields.acf_settings.locales | first %} {% if product.metafields.accentuate.title[shop.locale] %}{{ product.metafields.accentuate.title[shop.locale] }}
{% else %}{{ product.metafields.accentuate.title[default_language] }}
{% endif %} ``` ### Multi-language Markdown example In case you were wondering how multi-language Markdown fields work, here is an example (note the .html at the end to get the rendered HTML from the markdown code): ```liquid{{ product.metafields.accentuate.markdown_title[shop.locale].html }}
``` ### Setting up the languages Before you can edit content for multi-language fields, you need to tell ACF which languages to handle content for and optionally provide a DeepL API key for built-in translation. \ \ So, from your admin side menu, click the "Settings" button to open the settings dialog and go to the "Languages" tab:  In the selection box for "Multiple languages setup", select the languages you need to provide content for. You can select as few or as many languages as you need. Note that languages can be added or removed dynamically, so you don't need to know your complete setup before adding content for each language. If you need to add a language later after setting up content for other languages, you can just do so. {% hint style="warning" %} Mind the ordering as this will be reflected in the editor. You can also use the ordering to provide a default language in case a visitor's language is not defined (see below) {% endhint %} When you edit a multi-language custom field, the ACF editor will allow you to input content for each language selected in the above setup. \ \ Here is an example of a multi-language text field called "Greetings", allowing input in all three defined languages:  ### Translating content to other languages ACF supports in-app translation of content in multi-language fields via an integration with [DeepL](https://www.deepl.com/). DeepL combines deep learning and artificial intelligence to understand and translate text between these different languages: * Bulgarian * Czech * Danish * German * Greek * English * Spanish * Estonian * Finnish * French * Hungarian * Italian * Japanese * Lithuanian * Latvian * Dutch * Polish * Portuguese * Brazilian Portuguese * Romanian * Russian * Slovak * Slovenian * Swedish When you have multiple languages defined in ACF **and** your primary language is one of the above, ACF will allow you to translate content in a multi-language field **from** that primary language **to** any other language that is listed above. \ \ For example, you have English listed as a primary language (the first one in the ordering) with German, French, and Finnish as secondary languages.  With DeepL enabled, ACF will now allow you to translate **from** English **to** both German, French, and Finnish.\ \ The translation service is available directly from each field. This is an example of a simple text field:  Example for HTML fields with translation available directly from the toolbar:  ### How to enable DeepL To use DeepL within ACF, you need a DeepL Pro API subscription. DeepL Pro is a 3rd party service with both a free and a paid option. [See details and sign up here](https://www.deepl.com/pro.html#developer). \ \ Once signed up, you can go to your DeepL account page and see your API key:  Copy the API key using the copy button to the right of the key and from your Shopify admin, click the "Settings" button in the side menu to open the settings dialog, go to the "Languages" tab, and paste the key into the field for "DeepL API key":  Click "Save" and you're ready to translate your texts in-house. {% hint style="info" %} **Disclaimer:** DeepL does not give any guarantee regarding the correctness of the translations created by the machine translation system. This is not meant to replace a professional translation service for mission-critical content. {% endhint %} # Reference fields A reference type custom field is a specialized version of a 'Selection' type which will list all available objects of its type:  {% hint style="info" %} 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 {% endhint %} 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. ```liquid {{ 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 }} ``` The above examples use [Shopify Global Objects](https://help.shopify.com/en/themes/liquid/objects#global-objects) {% hint style="info" %} 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. {% endhint %} {% hint style="info" %} 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** {% endhint %} 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. ```liquid {{ 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: ```liquid {% assign selected_handles = product.metafields.accentuate.selection | split: '|' %} {% for selected_handle in selected_handles %}{{ all_products[selected_handle].title }}
{% 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: ```liquid {% 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 %}The referenced variant is {{ referenced_product.title }} {{ referenced_variant.title }}
``` Note the use of the Liquid filter "plus: 0" which converts a string to a number for use in the "where" filter. {% hint style="warning" %} 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 {% endhint %} ### File reference fields 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 [Liquid filters *file\_url* or *file\_img\_url*:](https://shopify.dev/api/liquid/filters/url-filters#file_url) ```liquid {% assign url = product.metafields.accentuate.referenced_file | file_url %} Click to download ``` Also, the filename (of an image) can be used as a lookup value to the *images* global object in Liquid to get an [image object](https://shopify.dev/api/liquid/objects/image) of the file: ```liquid {{ 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.: ```liquid {% assign url = product.metafields.accentuate.referenced_resource %} Please see here ``` ### 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: ```liquid {% assign referenced_media = shop.metafields.globals.vendor_logos | where: "handle", product.metafields.accentuate.vendor_logo_ref | first %}{{ referenced_global_field }}
``` 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] %}{{ referenced_global_field }}
{% 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: ```liquid {% assign reference_to = product.metafields.accentuate.features.references | first %} {% assign referenced_global_field = shop.metafields.globals[reference_to.field][reference_to.index] %}{{ referenced_global_field }}
``` ### 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 %}The type of field being referenced is '{{ reference_to_type }}'
``` ### 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] %}{{ referenced_field.label }}: {{ referenced_global_field }}
{% 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: ```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] %}
{{ referenced_global_field }}
{% 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 %}{{ shop.metafields.globals.feature_title[reference_to.index] }}
{{ shop.metafields.globals.feature_description[reference_to.index] }}
{% 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. {% 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 %}{{ shop.metafields.globals.feature_title[index] }}
{{ shop.metafields.globals.feature_description[index] }}
``` {% 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 %} # Fields ### **Fields** Fields are the essence of ACF. They are called "Metafields" and are stored as information tied directly to your own individual objects such as your products, collections, pages, etc.  You can use fields to store information, media, references, etc. that are relevant to help you better describe your objects in your storefront. Also, you can use it as an admin tool to store important backend information related to your exact business processes - the use cases can be whatever you want them to be essentially. # Label & Namespace ### What is a label in Metafields? **Label** - internal identifier you’ll see inside the app to help you stay organized. **Name / Key** - automatically generated based on the label, but you can also edit it if you want.# Field data type When defining a custom field, selecting the correct **field data type** is essential because it determines **what kind of data** you want to store. ACF supports a wide variety of field types, including: simple **text** fields, **images**, **URLs**, **HTML**, **rich text**, **file uploads**, **number** inputs, **dropdowns**, **references** and more. Each serves a specific purpose depending on the kind of data you need to capture. For example: * Want to upload a product demo video? Use a **Media v2** field. * Need a short description? Use a **Single-line text** field. * Referencing another object like a global FAQ? Use a **Reference** field. {% hint style="info" %} When adding a new field, ACF may restrict its field type to a specific selection. If you have a Shopify Metafield definition in place for the chosen name and namespace combination, this definition will determine your field's type for you, so the Shopify and ACF field definitions are aligned (as they should be). {% endhint %} To help you visualize your options, here’s a preview of the field type selector in ACF:
{{ product.metafields.accentuate.subtitle.value }}
``` ### Repeatability {% hint style="warning" %} While Shopify » ... (List) types are repeatable by definition, they cannot be part of a repeatable section. This is a restriction in ACF, which will be addressed in an upcoming version. {% endhint %} ### Transferability {% hint style="warning" %} Shopify **reference field** values cannot successfully be transferred to other stores due to the use of internal Shopify ids, which will vary across stores. **File reference** fields are an exception here if the same file names exist in the target store. {% endhint %} # Shopify » Single line text A Shopify Single line text works similar to the ACF type Text.\ \ There is no functional difference, but the Liquid code has a new syntax. Being a Shopify data type, that returns a [Metafield object](https://shopify.dev/api/liquid/objects/metafield), the *value* property returns the actual value: ```liquid{{ product.metafields.accentuate.subtitle.value }}
``` # Shopify » Multi-line text A Shopify Multi-line text works similar to the ACF type Text (with its "Lines" setting set to more than 1 line).\ \ There is no functional difference, but the Liquid code has a new syntax. Being a Shopify data type, that returns a [Metafield object](https://shopify.dev/api/liquid/objects/metafield), the *value* property returns the actual value: ```liquid{{ product.metafields.accentuate.subtitle.value }}
``` {% hint style="info" %} A Shopify Multi-line text cannot store more than 65,535 characters (this includes any HTML tags) {% endhint %} ### Storing HTML in a Multi line text field Since the Shopify field types don't yet offer a 'html' option, we have made it possible to treat the Multi line text field as HTML:liquid  With this setting enabled, you get the same editing functionality from ACF as for our [native HTML field type.](/metafield-definitions/create-a-metafield-definition/field-data-type/acf-field-types/html) # Shopify » Boolean A Shopify Boolean works similar to the ACF type Checkbox\ \ There is no functional difference, but the Liquid code has a new syntax. Being a Shopify data type, that returns a [Metafield object](https://shopify.dev/api/liquid/objects/metafield), the *value* property returns the actual value: ```liquid {% if product.metafields.accentuate.display_vendor.value %}{{ product.vendor }}
{% endif %} ``` # Shopify » Color A Shopify Color works similar to the ACF type Color and gives you a convenient control to select a color and store the result as a string in hex RGB format such as #000000, #e9e9e9, #ffffff etc. \ \ Example use: ```html ``` Also, you can use [Liquid Color filters](https://shopify.dev/api/liquid/filters/color-filters) to perform operations on the color such as converting to HSL, lighten or darken the color etc. {% hint style="info" %} **Note:** while the *value* property used as shown above returns a string in hex RGB format, the Shopify Color type actually returns [a Color object](https://shopify.dev/api/liquid/objects/color) with access to the selected color's underlying properties such as the *red*, *blue* and *green* components. {% endhint %} # Shopify » Custom objects (JSON) A Shopify JSON field works similarly to the ACF JSON type, albeit without restrictions regarding outermost arrays.\ \ The type allows you to enter field values as raw JSON. As long as you adhere to valid JSON syntax, you are free to define anything you like in your very own structure.\ \ Being a Shopify data type returning a [Metafield object](https://shopify.dev/api/liquid/objects/metafield), the *value* property returns the actual value in Liquid.\ \ So, if you have a JSON field with this content: ```json { "make": "Audi", "model": "RS6" } ``` You can use it directly in Liquid: ```liquid {% assign car = product.metafields.accentuate.specs.value %}My car is the brand new {{ car.make }} {{ car.model }}
``` If you need the custom field as a client-side JavaScript variable, you can do this: ```javascript ``` # Shopify » URL A Shopify Url field type basically behaves just like a Text (or Shopify Single line text) field, allowing you to enter a URL.\ \ Defining the field as a URL type ensures that the content is a fully qualified URL complete with a protocol scheme (https\://, http\:// etc.): ```liquid Click to view instructions ``` # Shopify » Date A Shopify Date works similar to the ACF type Date but always stores the date in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format (YYYY-MM-DD) without a presumed timezone.\ \ A field of type Shopify » Date can be subject to date filters in Liquid: ```liquid {{ product.metafields.accentuate.published_date.value | date: "%a, %b %d, %y" }} ``` Please see [Understanding Date Formats in Liquid and Shopify](https://www.shopify.com/partners/blog/liquid-date-format) # Shopify » Date and Time A Shopify Date and Time field always stores the date and time in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format without a presumed timezone (YYYY-MM-DDThh:mm:ss+00:00) \ \ Note that ACF doesn't allow for selection of seconds in the time part of the field - this will always be '00'.\ \ A field of type Shopify » Date and Time can be subject to date filters in Liquid: ```liquid {{ product.metafields.accentuate.published_date_time.value | date: format: 'long' }} ``` Please see [Understanding Date Formats in Liquid and Shopify](https://www.shopify.com/partners/blog/liquid-date-format) # Shopify » Integer A Shopify Integer works similar to the Decimal type, but only allows for input of a number without decimals.\ \ The *value* property returns a numeric value directly, allowing you to do numeric comparisons directly: ```liquid {% assign rrp = product.metafields.accentuate.rrp_price.value %} {% if rrp > 100 %}RRP is {{ rrp }}
{% endif %} ``` # Shopify » Decimal A Shopify Decimal works similar to the ACF type Number, allowing for input of a number with decimals.\ \ The *value* property returns a numeric value directly, allowing you to do numeric comparisons directly: ```liquid {% assign rrp = product.metafields.accentuate.rrp_price.value %} {% if rrp > 100 %}RRP is {{ rrp }}
{% endif %} ``` # Shopify » Weight A Shopify Weight type allows you to select a unit and a decimal value to go with that unit.\ \ Weight units can be any of **oz**, **lb**, **g** or **kg**.\ \ The entered weight is then available as a JSON structure with *unit* and *value* properties, for example: ```liquid {% assign weight = product.metafields.accentuate.weight.value %}The weight is {{ weight.value }}{{ weight.unit }}
``` Referencing *.value* alone will render the output as "*value*\The weight is {{ product.metafields.accentuate.weight.value }}
``` # Shopify » Volume A Shopify Volume type allows you to select a unit and a decimal value to go with that unit.\ \ Volume units can be any of **ml**, **cl**, **l**, **m3** (cubic meters), **us\_fl\_oz**, **us\_pt**, **us\_qt**, **us\_gal**, **imp\_fl\_oz**, **imp\_pt**, **imp\_qt** or **imp\_gal**.\ \ The entered volume is then available as a JSON structure with *unit* and *value* properties, for example: ```liquid {% assign volume = product.metafields.accentuate.volume.value %}The volume is {{ volume.value }}{{ volume.unit }}
``` Referencing *.value* alone will render the output as "*value*\The volume is {{ product.metafields.accentuate.volume.value }}
``` # Shopify » Dimensions A Shopify Dimension type allows you to select a unit and a decimal value to go with that unit.\ \ Dimension units can be any of **in**, **ft**, **yd**, **mm**, **cm** or **m**.\ \ The entered dimension is then available as a JSON structure with *unit* and *value* properties, for example: ```liquid {% assign dimension = product.metafields.accentuate.dimension.value %}The dimension is {{ dimension.value }}{{ dimension.unit }}
``` Referencing *.value* alone will render the output as "*value*\The dimension is {{ product.metafields.accentuate.dimension.value }}
``` # Shopify » Reference fields A Shopify Reference field works similarly to the ACF reference type.\ \ From an editor's perspective, there is no functional difference, but the Liquid code now returns the referenced object directly without the need to do a lookup via a global object using a handle.\ \ So for example a Product reference returns the referenced product directly: ```liquid {% assign ref_product = product.metafields.accentuate.ref_product.value %}The referenced product is {{ ref_product.title }}
``` If you are referencing a file or an image from your Files list in Shopify, you can get the associated URL using the [Liquid filters *file\_url* and *file\_img\_url*:](https://shopify.dev/api/liquid/filters/url-filters#file_url) ```liquid {% assign url = product.metafields.accentuate.ref_file.value | file_url %}The referenced file is {{ url }}
``` {% hint style="warning" %} Shopify reference field values cannot successfully be transferred to other stores due to the use of internal Shopify ids, which will vary across stores {% endhint %} {% hint style="success" %} However, using ACF, you can choose to export Shopify Product references and Shopify Collection references using their respective handles, which you can then import into another store assuming the handles match across your stores {% endhint %} # ACF Field types # Text The value of custom fields of type Text is represented as you may expect - as Metafields with string values matching the value of their respective custom fields ```liquid{{ product.metafields.accentuate.subtitle }}
``` If you need to display multi-line texts on your storefront, you can take advantage of the *newline\_to\_br* filter, so line breaks will be formatted correctly: ```liquid{{ product.metafields.accentuate.subtitle | newline_to_br }}
``` # Markdown text In a Markdown type field, you can enter text in [Markdown syntax](https://www.markdownguide.org/basic-syntax/) and ACF will automatically render it as HTML in a separate property in the Metafield.\ \ A Markdown field contains two properties: > markdown Your markdown as entered in the editor > html The HTML derived from your Markdown, ready to show in the browser: ```html{{ product.metafields.accentuate.markdown_title.html }}
``` # HTML Editing HTML in custom fields is done via an advanced editor - the Froala WYSIWYG editor.\ \ Via the individual HTML fields' setup or the settings dialog (available from the admin side menu), you can choose to have either the full toolbar or a simplified version.\ \ The Settings dialog also allows you to turn on "paste as plain text" so that pasting HTML from other sources (such as Word) won't carry over any formatting but will keep the structure.  ### Preserving the HTML look on your storefront Depending on the options used for aligning blocks of text, embedding videos, styling images, and tables, etc., the HTML itself may contain references to CSS classes defined by Froala.\ \ To preserve the look of the edited HTML outside of the editor (ie on your storefront) you **may have** to include the following CSS file in your theme.liquid file: ```html ``` Note the version number 3.1.0 in the URL. This can change over time, so if anything looks out of place, check your used version number vs the above.\ \ Also, make sure that you place the edited content inside an element that has the class *fr-view*: ```html
{{ product.metafields.accentuate.my_html_description }}
```
# Checkbox
A checkbox can hold two states - checked or unchecked. \
\
The Metafield value of a checked checkbox (!) is represented as a string value of "true" but an unchecked checkbox will cause the underlying Metafield to be deleted rather than contain a value of "false". \
\
Accordingly, we can test for it being checked or not this way:
```liquid
{% if product.metafields.accentuate.washable %}
{{ product.title }} can be washed
{% else %}{{ product.title }} can NOT be washed
{% endif %} ``` # Selection A field of type Selection gives you either a dropdown-style or a table-style way of selecting one or more predefined values. {% hint style="info" %} You can mark values to be suggested when editing a product, a page, etc. that doesn’t have a value for that field already. If you would like a default value of "Blue" to be suggested by default in a selection of "Red, Green, Blue", just prefix the option with a colon: ":Blue" in the field definition {% endhint %} {% hint style="info" %} You can opt to have selections use another value than the one presented in the ACF editor by separating the value and the presentation string with double colons - "value::string". To have e.g. a color code stored for a selection of a named color, enter "#0000ff::Blue". This will show the option as "Blue" in the ACF editor dropdown but actually store the value "#0000ff" in the Metafield {% endhint %} The selection is represented as a Metafield with its string value matching the selected value: ```htmlYou have selected the value: {{ product.metafields.accentuate.selection }}
``` Or, in case of multiple selected values, with each value listed using the "pipe" symbol ("|") as a separator token. \ \ You can use Liquid's 'split' filter on the Metafield to separate the values - like this: ```liquid {% assign selected_values = product.metafields.accentuate.selection | split: '|' %} {% for selected_value in selected_values %}{{ selected_value }}
{% endfor %} ``` # Tags Tags behave similarly to Selection types (see separate article) with the only difference being that you define the values for every instance of your Shopify object as opposed to the selection lists' predefined options. A tag field, where you have entered only a single value, is represented as a Metafield with its string value matching your input, and as with selections, if you have entered multiple values, each value is listed with the "pipe" symbol ("|") as a separator token. # Number All ACF custom fields are stored as strings - even numeric types like Number to allow for decimal points. \ \ Liquid handles this quite nicely with one exception: you cannot do a direct comparison between a number and a string\ \ So while this is possible: ```htmlWe have {{ product.metafields.accentuate.stock | plus: 100 }} in stock
``` You need to convert it to a number if you want to do a numeric comparison with the field's value beforehand, like this: ```liquid {% assign in_stock = product.metafields.accentuate.stock | plus: 0 %} {% if in_stock < 5 %}Product is low on stock
{% endif %} ``` {% hint style="info" %} the " | plus: 0 " converts the string into a number type in Liquid {% endhint %} # Date A custom field of type Date can be subject to date filters in Liquid: ```liquid {{ product.metafields.accentuate.published_date | date: "%a, %b %d, %y" }} ``` To ensure that Liquid's date filters work as expected, consider using a universal, numbered format like 2019-09-14 for your custom field values.\ \ More info on that subject can be found in this article: {% embed url="](https://github.com/aFarkas/lazysizes)\ ACF currently has a limit of \~50MB per single media upload. You will typically only reach this limit when uploading video files. Take care not to force your visitors to download assets of this size but consider using a streaming service for large video files (like YouTube, Vimeo, etc.) # Custom Object (JSON) Defining a field as a Custom object allows you to enter field values as raw JSON.\ \ As long as you adhere to valid JSON syntax, you are free to define anything you like in your very own structure.\ \ If you have a JSON field with this content: ```json { "make": "Audi", "model": "RS6" } ``` you can use it directly in Liquid: ```liquid {% assign car = product.metafields.accentuate.specs %}
My car is the brand new {{ car.make }} {{ car.model }}
``` If you need the custom field as a client-side Javascript variable, you can use the JSON filter: ```javascript ``` ### Restrictions JSON objects can be as simple or as complex as you need **but** if you need to create an array of JSON objects, either use repeatable fields (see separate article) or define the array as a property within the JSON object.\ \ An **outer-most array is reserved** for ACF's handling of repeatable JSON fields.\ \ So while this works well: ```json { "colors": ["Red", "Blue", "Green"] } ``` this will cause ACF to split the values after you save them ```liquid ["Red", "Blue", "Green"] ``` # Multi-language Text Three different field types are available as multi-language types: * Text * Markdown text * HTML Each of these behave as described for their "single language" counterparts (Text, Markdown, and HTML) but with an important difference as outlined here.\ \ All content for the custom field (i.e. across languages) is stored in the **same** Metafield, so it is important in Liquid to specify which language you need. If you omit this, all languages will be shown\ \ This example grabs the English (ISO code 'en') title from a custom field called "title": ```liquid {{ product.metafields.accentuate.title.en }} ``` ### Matching a language to the visitor's preference But if we always wanted to show the title in English, there would be no need for multiple languages. \ \ We can match the custom field output to any Shopify-translated content by using the language noted in the URL via shop.locale. \ \ For example, if you have [myshopifystore.com/es/products/great-shirt](https://myshopifystore.com/es/products/great-shirt), you can grab the es language and use it as a key to access your custom field snippet: ```liquid {{ product.metafields.accentuate.title[shop.locale] }} ``` We can also detect the visitor's browser language using a little [Shopify magic](https://shopify.dev/docs/liquid/reference/objects/request#request-locale) to show the "title" custom field in the language preferred by the visitor: ``` {% assign user_language = request.locale.iso_code %} {{ product.metafields.accentuate.title[user_language] }} ``` ### Showing a default value The above examples will return an empty string if no content was provided for the visitor's language. To properly test if we have some content to show and revert to a safe default, we can apply the code below. \ \ This code also showcases that the configured locales (country names' ISO codes) are available in a special Metafield shop.metafields.acf\_settings.locales for precisely this purpose: ```liquid {% assign default_language = shop.metafields.acf_settings.locales | first %} {% if product.metafields.accentuate.title[shop.locale] %}{{ product.metafields.accentuate.title[shop.locale] }}
{% else %}{{ product.metafields.accentuate.title[default_language] }}
{% endif %} ``` ### Multi-language Markdown example In case you were wondering how multi-language Markdown fields work, here is an example (note the .html at the end to get the rendered HTML from the markdown code): ```liquid{{ product.metafields.accentuate.markdown_title[shop.locale].html }}
``` ### Setting up the languages Before you can edit content for multi-language fields, you need to tell ACF which languages to handle content for and optionally provide a DeepL API key for built-in translation. \ \ So, from your admin side menu, click the "Settings" button to open the settings dialog and go to the "Languages" tab:  In the selection box for "Multiple languages setup", select the languages you need to provide content for. You can select as few or as many languages as you need. Note that languages can be added or removed dynamically, so you don't need to know your complete setup before adding content for each language. If you need to add a language later after setting up content for other languages, you can just do so. {% hint style="warning" %} Mind the ordering as this will be reflected in the editor. You can also use the ordering to provide a default language in case a visitor's language is not defined (see below) {% endhint %} When you edit a multi-language custom field, the ACF editor will allow you to input content for each language selected in the above setup. \ \ Here is an example of a multi-language text field called "Greetings", allowing input in all three defined languages:  ### Translating content to other languages ACF supports in-app translation of content in multi-language fields via an integration with [DeepL](https://www.deepl.com/). DeepL combines deep learning and artificial intelligence to understand and translate text between these different languages: * Bulgarian * Czech * Danish * German * Greek * English * Spanish * Estonian * Finnish * French * Hungarian * Italian * Japanese * Lithuanian * Latvian * Dutch * Polish * Portuguese * Brazilian Portuguese * Romanian * Russian * Slovak * Slovenian * Swedish When you have multiple languages defined in ACF **and** your primary language is one of the above, ACF will allow you to translate content in a multi-language field **from** that primary language **to** any other language that is listed above. \ \ For example, you have English listed as a primary language (the first one in the ordering) with German, French, and Finnish as secondary languages.  With DeepL enabled, ACF will now allow you to translate **from** English **to** both German, French, and Finnish.\ \ The translation service is available directly from each field. This is an example of a simple text field:  Example for HTML fields with translation available directly from the toolbar:  ### How to enable DeepL To use DeepL within ACF, you need a DeepL Pro API subscription. DeepL Pro is a 3rd party service with both a free and a paid option. [See details and sign up here](https://www.deepl.com/pro.html#developer). \ \ Once signed up, you can go to your DeepL account page and see your API key:  Copy the API key using the copy button to the right of the key and from your Shopify admin, click the "Settings" button in the side menu to open the settings dialog, go to the "Languages" tab, and paste the key into the field for "DeepL API key":  Click "Save" and you're ready to translate your texts in-house. {% hint style="info" %} **Disclaimer:** DeepL does not give any guarantee regarding the correctness of the translations created by the machine translation system. This is not meant to replace a professional translation service for mission-critical content. {% endhint %} # Reference fields A reference type custom field is a specialized version of a 'Selection' type which will list all available objects of its type:  {% hint style="info" %} 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 {% endhint %} 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. ```liquid {{ 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 }} ``` The above examples use [Shopify Global Objects](https://help.shopify.com/en/themes/liquid/objects#global-objects) {% hint style="info" %} 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. {% endhint %} {% hint style="info" %} 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** {% endhint %} 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. ```liquid {{ 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: ```liquid {% assign selected_handles = product.metafields.accentuate.selection | split: '|' %} {% for selected_handle in selected_handles %}{{ all_products[selected_handle].title }}
{% 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: ```liquid {% 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 %}The referenced variant is {{ referenced_product.title }} {{ referenced_variant.title }}
``` Note the use of the Liquid filter "plus: 0" which converts a string to a number for use in the "where" filter. {% hint style="warning" %} 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 {% endhint %} ### File reference fields 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 [Liquid filters *file\_url* or *file\_img\_url*:](https://shopify.dev/api/liquid/filters/url-filters#file_url) ```liquid {% assign url = product.metafields.accentuate.referenced_file | file_url %} Click to download ``` Also, the filename (of an image) can be used as a lookup value to the *images* global object in Liquid to get an [image object](https://shopify.dev/api/liquid/objects/image) of the file: ```liquid {{ 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.: ```liquid {% assign url = product.metafields.accentuate.referenced_resource %} Please see here ``` ### 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: ```liquid {% assign referenced_media = shop.metafields.globals.vendor_logos | where: "handle", product.metafields.accentuate.vendor_logo_ref | first %}{{ referenced_global_field }}
``` 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] %}{{ referenced_global_field }}
{% 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: ```liquid {% assign reference_to = product.metafields.accentuate.features.references | first %} {% assign referenced_global_field = shop.metafields.globals[reference_to.field][reference_to.index] %}{{ referenced_global_field }}
``` ### 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 %}The type of field being referenced is '{{ reference_to_type }}'
``` ### 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] %}{{ referenced_field.label }}: {{ referenced_global_field }}
{% 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: ```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] %}
{{ referenced_global_field }}
{% 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 %}{{ shop.metafields.globals.feature_title[reference_to.index] }}
{{ shop.metafields.globals.feature_description[reference_to.index] }}
{% 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. {% 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 %}{{ shop.metafields.globals.feature_title[index] }}
{{ shop.metafields.globals.feature_description[index] }}
``` {% 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 %} # Sections ### **Sections** Sections are used for two purposes: 1. To visually and logically group fields in the editor and to control the section's fields when the section is defined as [repeatable](/the-editor/repeatable-fields) 2. To group fields for the purpose of creating a [custom layout](/the-editor/layouts) per individual object (e.g. a page or a product) {% hint style="info" %} Sections are not custom fields (Metafields) in their own right but rather control elements for the value and layout editor, respectively. If you need to loop over the contained fields, please see [this article](/liquid-guides/access-field-definitions). {% endhint %} ### Adding a new section To add a new section you can click on the **Add section here** on a field definition to add a section below the field. If you do not have any fields for the scope, the **Add section** button will also be available in the top menu bar.  {% hint style="info" %} You can prefix a section's title with a "-" (dash) if you need the section to appear visually as a "sub-section" of another section in the editor {% endhint %} # Deciding on a field type In some scenarios, it can be difficult to figure out which field type to use or for which scope to have the field in to be able to achieve the feature in mind. While there is not always a correct answer, some general principles may guide you in the right direction for your scenarios It can be very beneficial for you to make these considerations from the get-go in order to make it easier for you to manage down the road, not having to change your setup later on. If you have any doubts about how you should set up your intended use case, get in touch with us and we will be happy to assist you. {% hint style="info" %} When adding a new field, ACF may restrict its field type to a specific selection. If you have a Shopify Metafield definition in place for the chosen name and namespace combination, this definition will determine your field's type for you, so the Shopify and ACF field definitions are aligned (as they should be). {% endhint %} ### Choosing the right scope First off, consider the data - would the same values reoccur across multiple objects? If so, utilizing one of the aggregate scopes may save you a lot of time and effort by allowing for one point of management of the data. You can read more about the various scopes [here](/introduction/field-scopes). ### Multiple selections or repeatable? While the two settings can from time to time achieve the same result, it is also relevant to consider when it is right to use one over the other. Enabling multiple selections for a field is recommended if you need multiple values for just one field. If you have a group of fields that you need multiple values for, making the overall section of the fields repeatable would be the recommended way to go. In general, we recommend not enabling any settings you won't need. It is much better to keep it simple and build your setup bit by bit once the needs present themselves. # Automatic tagging ACF supports automatic tagging (and untagging) for products, articles, customers, and orders when entering or importing values for these object types (including product variants).\ \ Automatic tagging of e.g. products will allow you to filter collections by custom field values on your storefront using either [Automated Collections](https://help.shopify.com/en/manual/products/collections/automated-collections/auto-create) or [Shopify's built-in tag filtering](https://shopify.dev/themes/navigation-search/filtering/tag-filtering)\ You can enable this in the field definition for the following field types * Text fields * Checkboxes * Tags * Selections * Number fields * Number ranges * Colors * Reference fields \ Tags are applied in the form of the field's label (e.g. "Brand") followed by either a "pipe" symbol ("|"), an underscore ("\_") or a colon (":") and the value of the field. {% hint style="info" %} *To use underscores ("\_") or colons (":") for the split character in the automatically applied tags, select this under "Settings" from the ACF's main dashboard* {% endhint %} {% hint style="info" %} A tag in Shopify (here: label and value combined) cannot be longer than 40 characters {% endhint %} For fields that can hold multiple values, like repeatable fields or fields that allow for multiple selections, multiple tags may be created and applied to the product as a result of the automatic tagging.\ \ Tags for checked checkboxes, where the value resolves to "true", only hold the field's label e.g. "New look", "Backordered" etc.\ \ Tags for reference fields will contain the referenced object's handle\ \ Automatic tagging occurs whenever you **change** a value using the editor. This also means that if you enable automatic tagging on a custom field, the tags won't be updated unless you save the custom field with a changed value. \ \ To fix tags for existing values, export the objects and import the exported file unchanged. This will synchronize the tags with the existing values. ACF also offers an API endpoint to trigger the automatic tagging process ### Example You have a selection list of brands as a product custom field with available options like "Hugo Boss", "Tommy Hilfiger", "SuperDry" etc. with automatic tagging enabled.\ \ You then select one of these brands in the dropdown for a given product (or variant) and the constructed value "Brand|Hugo Boss" is applied as a tag to the product (or variant's product) when the custom fields are saved. If you later select another brand, the old tag is removed, and a new one is applied.\ \ Tags can then be used for collection filtering in Shopify when you 'handleize' the value, so this URL will filter a collection for Hugo Boss branded products:\ \