Get Bricks

Query Loop

The Query Loop builder is available since version 1.3.7 for the Container, Accordion, and Slider element.

Update: It can also be enabled for these elements with subsequent updates: Div, Accordion (Nestable), Tabs (Nestable), Slider (Nestable).

It allows you to retrieve data from your database (according to your query parameters) and to render whatever content you want to show inside the loop (dynamic data).

You can query post types, taxonomy terms, and users. Some typically use cases are:

  • Posts: Latest posts, related posts (works for any registered & public post type)
  • Terms: Post categories & tags, product categories, etc.
  • Users: List blog authors, community members, team members

Creating A Custom Loop

Add a “Container” element to the canvas. Enable the Use Query Loop to turn your container into a loop item.

Container element: new query loop control

Once you’ve enabled the Use Query Loop setting, you’ll see a Query control (loop or infinity icon). This is where you set the parameters according to which the content is retrieved.

This container now serves as your repeater item. All elements inside this container are repeated as many times as the results of the query.

The Query Control

The Query control now supports three different object types: posts, terms and users.

  • Posts enable a WP_Query type of query. This is the default query type, and should be used when you want to display a loop of posts, pages, media files or custom post types.
  • Terms enable the WP_Term_Query. This should be used when you want to loop through the different terms of a taxonomy. Useful to list all the product categories that contain products.
  • Users enable the WP_User_Query. This should be used when you want to loop through a set of site users. Useful to list the blog authors or a list of team members (as long as they are inserted as site users).

The query controls adapt according to the selected query type.

Posts query

Post type: Select one or multiple post types (default: posts)

Order by: Order the results by post ID, author, title, published or modified date, comment count, relevance, menu order or random (default: published date).

Order: Ascending or Descending (default).

Posts Per Page: The number of posts to show per page (default: WordPress settings → Reading → Blog pages show at most)

Offset: The number of posts to skip.

Include/Exclude: If you want to include or exclude one or multiple posts from the query.

Exclude Current Post: If enabled it will exclude the current post from the loop (useful to build a “related posts” section)

Terms Include/Exclude: Include or Exclude posts that have one or multiple terms.

Taxonomy Query: Add one or multiple taxonomy queries to filter the posts.

Tax Query Relation: Define if the taxonomy queries should be inclusive (OR) or exclusive (AND).

Meta Query: Add one or multiple meta queries to filter the posts based on the custom fields.

Relation: Define if the meta queries should be inclusive (OR) or exclusive (AND).

Example 1: Latest Posts

In this example, we’ll list the latest four posts (each item shows the featured image, post title, and excerpt) using the Query Loop Builder.

Custom Query Loop Builder - latest posts
Display the latest posts using a custom query loop

We start by adding a container to the canvas. This container holds our loop and serves as the blueprint for each query item.

Next, we enable the “Use Query Loop” setting to turn our simple container into a query loop.

Inside our container, we add an image element, and set it to “Featured Image” using the Dynamic Data dropdown.

In the same container, add another container with a Heading and a Text element.

For the Heading element we add the {post_title} tag.

For the Text element we add {post_excerpt} tag.

If you like, you could use the Post Title element or the Post Excerpt element instead.

By default, the query control shows the latest posts, but because we want to restrict the number of posts shown, you need to edit the Query setting and set the Posts Per Page control to 4, to restrict the output to max. four rows.

Media Query

Bricks 1.5 introduces the possibility to query for media files (the attachment post type). In the Posts query type, you’ll now find the Media post type.

After selecting Media in the post type control, you’ll get a new control to define the mime type. By default, Bricks will automatically query for images but you may define other mime types (if more than one, separate them by a comma, e.g. image/jpeg,image/png,image/gif).

To query for the images attached to a post, you may use the Child of control to specify the post ID. To do it dynamically, you may use dynamic data to fetch the current post id: {post_id}.

Example 2: Media Gallery

The media query opens the possibility to build a custom media gallery using the Query Loop builder. To start you would need to add a Container element, insert a Block element inside it, and finally an image element inside of the Block.

In the container, you’ll set the flex-wrap to wrap, and the direction to horizontal (row). In the Block, you’ll need to activate the Query Loop, and set the Media post type, and the number of images you’ll want to get (posts per page). In the Block layout you need to set the width and the height (e.g. 300px).

In the Image, you’ll set the dynamic data as {post_id} – note that the query returns the attachment posts (media files), so the image ID is the post ID. To complete the layout, set the image object-fit to cover, and the height to 300px.

