Connect to ACF fields (Themer)

Beaver Themer lets you set field connections or field connection shortcodes to grab the contents of custom fields that you've created with the Advanced Custom Fields (ACF) plugin (free or premium). You can also use these field connection shortcodes in custom layouts in the Posts module, and as long as you have Beaver Themer installed, these field connections are available in regular Beaver Builder layouts as well as Themer layouts.

Here are the sections that follow in this article:

ACF field connection example

Here's an example of using field connections to ACF fields to assist your clients with edits, with more details about implementation in the following sections.

Suppose you have a client who has a Call to Action on their home page that they want to modify frequently. To make it easy for them to manage the information in the back end of the site (shown in the following screenshot), you've created an ACF options page with a group of four ACF fields: a headline, a blurb, an image, and a button label.

To display these fields on the front end, you create a layout in Beaver Builder with connections to these ACF fields, using a Heading module, Text Editor module, Photo module, and Button module respectively. This way, the client only needs to provide the content, while the layout and style are created automatically.

You could even let the client choose colors for the background, text, and button, using a Color Picker custom field.

Tip: As long as Beaver Themer is installed, field connections are available in both regular Beaver Builder layouts and Themer layouts, so you have many options in where and how you choose to display custom fields. You can put this callout example into a Part-type Themer layout, which you can assign to a specific position outside the content area on any pages you specify. If you want the custom field to appear inside the content area of a regular Beaver Builder layout, you can use a field connection in a regular Beaver Builder layout, and then save the row, column, or module to reuse it. Or, if the site makes use of layout templates for consistency across pages, you can add it there.

ACF field connection choices

When the ACF plugin is installed, the list of field connections in Beaver Builder modules displays an Advanced Custom Fields section. The choices in this section are not the ACF field types themselves but rather where the field will be pulled from or placed in your site, as described in the following sections. This screenshot shows most of ACF field connection items – in this case, generated by the HTML module in a Part-type Themer layout.

Which of these ACF field connection choices appear in the list depends on the row, column or module setting that generates the field connection list (text, image, etc.) and the type of page the layout applies to (archive, single post, and so on).

The Connect and Insert buttons appear as you mouse over categories in the list, and they insert a field connection or field connection shortcode respectively. See the general overviews about field connections and field connection shortcodes for more information.

Once you've chosen an item in the ACF field connection list, a new settings box appears, in which you choose the ACF field type and add the field name, which is usually text separated by underscores. There may also be other options, depending on the ACF field type and the Beaver Builder setting. For example, if you select an ACF Image field type, there's also an image size setting you can choose, as shown in this screenshot.

For the Checkbox and Select ACF types, the field connection has a Format choice for how it will appear on the published page: as text, an ordered list, or an unordered list.

ACF field connection choices in the UI

Here's a list of the field connection items that most commonly appear in the Advanced Custom Fields section when you click the Plus icon in Beaver Builder. Other ACF field connection choices may appear for particular Beaver Builder settings. For examples, see the Gallery and Color sections in the Tips section below.

ACF Post Field
ACF Post Field - Photo
ACF Post Field - URL

Choose this item if your ACF field group's Location setting is any choice in the Post or Page category. The next screen will ask you to provide the ACF custom field type and field name. Some custom field types have extra options, such as image size for Image field types or output type (text, ordered list, unordered list) for Checkbox and Select field types.

The ACF Post Field - Photo choice appears when you are setting up a field connection for an image setting in Beaver Builder.

Choose ACF Post Field - URL when you want to return the URL for an image itself, though like the ACF Archive Field, if you insert a field connection shortcode into a text field or a custom post layout, you'll get the URL of the image for ACF Post Field as well as ACF Post Field - URL.

ACF Post Author field
ACF Post Author Field - Photo

Select this item when you have the ACF field group location set to User Form and you want to display the value of an ACF field from the user form for the author of the post being displayed.

The ACF Post User Field can also display the value of a custom field on the user form, but there's a difference. The ACF Post Author Field always displays the value of that field for the post author, while the ACF User field displays the value of the field for the user who's logged in. See the example for the ACF User Field in the next section.

The ACF Post Author Field - Photo choice appears when you are setting up a field connection for an image setting in Beaver Builder.

ACF User field
ACF User Field - Photo

Choose this category when you have assigned the ACF field group location to any item in the User category. If the location is set to User Form, the field appears on the user forms that you specify.

Here's an example that shows the difference between ACF Post Author Field and ACF User Field. We created a field group in ACF called Post Author Test, then created one field, also labeled Post Author Test, and assigned this field to all user forms in the Location section, as shown in this screenshot.

Now if you open any WordPress user's form, it displays this field group. The following screenshot shows a value of the Post Author Test field that we added for an admin in that user's form.

