Overview

Modify individual values before they’re saved to FacetWP’s index table.

Parameters

  • $params | array | An associative array of data to be indexed (see below)
  • $class | object | The indexer class
How to use custom PHP code?
PHP code can be added to your (child) theme's functions.php file. Alternatively, you can use the Custom Hooks add-on, or a code snippets plugin. More info
$params = [
  'post_id' => 123,
  'facet_name' => 'my_facet',
  'facet_source' => 'tax/category',
  'facet_value' => '45',
  'facet_display_value' => 'My Test Category',
  'term_id' => 0,
  'parent_id' => 0,
  'depth' => 0,
  'variation_id' => 0
];

Usage examples

Index only specific term levels

Index only top-level terms (depth = 0):

How to use custom PHP code?
PHP code can be added to your (child) theme's functions.php file. Alternatively, you can use the Custom Hooks add-on, or a code snippets plugin. More info
add_filter( 'facetwp_index_row', function( $params, $class ) {
  if ( 'my_facet_name' == $params['facet_name'] ) { // replace 'my_facet_name' with the name of your facet
    if ( $params['depth'] > 0 ) {
      $params['facet_value'] = ''; // don't index this row
    }
  }
  return $params;
}, 10, 2 );

Index only the top-level terms (depth = 0) and their direct children (depth = 1):

How to use custom PHP code?
PHP code can be added to your (child) theme's functions.php file. Alternatively, you can use the Custom Hooks add-on, or a code snippets plugin. More info
add_filter( 'facetwp_index_row', function( $params, $class ) {
  if ( 'my_facet_name' == $params['facet_name'] ) { // replace 'my_facet_name' with the name of your facet
    if ( $params['depth'] > 1 ) {
      $params['facet_value'] = ''; // don't index this row
    }
  }
  return $params;
}, 10, 2 );

Index only the first-level direct child terms (depth = 1):

How to use custom PHP code?
PHP code can be added to your (child) theme's functions.php file. Alternatively, you can use the Custom Hooks add-on, or a code snippets plugin. More info
add_filter( 'facetwp_index_row', function( $params, $class ) {
  if ( 'my_facet_name' == $params['facet_name'] ) { // replace 'my_facet_name' with the name of your facet
    if ( $params['depth'] !== 1 ) {
      $params['facet_value'] = ''; // don't index this row
    }
  }

  return $params;
}, 10, 2 );

Note that this will last example will not work when the “Hierarchical” setting is enabled, in Checkboxes, Dropdown and fSelect facets. This is because in that case the facet values are rendered and re-ordered to display the hierarchy itself, which will not work when higher levels are absent.

To prevent one or more posts from being indexed for a certain facet, you can use the following code:

How to use custom PHP code?
PHP code can be added to your (child) theme's functions.php file. Alternatively, you can use the Custom Hooks add-on, or a code snippets plugin. More info
add_filter( 'facetwp_index_row', function( $params, $class ) {
  $post_ids = array( 123, 456, 789 ); // add your post IDs here
  if ( 'my_facet_name' == $params['facet_name'] && in_array( $params['post_id'], $post_ids ) ) { // replace 'my_facet_name' with the name of your facet
    $params['facet_value'] = ''; // don't index this row
  }
  return $params;
}, 10, 2 );

This will exclude the specified posts from the results if they would normally show up when filtering with the specified facet.

Note that this code will not prevent these post(s) from showing up in the unfiltered results. To prevent posts from being in the results at all, you can adapt your query, or use the facetwp_pre_filtered_post_ids hook. Or, if you only want to prevent them from being in the filtered results, no matter which facet is used, you can use the facetwp_filtered_post_ids hook.

Combine facet choices

Combine multiple facet choices into one choice:

How to use custom PHP code?
PHP code can be added to your (child) theme's functions.php file. Alternatively, you can use the Custom Hooks add-on, or a code snippets plugin. More info
add_filter( 'facetwp_index_row', function( $params, $class ) {
  if ( 'fruits' == $params['facet_name'] ) { // Replace 'fruits' with the name of your facet.
    $val = $params['facet_value'];
    if ( 'oranges' == $val || 'grapefruits' == $val || 'lemons' == $val ) { // Replace 'oranges'/'grapefruits'/'lemons' with the facet choices to combine (we use the technical name here). Note that || means OR.
      $params['facet_value'] = 'citrus-fruits'; // Replace 'citrus-fruits' with the new facet_value (technical name/slug). Don't use spaces or special characters.
      $params['facet_display_value'] = 'Citrus Fruits'; // Replace 'Citrus Fruits' with the new facet choice's display name.
    }
  }
  return $params;
}, 10, 2 );

Important to distinguish here is that each facet choice consists of two values that are indexed and stored in the index table. The facet_value is its technical name (“slug”) as it appears in the URL after filtering. And the facet_display_value is the choice’s display value as it shows up in the facet itself in the front-end.

