What is the Listing Builder?

FacetWP’s Listing Builder allows you to quickly and visually design a results listing.

It is a convenient alternative to building your own WP archive pages or Custom WP_Query loops.

After building the listing template, you can display it on any WordPress page with a shortcode, or include it in an archive page with a PHP include. Then put any number of facets on the page to interact with it.

It is even possible to have multiple listing templates on the same page: one being the dynamic listing that the facets on the page interact with, the others being “static” listings.

If you prefer to code your post loops and query arguments by hand, you can still take advantage of the Listing Builder by using its Dev mode.

Create a listing template

Browse to Settings > FacetWP, click the “Listings” tab and then “Add new”.

The Listing Builder is covered in the video below, starting at 1:49.

Using Dev mode

FacetWP Listing Builder Dev ModeNew templates use the “visual” Listing Builder by default. However, if you need more flexibility and you’re experienced in WordPress coding, you can switch both the “Display” and “Query” tabs independently from each other to “Dev mode”, by clicking the checkbox on the right.

In Dev mode, you can use PHP to build the listing template output and the query arguments.

Using dynamic tags

Within the Listing Builder you can use so-called “dynamic tags”, which are very useful in building more sophisticated layouts of the retrieved individual posts. A dynamic tag lets you pull in all kinds of post data, to be used in for example an HTML builder item or in a builder item’s setting field.

Besides the set of built-in tags the Listing Builder comes with, you can use your own tags, created from custom fields within the Listing Builder itself.

For more complex needs it is also possible to create custom tags by modifying the output of existing tags or by writing them from scratch.

Built-in dynamic tags

The following built-in tags are available:

Tag Output
{{ post:id }} Returns the post’s id
{{ post:name }} Returns the post’s name / title
{{ post:type }} Returns the post’s type
{{ post:url }} Returns the post’s url
{{ post:image }} Returns the post’s featured image (in “full” size).
If you need another WordPress image size, you can can use the facetwp_builder_dynamic_tag_value hook.

Create dynamic tags within the Listing Builder

By creating a dynamic tag in the Listing Builder itself, you can pull in a post’s custom field value into a builder item’s field or setting.

The way this works is that you create a hidden builder item from the custom field you want to pull the value from, and use it’s “Name” as the dynamic tag name, to be used in other builder items’ fields. This may sound complicated but it’s actually very easy:

Let’s say you have a photo_url custom field and you want to wrap it into an <a> tag:

  1. First, add a new builder item and select the desired field:
Selecting the item source in the Listing Builder
Creating a dynamic tag from a custom field in the Listing Builder.
  1. Next, enter photo-url in the builder item’s “Name” field and click the “Hide item” checkbox. In the builder, the item will become greyed-out with a “hidden” icon next to it, and this item will be hidden on the front-end. We hide it because this builder item is only used to generate the dynamic tag: the content of its “Name” field becomes the dynamic tag: {{ photo-url }}.
  2. Finally, add a new HTML builder item and set its “Content” to:
<a href="{{ photo-url }}">{{ photo-url }}</a>
Selecting the item source in the Listing Builder
Adding a dynamic tag to the “Content” field of an HTML item in the Listing Builder.

FacetWP will now automatically replace all instances of {{ photo-url }} with the custom field’s value. You can even pull in multiple fields.

Create or modify custom dynamic tags

It is also possible to modify existing dynamic tags or create your own custom tags from scratch.

There are two hooks available for this (with the second one being the more efficient of the two):

You could for example create a tag to pull in content from a custom field and modify it. Or a tag to output the featured image url in any (default or custom) WordPress image size.

Besides modifying the output of built-in tags, you can also modify the dynamic tags you made within the Listing Builder itself. An example of this would be to modify a dynamic tag that pulls in data from a Price custom field, so that the output value of the tag is prepended with a currency sign.

See the above hook pages for mor examples.

Display a listing template

Copy the shortcode

Copy shortcode buttonCopy shortcode in listings overviewAfter creating the listing template, click the red “Copy shortcode” button.

It’s also possible to copy shortcodes directly from the Listings screen. Click the cog/gear icon on the right side of the listing’s row and click “Copy shortcode” in the dropdown.

You can also create your shortcode manually, using the listing name (the name in the grey box). Each listing’s shortcode looks like this:

[facetwp template="the_listing_name"]

Place the shortcode

Place FacetWP shortcode into a WP block editor Shortcode block
How to past a facet or listing shortcode into a WP Shortcode block.

Paste the shortcode into the body field of your page, or into Text widgets (Appearance > Widgets).

If you’re using the WordPress block editor, you can also paste shortcodes into a Shortcode block.

Display a listing template with PHP

Listing templates can also be placed directly in your WordPress archive templates, custom templates or includes, with PHP:

echo facetwp_display('template','the_listing_name');

Multiple listing templates on the same page

Introduced in FacetWP v4.0 is the possibility to add more than one listing template to the same page.

Each listing template can have its own grid layout, styling, and query. But only one of them can be “dynamic” and will react to the facets on the page. The others have to be “static” listing templates and will not react to facets.

Display static listing templates

Static listing templates can be added with a shortcode similar to dynamic templates, but with an extra “static” attribute:

[facetwp template="the_listing_name" static]

Static listing templates can also be placed directly in your WordPress archive templates, custom templates or includes, with PHP:

echo facetwp_display('template','the_listing_name', [ 'static' => true ]);

Using shortcodes in HTML items

A handy feature worth mentioning is that you can add your own shortcodes to the “Content” field of an HTML item. Shortcodes will be automatically parsed when the listing template is displayed:

Parsing shortcodes in an HTML item in the Listing Builder
How to use shortcodes in an HTML item in the Listing Builder

Responsive support

By default, the Listing Builder automatically changes to 1 column when the browser width <= 480 pixels. You can add additional “breakpoints” via CSS. For example, this CSS switches the layout to 2-columns if the browser width <= 780 pixels:

@media (max-width: 780px) {
    body .facetwp-template .fwpl-layout, 
    body .facetwp-template-static .fwpl-layout {
        grid-template-columns: repeat(2, 1fr);
    }
}

Hide empty items

The layout builder automatically adds the CSS class is-empty to any items that contain no value. You could use this (within your theme’s style.css) to hide these empty container elements with CSS, e.g.

.fwpl-item.is-empty {
    display: none;
}

How to duplicate a listing template

Duplicate, copy or clone a FacetWP listing template Since FacetWP v4.0 it is very easy to clone/duplicate a listing template, including all its settings:

Go to Settings > FacetWP and click the Listings tab. On the right side of the listing template you want to clone, click the cog/gear icon and click “Duplicate”. This instantly creates a full copy of the listing template and its settings, with the label and facet name having the word “copy” added.

You can then change the new template’s label, name and settings and click “Save changes”.

See also