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.

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 );

Index a serialized array

Index each value within a serialized array:

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 ( 'your_serialized_field_name' == $params['facet_name'] ) {
    $values = maybe_unserialize( $params['facet_value'] );
    if ( is_array( $values ) && ! empty( $values ) ) {
      foreach ( $values as $value ) {
        $params['facet_value'] = $value;
        $params['facet_display_value'] = $value;
        $class->insert( $params ); // insert new value to the database
      }
      $params['facet_value'] = ''; // skip the original row
    }
  }
  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