Tutorials

Create faceted post archive with "Loops & Facets" module in a minute

Elvis Krstulović

NOTICE! Link to video tutorial on the bottom of the post.

With Builderius 0.12 release we introduce a composite module called Loops & Facets. In this short tutorial I will demonstrate how you can use it to create advanced loop with facets only with Builderius.

Make sure you have prepared some posts and have at least two categories to work with. Assign one of these per post so we can see the results of faceted filtering.

Admin posts page with category terms applied

1. Adding GraphQL Snippet

Open the template (see how to create template here) by clicking on its name. Once in the builder let’s prepare our query to use it with our module. Create our DataVar in the template scope which will make it available to this Template only, or if we intend to use it accross the site, we can add it to Global scope.

Creating DataVar in Builder UI, click on Template scope first, then data settins, then Edit Data Variables button.

Inside the DataVar modal chose “New”, then choose GraphQL and give it any name (I named it archive).

Modal showing type select field with GraphQL option highlighted

Copy this GraphQL query to your clipboard and paste it to the code editor.

{  
  # taxonomy terms loop
  taxonomy: terms (
    query: {
      taxonomy: "category"
      hide_empty: true
      }
  ) @private {
    terms: nodes {
      id: term_id 
      slug @private
      name
    }
  }
  # labels for facets
  terms: expression_result(expression: "{{ unshift(taxonomy.terms, {'id':0, 'name':'All Terms'}) }}")
  # posts loop
  loop: posts (
    query: {
      post_type: ["post", "cpt-name"]
      }
  ) @private {
    posts: nodes {
      id: ID
      type: post_type
      post_title
      permalink
      author: post_author {
        id: ID
        name: display_name
      }
      img: featured_image @private {
        medium: file_url(size: MEDIUM)
        alt_text
      }
      # prepared for loop & facets module
      image: expression_result(expression: "{{{img.medium}}}")
      image_alt: expression_result(expression: "{{{img.alt_text}}}")
      
      taxonomy: terms(
        query: {
              object_ids: "{{{id}}}"
              taxonomy: "category"
            }
          ) @private {
          terms: nodes {
              id: term_id
              name
          }
      }
      # for filter module
      terms_ids: expression_result( expression: "{{foreach(taxonomy.terms, (v) -> {v.id })}}" )
      # for term names display
      terms_names: expression_result( expression: "{{foreach(taxonomy.terms, (v) -> {v.name })}}" )
    }
  }
  post_loop: expression_result(expression: "{{{loop.posts}}}")
}
GraphQL code in the DataVar modal.

Hit “Apply changes”, close the modal and then hit “Save”.

2. Add the Loops & Facets Module

Click on the “Module +” Button and type “Loop” in the search field.
Click on the Module and it will appear on the canvas.

Modules inserter with Loops & Facets module highlighted
Loops & Facets module with opened structure, with "Filters [collection]" and Post Loop [collection] modules highlighted

What you see in your canvas is placeholder data, we ship this with the module so you can see the output immediately even if you have not linked it yet with any data.

Now…

Open up the module structure and find two modules that have the label [collection] in them.

  • First one produces the filter buttons.
  • Second one produces the post cards.

3. Connect Posts Loop to the Dynamic Data for Posts

Click on the module called “Post Loop [collection]” and open Data Settings > Content section. In the content area you see the placeholder data. Replace it with real data coming from your DataVar. To do so click on the Database Icon shown in the next image.

Posts Loop module highlighted with arrow pointing to DataBase icon

From the dropdown, in the “Custom” section find the “…post_loop” option.

Dynamic data sources dropdown with post_loop options highlighted

Success, you now see your posts coming from your website!

4. Connect Facets Loop to the Dynamic Data for Category Terms

Builder UI showing posts appear in the canvas and in the content area of the editor panel

Do the same for the facet buttons. Select the module, “Filters [collection]”, go to Data Settings, content setion. Select the Database icon, find “…terms” option in the “Custom” section, and select it.

Dynamic data sources dropdown with terms options highlighted

Success!
You now see category terms coming from your website.

Builder UI showing facets appear in the canvas and in the content area of the editor panel

A short Video Demonstration

All posts

You might also like

Releases UI Stories: Surfacing Controls
Elvis Krstulović

Cookie settings

Our website uses some essential cookies to function well. With your permission, we would like to set up some additional cookies to improve your experience. Our Privacy Policy