Dev Docs

# Page Builder (ACF)

# Module Field Groups

All Module Field Groups must be created as standalone field groups in ACF, by cloning the Module: YOUR_MODULE_CLONE_ME field group. Then, in the Page Builder field group you need to add a child Clone field in the existing Flexible Content field.

Module Field groups should be left in the "Disabled" state so that they don't render anywhere.

# Content vs Setting tabs

For the module field group, remember to separate Content fields (stuff that is shown on screen like copy, images, labels, etc) and Settings (options to configure module behaviour, such as visual variants, interactive features or mobile-specific settings).

# Reusable components

Make sure that you are not duplicating existing work when working on isolated inner components of a module, we have a standard set of ACF fields for components such as Media (Image & Video) and Call to Actions, see Reusable Components .

# Naming Fields & UI Guidelines

When naming fields, look at existing similar modules and try to re-use as much terminology as possible.

General guidelines:

  • ❌ Avoid using question marks in field names. Show in Nav is better than Show in Nav?.

  • ✅ Add Field Instructions where necessary, if a field may be confusing or ambiguous it is a good candidate for having description/instructions included.

  • ✅ Use Title Case (opens new window) for naming fields.

  • ✅ Make use of default values where it makes sense. All "Choice" fields (True/False, Select, Button Group, etc) must have a default value.

  • ✅ Use required fields and validations where necessary. Think "will this module just break or look very wrong if it's missing this field?" if so, make it required. Some examples:

    • for Sliders/Carousels: require at least 1 slide, require an image if its used as background. Consider a max limit of slides if design overflow is possible.
    • for Local Maps: for the ones plotting points on top of a map, require at least 1 such point
    • for accessibility labels: if you need an accessible name (e.g. aria-label) and cannot derive from context, require the users to input one

  • ✅ Always check if fields are set (for optional fields) to avoid outputting empty markup

    @if(!empty($headline))
<h2>{{ $headline }}</h2>
@endif

  • ✅ For areas where text overflow might occur or if intended by design directions, add text/character limits to the field. If using WYSIWYG, you will need to cut the resulting length with something like wp_trim_words (opens new window). It is very important to understand that most fonts used in designs are variable-length, so you should test for the worst case by using wider letters such as W, i.e. limit the field length based on how many capital Ws fit in the desired space.

    • If it is requested for some text in a field to go above the limit, and it would negatively impact visuals, you need to ask a designer for a potential fix/workaround

Here are some good field names to start with:

  • Headline - for things that are meant to render in h1 or h2 tags, avoid using Title for this purpose.
  • Subtitle - for h3 - h4 tags, should come after a Headline.
  • Label - for non-heading content, use this for labels in and archive, "three-column" module, CTAs, Tab labels, etc.
  • Copy - for main WYSIWYG content
  • Caption - for captions in figures such as images, carousel slides, tables, etc
  • Display on Mobile / Hide on Mobile
  • URL
  • Style - for a dropdown or button group of alternate modules styles/variants
  • Visible / Hidden
  • Opens in New Window
  • Media / Featured Media / Gallery
  • Slides
  • Has Dropdown
  • Selection: Manual Selection / Automatic Selection

As for ACF UX settings:

  • ✅ For Choice (True/False) fields, always use the Stylized UI option.
  • ✅ Use Button Groups when selecting between 1-4 four options that fit a row on a medium (Tablet) resolution. Use a Select otherwise.
  • ❌ Avoid oEmbed, Gallery, Radio Button, Checkbox and Color Picker

# Clone Field Limitation

When using Clone fields, keep in mind that there is an existing limitation in ACF's Clone Field (opens new window) where you can't clone the same field twice at the same "level" in a field group, or use different Clones that when replaced result in field names colliding.

Let's say you want to use aMedia and a Image field inside your module's field group, if you just clone both of these you'll notice that changes are not persisted in both fields: one field will always override the other. This is because both Media and Image have similarly named fields internally (e.g. img_lg).

To avoid this, whenever cloning 2 similar field groups make sure to create a Group field first, and then use a " Seamless" Clone field as the only child of that Group field.

← Authenticating with Github Packages →