The final result of a media gallery using the Query Loop builder

Terms Query

Taxonomies: Select one or multiple taxonomies to query (default: none)

Order by: Order the results by term ID, term name, term parent, count or include list.

Order: Ascending (default) or Descending.

Number: The number of terms to show per page. WordPress default is all but Bricks defaults to the number defined in the WordPress settings → Reading → Blog pages show at most. Use 0 to display all the results.

Offset: The number of terms to skip.

Parent: Parent term ID to retrieve direct-child terms of. Set this to 0 to fetch only the terms that have children. Ex.: Given this structure, entering 55 would get only the Tshirts.

Child of: Term ID to retrieve child terms of. Ex.: Given this structure, entering 55 would get Tshirts and Tees.

Childless: (bool) True to limit results to terms that have no children. This parameter has no effect on non-hierarchical taxonomies. Default false.

Terms Include/Exclude: Include or Exclude terms from the query

Show empty: Whether to show terms not assigned to any posts.

Meta Query: Add one or multiple meta queries to filter the posts based on the custom fields.

Relation: Define if the meta queries should be inclusive (OR) or exclusive (AND).

No Results: Text to be shown when there are no matching results.

Example 3: Product Categories

In this example, we’ll build a dynamic list of products categories (product category image + a link to the category archive).

The example is based on the WooCommerce plugin and the sample products. We’ll need one container to hold the container loop. Inside of the container loop we’ve added a Basic Text element that contains the Dynamic Data {term_name} tag.

Display the product categories with a link

After setting the Query to loop through “terms”, and selecting the Taxonomy “Product Categories” you’ll get in the canvas as many containers as the existing categories. Inside of the loop, you’ll be able to use several dynamic data tags to fetch the term’s data, such as the term id, the term name, the term archive URL, the term description, and any term meta.

In this example, we set the loop container background image as the product category thumbnail, using the Dynamic Data dropdown and selecting the Product Category Image tag:

Set the container background image

We also set the loop container as a link to the product category archive page (using the Term Archive URL dynamic data tag). You’ll need to set the HTML tag to “a (link)”, and the link type to Dynamic Data which will enable the Dynamic Data dropdown:

Users Query

Roles: Select one or multiple user roles to query (default: any)

Order by: Order the results by user ID, name, username, nicename, login, email, registered date, post count, or include list.

Order: Ascending (default) or Descending.

Number: The number of users to show per page. WordPress defaults to all but Bricks defaults to the number defined in the WordPress settings > Reading > Blog pages show at most. Use -1 to display all the results.

Offset: The number of users to skip.

Meta Query: Add one or multiple meta queries to filter the posts based on the custom fields.

Relation: Define if the meta queries should be inclusive (OR) or exclusive (AND).

No Results: Text to be shown when there are no matching results.

Example 4: The blog authors

In this example, we want to build a section to list all the blog authors.

The blog authors are website users with the role author. As in the other examples, we’ve used a container to loop through the users. In that container, we’ve set a query of users type, setting roles to “Author” to pull only the website’s authors.

Inside the loop container, we’ve added an Image and a Basic Text element.

The image we’ve set it to display an ACF Dynamic Data field containing the profile image. In the Basic Text we’ve used the Dynamic Data {wp_user_display_name} tag.

Display the blog authors

The Pagination element

Bricks 1.3.7 introduces a new Pagination element. The perfect companion to the custom query loop builder. You’ll find this new element under the WordPress elements group.

Having the pagination as a separated element offers you the most flexibility to build any kind of layout.

After adding the Pagination element to the canvas, you’ll need to link this pagination element to one of the elements that runs a query. To do so, please select the element in the Related Query control, by editing the Pagination element:

Tip: to make it easier to recognise elements, give descriptive element names to the containers that have a query enabled.

Query Loop in Accordions & Sliders

The Accordion & Slider elements also allow to pull data dynamically through the Query Loop to feed the element parts.

In the Accordion element, you’ll find a Query Loop control to configure a query. The query results create as many accordion items as the results of the query.

You’ll be able to configure the accordion title, subtitle, and content of the “master” accordion item, and this will be used as a template for the dynamic accordion items:

Use the query loop in the accordion element

The same happens in the Slider element. If the Query Loop is enabled, you’ll have access to a Query control and a slide item which will behave as the template for all the slides.

Use the query loop in the slider element.