FacetWP includes built-in support for Advanced Custom Fields (ACF). It supports basic field types (Text, Select, Checkbox, etc.), Relationship fields and even Repeater sub-fields.

Create your field group

The first step is to create an ACF field group. In the screenshot below, we’re adding a new “Event Fields” group, and attaching it to the Event post type.

ACF field group

Use your field group

After you’ve added your field group, the next step would be to add some content. Edit some of your posts to make sure that your fields are appearing correctly.

post edit screen

Create your facet

After you’ve added some content using your new custom fields, go to Settings > FacetWP, click the Facets tab, then click the Add New button.

For the facet’s Data source, scroll down until you see the Advanced Custom Fields header, then select the appropriate choice.

FacetWP data source dropdown

Alternatively, use the built-in search box for quickly finding the desired field.

FacetWP data source search

Repeater fields

Facets can be added using data from repeater sub-fields.

Repeater values are tied back to the parent post. This means that repeater rows aren’t directly filterable.

For example, let’s say you have a “Speakers” facet based on a repeater field:

If the user selects “Jim”, the other choices (Bob, Dan) will remain too. This is because the 3 choices are tied to the parent post.

Taxonomy term custom fields

With Advanced Custom Fields you can add custom fields to taxonomy terms. (The same is true for the Pods plugin, the instructions mentioned here are the same.)

When you set such a custom term field as the data source in a facet, you will notice that the facet does not display any choices. This is because custom fields attached to taxonomy terms cannot be indexed directly by FacetWP.

However, with a bit of custom code, using a custom term field as data source is possible.

First, create the facet and set its data source to the taxonomy itself. Then, add the following code to your (child) theme’s function.php. Make sure to re-index afterwards.

/**
 * This code works for ACF and Pods.
 * 1. Replace "your_facet_name" with the actual facet name
 * 2. Replace "your_custom_field" with the actual custom field name
 * 3. Re-index afterwards
 */

add_filter( 'facetwp_index_row', function( $params, $class ) {

  if ( 'your_facet_name' == $params['facet_name'] ) {

    // Get the taxonomy term
    $term_id = (int) $params['term_id'];

    // Get the custom field value from the term
    $value = get_term_meta( $term_id, 'your_custom_field', true );

    // Set the facet_display_value to the custom term field value. Normally for a term this is the term name
    $params['facet_display_value'] = $value; // facet_display_value is used for the facet's choices

    // Optional, use with caution. Set the facet_value to the custom term field value. Normally for a term this is the term slug
    // $params['facet_value'] = $value; // facet_value is used for the facet's filtering and in the url
  }

  return $params;
}, 10, 2 );

What this code does, is force FacetWP into indexing the custom term field value instead of the term name (and/or optionally the term slug). When using this, keep the following in mind:

Normally, when FacetWP indexes a taxonomy term, the following happens:

  • Term names are stored in FacetWP’s index table as facet_display_value and used to generate the display of the facet’s choices.
  • Term slugs are stored in FacetWP’s index table as facet_value and are used for filtering, which means they will show up in the url after interacting with the facet.

The above code replaces facet_display_value with the custom field’s value while indexing, and ignores the term name. The term slug is still used.

You could choose to also replace the facet_value with the custom term field value. Use this with caution, because the facet_value is used internally for filtering and the url. Special characters or spaces are replaced when the value is indexed, or it gets entirely hashed into a string of random characters.

Using Advanced Custom Fields with a Map facet or Proximity facet

If you are using Advanced Custom Fields with a Map facet or Proximity facet, you can use ACF’s Google Map field type to attach a location to your posts. If you use this ACF field, in the Map / Proximity facet’s “Data source” settings choose this field underneath the “ACF” header.

If you need multiple locations per post, wrap your ACF Google Map field within a Repeater field.

See also