Template Parts with Display Posts Shortcode

Display Posts Shortcode lets you easily display posts based on any criteria you choose without any coding. Here’s the list of available parameters.

It includes some display options, but it’s unstyled so you’ll need to write CSS to make it look good. It’s difficult to match your theme’s layout for post summaries using just the shortcode and CSS.

Different styles of post summaries used by this theme

Styling belongs in a theme

Your theme already contains the markup and styling for displaying posts. By leveraging it, the shortcode output can match the styling of your site.

A few years from now when you redesign your site, your shortcodes will automatically use the new post styles defined in that theme.

Show Display Posts where your template partials are located

Use the following code to add a custom “layout” parameter to Display Posts.

This code looks for layouts in the /partials directory in the theme, prefixed with dps-. You can adjust the get_template_part() line to point to where you keep your template partials.


 * Template Parts with Display Posts Shortcode
 * @author Bill Erickson
 * @see https://www.billerickson.net/template-parts-with-display-posts-shortcode
 * @param string $output, current output of post
 * @param array $original_atts, original attributes passed to shortcode
 * @return string $output
function be_dps_template_part( $output, $original_atts ) {

	// Return early if our "layout" attribute is not specified
	if( empty( $original_atts['layout'] ) )
		return $output;
	get_template_part( 'partials/dps', $original_atts['layout'] );
	$new_output = ob_get_clean();
	if( !empty( $new_output ) )
		$output = $new_output;
	return $output;
add_action( 'display_posts_shortcode_output', 'be_dps_template_part', 10, 2 );

We can now use our template partials in the shortcode:

[display-posts layout="large"]

The partials are only used if a layout is specified in the shortcode, and a matching partial is found. This lets you keep using the plugin in other contexts as well, like a bulleted list of recent posts.

Markup in Template Partials

Now that the key functionality is in place, it’s time to create some template partials to use in Display Posts.

I use archive.php as the base layout for a post summary. It’s used on archive pages, and often elsewhere like a related posts section after a single post.

 * "Large" layout for Display Posts Shortcode
 * @package      StudyFinds2018
 * @author       Bill Erickson
 * @since        1.0.0
 * @license      GPL-2.0+

echo '<article class="post-summary large">';
	echo '<a class="entry-image-link" href="' . get_permalink() . '">' . wp_get_attachment_image( ea_entry_image_id(), 'ea_archive' ) . '</a>';
	echo '<h2 class="entry-title"><a href="' . get_permalink() . '">' . get_the_title() . '</a></h2>';
echo '</article>';

I use the “dps” prefix to indicate that these are for Display Posts Shortcode, and to limit which partials can be used by the shortcode.

This also saves me from building custom Related / Recent Posts widgets. We simply add a text widget containing the shortcode and it matches the site:

Display popular content

If you’re using Shared Counts for social sharing, you can display a list of your most shared content with:

[display-posts layout="small" orderby="meta_value_num" meta_key="shared_counts_total"]

You can even get fancy and display the 5 most shared posts published in the last 6 months in the same category as the current post:

[display-posts layout="small" posts_per_page="5" orderby="meta_value_num" meta_key="shared_counts_total" taxonomy="category" tax_term="current" date_query_after="6 months ago"]

Find yourself writing the same long shortcode over and over? Create a shortcut argument, then use something like

[display-posts show_popular="true"]

For more examples of customizing this plugin, see my Display Posts Shortcode code snippets.

Bill Erickson

Bill Erickson is a freelance WordPress developer and a contributing developer to the Genesis framework. For the past 14 years he has worked with attorneys, publishers, corporations, and non-profits, building custom websites tailored to their needs and goals.

Ready to upgrade your website?

I build custom WordPress websites that look great and are easy to manage.

Let's Talk

Reader Interactions

Comments are closed. Continue the conversation with me on Twitter: @billerickson


  1. Frédéric De Smet says

    Where should i place all these snippets? In a child theme ?

    Can i acces advanced custom fields data?

    Thanks in advance!!!

    • Bill Erickson says

      The last snippet (featuring the be_dps_template_part() function) can be placed in your theme’s functions.php file or a core functionality plugin.

      The template partials themselves can go anywhere in your theme you like, but the code above assumes they are in: wp-content/themes/[your theme]/partials/dps-[something].php

      For instance, the small partial above would be /partials/dps-small.php.

      Yes, you can use advanced custom fields data in there. Either access the data using ACF functions ( get_field() ) or using WP core functions ( get_post_meta() ).

  2. Mark Holloway says

    Hi Bill,

    I’m adding add_action( ‘display_posts_shortcode_output’, ‘be_dps_template_part’, 10, 2 ); to my theme but it keeps white screening my page, any ideas?


    • Bill Erickson says

      Hmm, no that shouldn’t cause any issues. Maybe there’s a PHP error in your version of be_dps_template_part(). Try enabling debug mode with define( 'WP_DEBUG', true ); in wp-config.php.

      Also take a look at this file in my starter theme as a working example.

  3. Eric says

    Hi Bill,
    First I hope you and your family are healthy and doing well.

    I’m trying to do this while knowing nothing about php. I’m using the twentytwenty theme.

    I can’t seem to fully understand your instructions, I think I’m missing something.

    I’ve added the first snippet using the Code Snippets plugin. The same way as you I’ve linked ‘partials/dps’.

    I don’t have a partials folder so I created it and put in there copies of the .php files I find in template-parts and gave them a ‘dps’ prefix, making them look like ‘dps-content.php’ (here is where I’ve gone off road I believe).

    I keep reading your instructions over and over again but can’t seem to understand where should I put what, like the second snippet.

    I hope you can help me,

    Thank you very much

    Greetings from Barcelona

    • Bill Erickson says

      The second snippet is an example of the content you could include in your partial (ex: dps-content.php). You can add any markup you like to the template part, and you’ll usually want to match the markup used for your post listings in your theme.