Another thing to notice is that in line 3 and 4 of the above example, we are using facet_value to select the choices that will be combined. You could also use facet_display_value here, as it is available in the hook’s parameters.

Split or add facet choices

This hook can also be used to add new rows to the indexing table, with the insert() function. The following code example splits comma-separated facet values into individual facet values. It then uses the insert() function to enter these values as new rows in the indexing table.

Say you have a facet with a choice apples, oranges, bananas. After implementing the below code, and doing a full re-index, you will now have three facet choices: apples, oranges, and bananas.

How to use custom PHP code?
PHP code can be added to your (child) theme's functions.php file. Alternatively, you can use the Custom Hooks add-on, or a code snippets plugin. More info
add_filter( 'facetwp_index_row', function( $params, $class ) {
  if ( 'my_facet_name' == $params['facet_name'] ) { // Replace 'my_facet_name' with the name of your facet

    // Split the original facetwp_display_value by comma
    $values = explode(",", $params['facet_display_value']);

    // Store each separate value as a new row
    foreach ($values as $value) {
      $value = trim( $value ); // Remove any whitespace from the beginning and end of the new value
      $params['facet_value'] = $value;
      $params['facet_display_value'] = $value;
      $class->insert( $params );
    }
    $params['facet_value'] = ''; // skip the original row
  }
  return $params;
}, 10, 2 );

Create a month/year facet

This hook can also be used to create a facet with years (or months and years) as facet choices.

First, create a facet (for example a Dropdown facet), and set its Data Source to Post Date (or any custom field that stores a date in the YYYY-MM-DD format).

Then add the following code to your (child) theme’s functions.php. Make sure to change my_facet_name to the name of your facet, and re-index:

How to use custom PHP code?
PHP code can be added to your (child) theme's functions.php file. Alternatively, you can use the Custom Hooks add-on, or a code snippets plugin. More info
add_filter( 'facetwp_index_row', function( $params, $class ) {
  if ( 'my_facet_name' == $params['facet_name'] ) { // change "my_facet_name" to the name of your facet
    $raw_value = $params['facet_value'];
    $params['facet_value'] = date( 'Y-m', strtotime( $raw_value ) ); // Use "2023-11" for the facet choice in the URL
    $params['facet_display_value'] = date( 'F Y', strtotime( $raw_value ) ); // Use "November 2023" for the facet choice's display value
  }
  return $params;
}, 10, 2 );

Using this example code, the facet will display choices formatted as November 2023, determined by the F Y format passed in the date() function for the facet_display_value in line 5. When selected, the facet choice will show as 2023-11 in the URL, as set in line 4 with the Y-m format.

These formats can be changed: for example to only show years just use Y. For abbreviated, 3-letter month names, use M instead of F. See PHP’s date() function for more formatting options.

Index a serialized array

Some custom fields store their values as a serialized array, which looks like this:

How to use custom PHP code?
PHP code can be added to your (child) theme's functions.php file. Alternatively, you can use the Custom Hooks add-on, or a code snippets plugin. More info
a:2:{i:0;s:6:"Monday";i:1;s:8:"Thursday";}

FacetWP will recognize some custom field types that do this (like ACF Checkboxes fields) and will automatically unserialize the value while indexing. But this will not always be the case. There are also situations in which FacetWP does not recognize the field as being serialized, for example if a facet uses an ACF Relationship field or Post Object field as its data source, and the related field is a field that stores its data serialized, like an ACF Checkboxes field.

In these situations, you can use the facetwp_index_row hook as shown in the example below. To index each value within a serialized array, it first needs to be unserialized. Then each value in the array can be inserted individually into the database. And last but not least, the original (serialized) value needs to be skipped over:

How to use custom PHP code?
PHP code can be added to your (child) theme's functions.php file. Alternatively, you can use the Custom Hooks add-on, or a code snippets plugin. More info
add_filter( 'facetwp_index_row', function( $params, $class ) {
  if ( 'my_facet_name' == $params['facet_name'] ) {  // Replace 'my_facet_name' with the name of your facet
    $values = maybe_unserialize( $params['facet_value'] );
    if ( is_array( $values ) && ! empty( $values ) ) {
      foreach ( $values as $value ) {
        $params['facet_value'] = $value; // Set the choice's technical value (as seen in the URL).
        $params['facet_display_value'] = $value; // set the choice's display value (as seen in the facet).
        $class->insert( $params ); // insert each new value into the database as a new row.
      }
      $params['facet_value'] = ''; // skip the original row, by setting the technical value to nothing.
    }
  }
  return $params;
}, 10, 2 );

More examples

Other notes

  • facet_value is used for the URL / permalink
  • facet_display_value is used as the label (front-end)
  • To skip the current row, set facet_value to an empty string.

See also