Overview

With this hook, you can programmatically register/add new Listing Builder listing templates, rather than using the plugin interface.

Why register listing templates programmatically?

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

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

Parameters

  • $templates | array | An array of existing listings

How to register a listing programmatically

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

But how to get all available settings for a particular listing? The quickest way to get a complete and up-to-date array of all available settings for a specific listing is to first create the listing in the interface, set all its options, and then export the listing.

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

How to export a listing's settings.
How to export a listing’s settings.
How to quickly convert a listing's exported JSON to a PHP array online.
How to quickly convert a listing’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 into 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 listing’s settings and paste them into the hook code as shown in the examples below.

Examples

To register a new listing named products_listing, add the hook to your (child) theme’s functions.php in the following way.

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_templates', function( $templates ) {

  // add a new 'products_listing' listing to the existing $templates array
  $templates[] = [
    "name" => "products_listing",
    "label" => "products listing",
    "query" => "",
    "template" => "",
    "layout" => [
      "items" => [
        // ...etc.
      ],
      "settings" => [
        // ...etc.
      ]
    ],
    "query_obj" => [
      "post_type" => [
        [
          "label" => "Products",
          "value" => "product"
        ]
      ],
      "posts_per_page" => 10,
      "orderby" => [
        [
          "key" => "title",
          "order" => "ASC",
          "type" => "CHAR"
        ]
      ],
      "filters" => [
      ]
    ],
    "modes" => [
      "display" => "visual",
      "query" => "visual"
    ]
  ] ;

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

To register multiple listings at once, just add another listing to the $templates array. The following example adds two new listings: one named products_listing and another named blog_listing:

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_templates', function( $templates ) {

  // add a new 'products_listing' listing to the existing $templates array
  $templates[] = [

    // settings for this listing
    "name" => "products_listing",
    "label" => "products listing",
    "query" => "",
    "template" => "",
    "layout" => [
      "items" => [
        // ...etc.
      ],
      "settings" => [
        // ...etc.
      ]
    ],
    // ... etc.
  ] ;

  // add a new 'blog_listing' listing to the existing $templates array
  $templates[] = [

    // settings for this listing
    "name" => "blog_listing",
    "label" => "blog listing",
    "query" => "",
    "template" => "",
    "layout" => [
      "items" => [
        // ...
      ],
      "settings" => [
        //... etc.
      ]
    ],
    // ... etc.
  ] ;

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

Locked listings

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

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

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

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

When a listing is registered with the facetwp_templates hook, the listing's settings will be locked.
When a listing is registered with the facetwp_templates hook, the listing’s 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 listing will no longer be registered by your code, but again in the database like a normal listing. After that, changes to the listing settings in the hook will no longer have an effect unless you change the listing’s name in the code, which will then create a new code-registered listing with that name.

See also