Home

The Display Posts Shortcode was written to allow users to easily display listings of posts without knowing PHP or editing template files.

Add the shortcode in a post or page, and use the arguments to query based on tag, category, post type, and many other possibilities (see the Arguments). I've also added some extra options to display something more than just the title: include_date, include_excerpt, and image_size.

See the WordPress Codex for information on using the arguments.

WordPress.com Users

This plugin is now available to all users of WordPress.com. There's no installation necessary, just drop the shortcode in your page's content area. Unfortunately you won't be to use any of the filters listed in Further Customization since this requires customizing your theme, which isn't allowed on WordPress.com

Image Alignment

A common request is display a list of posts with title, excerpt, and the thumbnail aligned to the left. Here's the shortcode you might use:

[display-posts include_excerpt="true" image_size="thumbnail" wrapper="div"]

This includes the excerpt, adds an image of the "thumbnail" size (you can customize the image sizes in Settings > Media), and tells it to wrap the list in a div instead of an unordered list so we don't have bullets.

This plugin does not include any styling of the listings so that you can make them look however you want. In order to get the image floating to the left, add this to your theme's style.css:

.display-posts-listing .listing-item {
	clear: both;
}

.display-posts-listing img {
	float: left;
	margin: 0 10px 10px 0;
}

Examples

[display-posts tag="advanced" posts_per_page="20"]

This will list the 20 most recent posts with the tag 'Advanced'.

[display-posts tag="advanced" image_size="thumbnail"]

This will list the 10 most recent posts tagged 'Advanced' and display a post image using the 'Thumbnail' size.

[display-posts category="must-read" posts_per_page="-1" include_date="true" order="ASC" orderby="title"]

This will list every post in the Must Read category, in alphabetical order, with the date appended to the end.

[display-posts taxonomy="color" tax_term="blue" include_excerpt="true"]

This will display the title and excerpt of the 10 most recent posts marked "blue" in the custom taxonomy "color".

[display-posts wrapper="ol"]

This will display posts as an ordered list. Options are ul for unordered lists (default), ol for ordered lists, or div for divs.

[display-posts id="14,3"]

This will display only the posts with an ID of 14 and 3.

Arguments

View all shortcode parameters here

Multiple Taxonomy Queries

While most people will only ever need a single taxonomy query, this plugin supports an infinite number of taxonomy queries. Let's say you wanted to get all posts in category "featured" and also tagged "homepage". We'll use a shortcode that looks like this:

[display-posts taxonomy="category" tax_term="featured" taxonomy_2="post_tag" tax_2_term="homepage"]

You can string as many of those as you like, just start the count at 2. In the field listing below, replace (count) with an actual number.

Here's the available fields:

taxonomy_(count)
Which taxonomy to query
Default: empty

tax_(count)_term
Which terms to include (if more than one, separate with commas)
Default: empty

tax_(count)_operator
How to query the terms (IN, NOT IN, or AND)
Default: IN

tax_relation
Describe the relationship between the multiple taxonomy queries (should the results match all the queries or just one of them). Available options: AND and OR
Default: AND

Further Customization

shortcode_atts_display-posts

Change the default arguments of the shortcode. For instance, if you want all shortcodes to have include_excerpt="true" and include_author="true", you could use this to set it once and then not have to include those parameters on all shortcodes. Example: http://www.billerickson.net/code/change-default-attributes-in-display-posts-shortcode/

display_posts_shortcode_args

For customizing the $args passed to WP_Query. Useful if a query arg you want isn't already in the shortcode. Example: http://www.billerickson.net/code/display-posts-shortcode-exclude-posts/

display_posts_shortcode_output

For customizing the output of individual posts. Example: http://www.billerickson.net/code/display-posts-shortcode-full-content/

no_posts_message

Content to display if no posts are found (default is empty).

display_posts_shortcode_wrapper_open and display_posts_shortcode_wrapper_close

For customizing the outer markup of the whole listing. By default it is a ul but can be changed to ol or div using the 'wrapper' attribute, or by using this filter. Example: http://www.billerickson.net/code/display-posts-shortcode-outer-markup/

display_posts_shortcode_post_class

For adding classes to the individual posts (ex: break into columns)

Adding a target="_blank" to the anchor tag in posts

Add the following code to your theme's functions.php file:

function be_links_in_new_window( $output ) {
    return str_replace( '<a ', '<a target="_blank" ', $output );
}
add_filter( 'display_posts_shortcode_output', 'be_links_in_new_window', 20 );

More examples: http://www.billerickson.net/code-tag/display-posts-shortcode/

Pagination

A common question I receive is how to load the next page of results, or paginate the query. This plugin does not support pagination, nor will it in the future. If you need pagination in your query, you should not be using a shortcode. Use the WordPress core templates like the category archive or tag archive. Or if you must, build a custom page template that overrides the main WordPress query: http://www.billerickson.net/code/pagination-in-a-custom-query/