Then we created a post with that same admin as the author, and in a Singular Themer layout we set up two field connection shortcodes to that custom field – one using an ACF Post Author Field shortcode, the other using an ACF User Field shortcode. You can see the difference in the following screenshots.

With the admin who's the post author logged in, both shortcodes display the same custom field value in the post:

With another user logged in, the two shortcodes display different field values:

With nobody logged in, the ACF Post User Field value is blank:

The ACF User Field - Photo choice appears when you are setting up a field connection for an image setting in Beaver Builder.

ACF Option field
ACF Option Field - Photo

Choose this option when you have created one or more Options pages for the field you want to use. Choosing this category tells Themer to look on the options pages for the field and the value.

The ACF Option Field - Photo choice appears when you are setting up a field connection for an image setting in Beaver Builder.

ACF Relational

Use this category for ACF Relationship fields. See this article for more information.

ACF Archive Field
ACF Archive Field - Photo
ACF Archive Field - URL

Most of the other choices in this list relate to the source location of the custom field, which is dictated by the location you specify for the custom field in ACF. The ACF Archive Field choice is different, in that it's used when the target to display the custom field is an archive.

As you might guess, this causes some overlap. For example, if you have a custom field located in a post and the target to display the value is on an archive page, then either ACF Post Field or ACF Archive Field works to display the value. We suggest that the easiest way to remember the difference is to use the ACF Archive Field choice when the other choices don't apply.

Most often, you need the ACF Archive Field choice when you have an ACF field that appears on a custom taxonomy page (which means the Location choice for the custom field is Taxonomy).

For example, suppose you've created a custom taxonomy called House type that's associated with a custom post type called House. You want to be able to upload an image for each house type in the taxonomy, so in ACF you create a custom Image field named house_type_image and assign the location to Taxonomy = House Type. In this screenshot, you can see the custom field at the bottom of the edit page.

Then you want the custom image to appear on the archive page for every taxonomy item. Create a Themer Archive layout specifically for House Type archives by specifying the taxonomy as the location:

Open the Themer layout in Beaver Builder, then open the Row settings for the taxonomy title. In the Row background section, click the Plus icon, then in the Advanced Custom Fields section of the field connections list choose ACF Archive Field - Photo. On the next settings screen, choose Image as the field type, enter the field name house_type_image, and select the image size you want. The correct image will appear in the row background for each house type archive page, for example:

To return the image's URL instead of the image itself (or the URL of another field type that requires an upload), use an HTML module and choose ACF Archive Field - URL, either as a field connection or as a shortcode.

Note: Field connections for text field settings (such as a heading) and field connection shortcodes always return text, so ACF Image-type custom fields return the URL rather than the image itself, whether you use ACF Archive Field or ACF Archive Field - URL. In a custom post layout in a Posts module with shortcode for an ACF Image field type, your HTML could look like this:

If instead you wanted to insert this image into a custom post layout, you could use the following code:

[wpbb-if archive:acf type='image' name='house_type_image']
<div class="fl-post-image">
	<img src="[wpbb archive:acf type='image' name='house_type_image' image_size='medium']">
</div>
[/wpbb-if]

In this code, the conditional shortcode in the first line ensures that the HTML markup for the image is only rendered when this custom ACF field has a value. If the ACF field is empty, the entire <div> is ignored.

Other ACF field types available as shortcodes only

The following field types do not appear in the UI in the list of field connections but can be used as shortcodes.

ACF Repeater field

See this article for how to use a repeater field as a shortcode.

ACF Flexible Content field

See this article for how to use a flexible content field as a shortcode.

Tips for using ACF field connections

Match data types

The ACF custom field data type should match the Beaver Builder row, column, or module setting data type. Here are some examples.

Text and shortcodes

Use ACF Text field types in row, column, or module settings that take text, such as any heading or label field or any module with a text editor.

Note: If you insert a field connection or shortcode for an ACF Image field into a Beaver Builder text field, or insert a field connection shortcode into a Beaver Builder custom post layout, the URL of the image is returned, not the image itself. To create a link of the URL, or to display the image, add the appropriate HTML markup into the text field or custom layout. You could even insert an image into Heading field by adding the shortcode for an image and wrapping it in <img src="[acf-field-shortcode-goes-here]"/>

Galleries

For example, you can only add an ACF field of type Gallery to a Gallery module. You won't see an option to select an ACF Gallery field type anywhere else in the Beaver Builder UI. Here's a screenshot of a Singular Themer layout for a custom post type with an ACF Gallery field.

Colors

You can set a field connection for most color settings in Beaver Builder. For example, you can set a custom color background for a row in a Singular Themer layout. The screenshot shows that the field connection choices are all related to Color, which means the ACF field type should be Color Picker.

ACF Group field types

If you have an ACF Group field type with subfields, use the group name as a prefix for each subfield, separated by an underscore, such as mygroup_mysubfield1.