Advanced Custom Fields

Oxygen has built-in support for Advanced Custom Fields. Nothing to install or connect:
if ACF is active, your fields appear in the dynamic data chooser under an ACF category,
grouped by the ACF field group they belong to.

This page covers what that integration actually gives you — which field types map to what,
how repeaters work, and how to drive a loop from a relationship field.

Create your fields in ACF and put real data in at least one post before you start. Oxygen
reads the field definitions, so an empty field group gives you nothing to bind to and
nothing to preview against.

Using an ACF field

1. Select an element and find the control you want to fill — text, an image source, a link
   URL.
2. Click the dynamic data button on that control.
3. Open the ACF category. Your fields are listed under the name of the ACF field group
   that contains them.
4. Pick the field.

That's the whole workflow, and it's the same one described in
Dynamic Data — ACF fields are ordinary dynamic
fields once registered.

Note: the chooser only offers fields the control can accept. Binding an image source
shows image-shaped fields; binding a text control shows text-shaped ones. If a field you
expect is missing, you are probably on a control that can't take it.

How ACF field types map

This is the part worth knowing, because it explains something confusing: one ACF field
can produce more than one entry in the chooser.

An ACF URL field, for example, registers three: the plain value, an image, and an oEmbed.
All three carry the label you gave the field in ACF, so they are identical in the list —
the only thing separating them is the kind of value each returns. That sounds worse than it
is in practice, because the chooser filters by what the control accepts: bind an image
source and only the image one is offered.

The rule of thumb is to open the chooser from the control that needs the value, rather than
picking a field first and hoping it fits.

ACF field type	What Oxygen registers
Text, Textarea, Number, Range, Select, Radio, Button Group, True/False, Date, Colour, and anything not listed below	A single value field
Image	Image · Image URL
File	File · File as image · File as oEmbed
URL	Value · Image · oEmbed
Email	Value · Email
oEmbed	oEmbed
Gallery	Gallery · Gallery image
Google Map	Google Map
Link	Link
Post Object	Post · Post featured image
Page Link	Page link · Page link post
Taxonomy	Taxonomy
User	User
Checkbox, Radio, Button Group, Select	Choice field
Group	Group
Repeater	Repeater
Flexible Content	Flexible content

Four ACF field types are deliberately ignored and never appear in the chooser:
Message, Tab, Accordion, and Clone. The first three are layout devices in
the ACF admin rather than data, so there is nothing to bind.

Clone is the one to know about, because it's excluded by choice rather than by
availability: even on ACF PRO, where Clone works perfectly well, Oxygen registers nothing
for it. If you rely on cloned fields, bind the original fields instead — they're still
there under their own field group.

Tip: repeaters don't appear in the ACF category either. They get their own
Repeaters category and are chosen from the Repeater Field element rather than from a
control's dynamic data button — see below. Flexible Content is separate again.

Note: four of these types are ACF PRO features — Repeater, Flexible
Content, Gallery and Clone. On free ACF those field types don't exist, so the
corresponding Oxygen entries never appear. That is the integration working correctly,
not a missing feature. Group is not one of them — it ships in free ACF, so grouped
fields work on any ACF install.

Repeater fields

An ACF Repeater is a list of rows on a single post, and Oxygen renders it with the
Repeater Field element.

1. Build the row design as a Component. Go to Oxygen → Components, create one, and
   bind its elements to the repeater's subfields. One Component describes one row.
2. Add a Repeater Field element to the page or template.
3. In Content → Repeated Block, choose the Component from step 1.
4. In Content → Field → Repeater Field, choose your ACF repeater. Entries read as the
   repeater's name followed by its field group in brackets — Team Members (Page Details).
5. Lay the rows out with Design → List — a repeater can be a grid, slider, accordion or
   tabs, not only a list.

The rows render in the builder canvas and on the front end.

Because the Repeater Field is a loop like any other, it also gets
alternate and static items and an
empty state — the last is worth setting here, since an
optional repeater is empty on most posts.

Caution: build the row Component from the repeater's subfields, and build the empty
state Component from static content only. A Component that binds post fields breaks
when rendered without a post in context, and takes the page down rather than rendering
blank.

Note: ACF's Repeater is a PRO field. On free ACF there are no repeaters to
choose and the Repeater Field element's dropdown is empty.

Relationship fields as a query source

A Post Loop can take its posts straight from an ACF
Relationship field — "show the products related to this post", without writing a query.

1. Select the Post Loop and open Content → Query.
2. Choose the Custom mode and open the Query Builder.
3. Set Source to ACF Relationship. This option only appears when ACF is active.
4. Pick your relationship field from the Field dropdown. If it reads "No relationship
   fields found", there are no relationship fields registered on the site.
5. Apply Query.

The loop now renders whatever that field points at on the current post, and it tracks the
field — change the relationships in ACF and the loop follows, with no edit in Oxygen.

Three things behave differently on this source, and all three surprise people:

• Pagination does not work. Oxygen explicitly discards the page number for a
  relationship query, so every page would show the same rows. If you need paging over a
  relationship, use an Array query instead and return the related post IDs yourself.
• Conditions don't apply. The Query Builder's Conditions section only filters the
  Post Types source. On a relationship source it has no effect — the field defines the
  set.
• Order and dates still work. Order By, Order, and the Before/After date filters all
  apply on top of the related posts, so you can show the three most recent related items.

A relationship source returns published items of any post type, and defaults to three per
page rather than the usual eight — set Posts per page if you want more.

Tip: an empty relationship field returns nothing at all, deliberately — Oxygen
forces an empty result rather than letting WordPress fall back to "every post", which is
what an empty ID list would otherwise mean. That makes an
empty state genuinely useful on a related-posts loop.

Ordering a loop by an ACF field

Any Post Loop can sort by an ACF value. In the Query Builder's Order section, set
Order By to ACF — an extra Field chooser appears for picking which one — then
set Order to ascending or descending.

The ACF entry in Order By only appears when ACF is active.