Overview

With this hook, you can programmatically register/add new facets, rather than using the plugin interface.

Why register facets programmatically?

Here are several reasons why you may want to register your facets in code:

  • To prevent users from changing facet settings. Facets that are added this way will appear as “locked facets” in the plugin settings. While this does not absolutely prevent users from changing the facet settings, it will take a deliberate “unlock” action to do so.
  • You can have your facets and their settings under version control (e.g. with git). This way you can revert to previous sets of facets or previous facet settings.
  • If your facets and settings are tied to a theme, anyone using the code/theme automatically has the registered facets and their settings.
  • If you are using FacetWP with WordPress multi-site, all sites in the multi-site network can have the same facets and facet settings, as long as they are using the same theme. You no longer have to change facet settings in each site separately, and you can maintain them in one place: the theme’s functions.php file.

Parameters

  • $facets | array | An array of existing facets

How to register a facet programmatically

The examples below show that to register a facet in code, you need to pass an array of the facet’s settings to the hook.

But how to get all available settings for a particular facet type? Every facet at least has a label, name, and type. Most facet types have a source. But the rest of the settings depend on the facet type.

You could check this (incomplete) overview. But the quickest way to get a complete and up-to-date array of all available settings for any given facet type is to first create the facet in the interface, set all its options, and then export the facet.

To do so, go to Settings > FacetWP > Settings > Import/Export, select one or more facets and click the “Export” button:

How to export a facet's settings.
How to export a facet’s settings.
How to quickly convert a facet's exported JSON to a PHP array online.
How to quickly convert a facet’s exported JSON to a PHP array online.

Copy the exported code that appears in the text box (which is in JSON format) and decode it to a PHP array.

A quick way to do this is to paste it into an online JSON to PHP array converter like https://jsontophp.com.

Copy the converted PHP array’s key/value pairs with all the facet’s settings and paste them into the hook code as shown in the examples below.

Examples

To register a new Search facet named my_search, add the following code to your (child) theme’s functions.php:

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_facets', function( $facets ) {

  // add a new 'my_search' facet to the existing $facets array
  $facets[] = [
    // settings for this facet
    'label' => 'My Search',
    'name' => 'my_search',
    'type' => 'search',
    'search_engine' => '',
    'placeholder' => 'Enter keywords',
  ];

  // return the modified $facets array
  return $facets;
}, 10, 1 );

To register multiple facets at once, just add another facet to the $facets array. The following example adds two new facets: a Checkboxes facet named categories and a Search facet named my_search:

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_facets', function( $facets ) {

  // add a new 'categories' facet to the existing $facets array
  $facets[] = [
    // settings for this facet
    'label' => 'Categories',
    'name' => 'categories',
    'type' => 'checkboxes',
    'source' => 'tax/category',
    'parent_term' => '',
    'hierarchical' => 'no',
    'orderby' => 'count',
    'count' => '20',
    'show_expanded' => 'no',
    'ghosts' => 'no',
    'preserve_ghosts' => 'no',
    'operator' => 'and',
    'soft_limit' => '5'
  ];

  // add a new 'my_search' facet to the existing $facets array
  $facets[] = [
    // settings for this facet
    'label' => 'My Search',
    'name' => 'my_search',
    'type' => 'search',
    'search_engine' => '',
    'placeholder' => 'Enter keywords',
  ];

  // return the modified $facets array
  return $facets;
}, 10, 1 );

Locked facets

After registering a facet with this hook, it will appear in FacetWP’s Facets overview with a “locked” icon:

When a facet is registered with the facetwp_facets hook, the facet label will have a 'locked' icon.
When a facet is registered with the facetwp_facets hook, the facet label will have a ‘locked’ icon.

If the new facet does not appear, make sure its name is unique and not already used for another facet.

The settings screen of a locked facet will have a red “This facet is registered in code. Click to allow edits” warning on top, and the settings will be dimmed:

WWhen a facet is registered with the facetwp_facets hook, the facet settings will be locked.
When a facet is registered with the facetwp_facets hook, the facet settings will be locked.

When you click the lock icon, and then change the settings (or leave the settings as they are) and click “Save changes”, the facet will no longer be registered by your code, but again in the database like a normal facet. After that, changes to the facet settings in the hook will no longer have an effect unless you change the facet’s name in the code, which will then create a new code-registered facet with that name.

See also