Post Loop Widget for Page Builder

The Post Loop widget shows a list of posts with a loop template from your theme, or one that a plugin registers. The template you choose sets how the posts look. Page Builder includes the widget. The Posts query field needs the SiteOrigin Widgets Bundle.

The Post Loop widget form

Title
An optional title above the posts.

Template
The theme template that displays the posts. The list shows the templates that Page Builder finds in your theme, and any that plugins register. If there are none, the form says “Your theme doesn’t have any post loops.” and shows no settings. See Loop Templates.

SiteOrigin themes, such as Corp, include loop templates for the Post Loop widget. If your theme has none, try one of its content templates.

More link
If the template supports it, cut posts at the More block and show the more link.

Post Loop widget output in a grid on the front end

Posts Query

With the Widgets Bundle active, click Posts query to open these settings:

Post Type
The post types to show. Choose All, or one or more post types, such as Posts and Pages.

Post In
Show only the posts you choose. Click the field, then search for posts or choose from the list.

Taxonomies
Show only posts with the categories, tags or other terms you choose. Click the field, then search for terms or choose from the list.

Taxonomies Relationship
OR shows posts that have at least one of the terms. AND shows posts that have all of the terms. OR by default.

Date Selection Type and Dates
Show posts from a date range. Specific uses set dates. Relative counts back from the current date.

Order By
How to sort the posts: No order, Post ID, Author, Title, Published date, Modified date, By parent, Random order, Comment count, Menu order, By meta value, By numeric meta value or By include order. Published date by default.

Order Direction
Ascending or Descending. Descending by default.

Posts Per Page
The number of posts on each page of the loop. If you leave it empty, the widget shows 10 posts.

Sticky Posts

Default: the standard WordPress behavior. On the first page, WordPress can move sticky posts to the top of the loop.
Ignore sticky: sticky posts show in their normal position in the loop.
Exclude sticky: sticky posts don’t show.
Only sticky: only sticky posts show, plus any posts you choose in Post In. If your site has no sticky posts and Post In is empty, all matching posts show.

With Default, WordPress can add sticky posts to the first page even when they don’t match your other settings, such as Post In, Dates or an offset. The first page can then show more posts than Posts Per Page. Choose Ignore sticky to prevent this.

Additional
Extra query arguments, in the format used by query_posts. Separate arguments with &. For example:

offset=1 skips the first post. An offset overrides the page number, so a paginated loop shows the same posts on every page. If Posts Per Page is -1, WordPress ignores the offset. Set Sticky Posts to Ignore sticky when you use an offset.
post__not_in=123,456 hides the posts with those IDs.

When Post In is set, WordPress ignores exclusions such as Exclude sticky and post__not_in.

Without the Widgets Bundle

Without the Widgets Bundle, the widget shows a basic form in place of Posts query. It has More Link, Post Type, Posts Per Page, Order By, Order, Sticky Posts and Additional fields.

The widget shows posts on the front end. In the admin, it shows only in SiteOrigin Layout block previews and Legacy Widget block previews.
The loop normally leaves out the current post.
A Post Loop inside another Post Loop shows no posts.

Loop Templates

Page Builder looks for templates in your parent theme and child theme. It finds files named loop*.php or content*.php, such as loop.php, loop-grid.php or content-page.php. The files must be in the theme’s root folder or one folder down, such as loops/loop-grid.php. Page Builder doesn’t find files in deeper folders.

The widget loads a loop*.php template once, so the template must run its own loop. A content*.php template shows one post, so the widget loads it once for each post.

To give a template a clear name in the Template list, add a Loop Name header to the top of the file:

<?php
/**
 * Loop Name: Blog Grid
 */

Child Theme

To change a parent theme’s loop, copy the file to the same folder and file name in your child theme. For example, to change loops/loop-blog.php, create a loops folder in your child theme and copy loop-blog.php into it.

To add a new loop, add a file named loop*.php to the child theme’s root folder, or one folder down.

Custom Plugin

To add templates from a plugin, register each template with the siteorigin_panels_postloop_templates filter. The path starts with the plugin’s folder name, relative to the plugins folder.

function so_custom_postloop_templates( $templates ) {
	$templates[] = 'so-custom-post-loop/loops/loop-plugin.php';
	return $templates;
}
add_filter( 'siteorigin_panels_postloop_templates', 'so_custom_postloop_templates' );

Add one $templates[] line for each template. Download an example plugin.

Advanced Customizations

Filtering the Query

With the Widgets Bundle, use the siteorigin_widgets_posts_selector_query filter to change the query. This example hides the Past Events category (term ID 1625) from every posts query, except on the page with ID 59427. If you select other terms in Taxonomies, it also changes their relationship to AND.

function so_posts_query_exclude_term( $query ) {
	$terms = array(
		'taxonomy' => 'event_categories', // The taxonomy name.
		'field'    => 'term_id',
		'terms'    => 1625, // The term to exclude.
		'operator' => 'NOT IN',
	);

	if ( is_page( 59427 ) ) {
		return $query;
	} elseif ( isset( $query['tax_query'] ) ) {
		$query['tax_query'][] = $terms;
		$query['tax_query']['relation'] = 'AND';
	} else {
		$query['tax_query'][] = $terms;
	}

	return $query;
}
add_filter( 'siteorigin_widgets_posts_selector_query', 'so_posts_query_exclude_term' );

This filter runs for every widget that uses the Widgets Bundle posts field, not only the Post Loop.

Template and Settings in a Template

While a loop template renders, two methods return the widget’s details:

SiteOrigin_Panels_Widgets_PostLoop::get_current_loop_template() returns the template file name as a string, such as loops/loop-blog-grid.php.
SiteOrigin_Panels_Widgets_PostLoop::get_current_loop_instance() returns the widget’s settings as an array.

Use them in your template to change the output based on the widget’s settings. They return null outside the template, for example in the query filter above.

Post Loop Widget

Widget Settings