Post Loop Widget

The Post Loop widget displays posts using available theme templates. The Query Builder can be used to filter your posts using a wide array of parameters.

Title
Optionally insert a widget title.

Template
Choose a theme template to display your posts. The Post Loop widget looks for templates within your theme with the following file names:

*-content.php
content-*.php
*-loop.php
loop-*.php

SiteOrigin themes like Corp have loop templates available for the Post Loop widget. If your theme doesn’t offer predefined templates you can try using one of the content partials if those are available in the drop-down list.

More Link
If the template supports it, cut posts and display the more link.

Posts query

Post type
Choose between All, Posts, Pages or any of the other available post types in your WordPress installation.

Post in
Specify posts to retrieve. Click on the field and use the provided search field to search for your post or browse the abbreviated list under the search field.

Taxonomies
Specify taxonomies to retrieve. Taxonomies are groups such as categories, tags, posts, and products. Click on the field and use the provided search field to search for your taxonomies or browse the abbreviated list under the search field.

Date selection type
Choose between specific or relative.
Select a range between specific dates or relative to the current date.

Dates
Select a from and to date.

Order by
Choose how to order your posts. The following options are available:

  • No order
  • Post ID
  • Author
  • Title
  • Published date
  • Modified date
  • By parent
  • Random order
  • Comment count
  • Menu order
  • By meta value
  • By numerica meta value
  • By include order

Order direction
Choose between Ascending or Descending.

Posts per page
Optionally enter the number of posts to display per page. If a value isn’t entered, this setting will fallback on the global setting at SettingsReading.

Sticky posts
Choose between Default, Ignore sticky, Exclude sticky and Only sticky.

Additional
Additional query arguments. See query_posts.

Below you’ll find a few examples of additional query arguments you might make use of.

Don’t Display the Most Recently Published Post
offset=1


Advanced Customizations

Adding Loop Templates to Your Child Theme or Custom Plugin

Child Theme

You can overwrite existing theme loops or add new loops from within a child theme.

To overwrite an existing theme loop, make a copy of the loop file and paste it into your child theme. The loop file must be stored in the same relative location and keep the same file name if you’d like to overwrite the copy in the parent theme. For example, if in our SiteOrigin North theme you’d like to overwrite the loops/loop-blog.php file, in your child theme create a loops folder and insert a copy of the loop-blog.php file into the child theme loops folder.

Adding a new theme loop to a child theme requires the loop file to have one of the following naming conventions:

*-loop.php
loop-*.php

Where * can be any name. loop-grid.php for example. Loop files can be inserted anywhere in your child theme.

Custom Plugin

Within your custom plugin, begin by letting Page Builder know which directory you’ll be storing your post loop templates in. If you haven’t yet created that directory, do so now. In our example, we’re naming the directory loops.

function so_custom_postloop_directories( $directories ) {
	$directories[] = plugin_dir_path( __FILE__ ) . '/loops/';

	return $directories;
}
add_filter( 'siteorigin_panels_postloop_template_directory', 'so_custom_postloop_directories' );

Next, create your loop templates in the newly created directory and then use the function below to register each loop template.

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' );

Note the template path begins with the plugin directory name.
Repeat $templates[] = 'so-custom-post-loop/loops/loop-plugin.php'; for each loop template that you’d like to add.

Download an example plugin.

Custom Pagination

If you’d like to use more than one Post Loop widget with pagination on a page, it’s necessary to add custom pagination to your templates to ensure that each Post Loop widget paginates independently. If you have two Post Loop widgets on a page, only one of the widget templates will need to make use of custom pagination.

echo paginate_links( array(
	'format'    => '?page-' . SiteOrigin_Panels_Widgets_PostLoop::get_current_pagination_id() . '=%#%',
	'prev_next' => false,
) );

Changing the Taxonomy Field from OR to AND

By default, the Taxonomies field uses a relationship of OR. To change the behavior of the Taxonomies field to AND, you can use the following function. This is useful if you’d like to list posts only if they are included in multiple categories. For example, only display posts if they are within category A and category B.

function so_posts_selector_and_relation( $query ) {
    if ( isset( $query['tax_query'] ) ) {
        $query['tax_query']['relation'] = 'AND';
    }
    return $query;
}
add_filter( 'siteorigin_widgets_posts_selector_query', 'so_posts_selector_and_relation' );

Filtering Example: Excluding a Category from a Post Type Loop

In this example, we’ve created an events post type and within that post type a category for past events. We’d like to remove all past events from the main events page. We’re displaying events on the events page using a Post Loop widget.

/**
 * Filter the SiteOrigin Widget Post Loop.
 */
function so_posts_query_exclude_term( $query ) {
	$terms = array(
		'taxonomy' => 'event_categories', // This is the taxonomy name.
		'field'    => 'term_id',
		'terms'    => 1625, // Term to exclude.
		'operator' => 'NOT IN'
	);

	// Is there a taxonomy query already present?
	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' );

In the above example, 1625 is the category ID for Past Events that we’d like to exclude from the main events page. 59427 is the category page for Past Events. We’re returning early on the Past Events category page as there isn’t any need to run this filter.