Use template parts to match your theme’s styling

Display Posts lets you easily display posts based on any criteria you choose without any coding.

It can be difficult to match your theme’s design for post summaries using just the shortcode and CSS. That’s where template parts come in.

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.

Markup in Template Partials

I use template partials for post layouts in my themes. Here’s the partials directory in my starter theme.

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.

For areas that require a different output, I create a separate partial. In one theme we displayed featured posts in a rotator, so I created archive-featured.php:

I use the same approach when it comes to styling Display Posts. I might have two post layouts: large and small. I’ll create dps-large.php and dps-small.php to hold the markup. If the large layout matches the archive layout, you can simply include one into the other:

The small layout uses slightly different markup:

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.

Specify a layout in the shortcode

I add a “layout” custom parameter to specify which post layout should be used.

[display-posts layout="large"]

This code snippet goes in a core functionality plugin or Code Snippets.

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.

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

Filters used:

Published by Bill Erickson

Bill Erickson is a freelance WordPress developer and a contributor 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.

Join the Conversation

  1. Bill, I wrote a plugin a while back that works in basically the same way as this one:
    https://github.com/jonschr/simple-query-shortcodes

    Yours is unquestionably better (takes a lot more parameters, allows for more advanced queries, etc. and will likely have a Gutenberg block much sooner than mine would), and I’d like to switch over to using it instead.

    However, I’ll often write one-off plugins for a given content type (e.g. FAQs or Partners or whatever) that automatically register a content type, add fields to the CPT, then also enable a default layout when used with something like this, where the content type is the name of the default layout.

    The method I use is adding actions rather than partials – my question is, do partials (as shown here) work in basically the same way if used in a plugin, or are those limited to use in themes?

    1. The actual WordPress function `get_template_part()` only works with themes and child themes, but you can use the same basic approach with a plugin.

      Just check if a file exists in a certain directory of your plugin, and if so, load it. For instance, in the FAQ plugin you might have something like this: https://gist.github.com/billerickson/cfc112b9bbbe37aa9a62890ba7e61709

      I still prefer pulling the template based on a custom layout parameter rather than just the post type. If you had a shortcode querying multiple post types ( [display-posts post_type="faq, post"]) it might look strange having the FAQs styled by the plugin but the posts using the default list styling.

      1. Yeah, and my plugin does that too, actually (there’s a ‘layout’ parameter; it just grabs the name of the post type by default if there’s not something more specific specified) – that’s the thing I actually thought made it unique, ’cause I hadn’t seen anything like it out there!

        However, it’s probably fortunate that I asked earlier today, because my plugin isn’t playing nice with Gutenberg ACF blocks (it outputs fine, but other blocks aren’t outputting some of their settings correctly – I’m probably not resetting the query somewhere).

        Yours works great out of the box in every way I’ve tried it so far, and that snippet looks like exactly what I’m needing, so that’s fantastic.

        I think I’ll be happier pushing reset on mine (which has been one of the most useful things I’ve written, actually), and moving forward with yours.

      2. One other question on this topic: is there a way using a custom layout parameter with this plugin to enqueue any necessary scripts/styles only when that layout is being output?

        I looked through the code and couldn’t find a hook that runs 1) after the layout is selected with the $original_args[‘layout] available but 2) before the individual post output.

        This would be for, say, loading posts up into a slider where we need to run certain javascript just once, or to allow a plugin to enqueue base styles to make it functional (letting the theme take care of more specific styling. It seems like it wouldn’t be the best practice to do an enqueue inside the individual post content (even though that might technically work).

        1. Take a look at Nathan Rice’s recent article on outputting the necessary styles immediately before they are needed. I plan to use a similar approach with the new Display Posts Gutenberg block.

          For JavaScript, you can simply call `wp_enqueue_script()` inside the shortcode output and it will be loaded in wp_footer.

          1. Hmm. Yeah, I’d read this, and it’s a brilliant idea. Makes sense (and cool technique for minimizing the amount of css that gets output globally/avoiding renderblocking).

            The thing I actually couldn’t figure out on Display Posts is if there’s an action that fires and is aware of what layout it’s in before the posts. I think I gave bad examples last time. Here’s a better one: outputting a slider, but with buttons set up above the slider which pull in categories for use in filtering the slides. So it’s actually not just enqueues, and it’s not just the opening/closing div. It’s potentially both.

            The action would need to be aware of the layout, but if it was aware of the query as well (to automatically detect the content type and/or categories), then so much the better. I’ll try your suggestion, though, as this is definitely an edge case. The vast majority of cases don’t need something like this. Real-world example – the floorplans here: https://maxflatsfc.com/floor-plans/

            I’ll definitely play with just enqueueing everything inside the shortcode output and see if that gets me where I need to go for the most part. I suspect I’ll run into issues with being able to use the same block twice (I sometimes cheat by generating a random number and adding that into the wrapper ID, then just writing some inline javascript which initializes the library using the same ID), but that’s probably mostly because of my own shortcomings in localizing scripts appropriately.

            BTW, I saw the other day that you’re part of the Georgetown meetup. I’m in Waco; I’ll have to come down some week and say hello. It’s incredible the amount of code & tutorials you’ve written that’s benefited my learning curve over the years, so thanks!

          2. You can use the display_posts_shortcode_wrapper_open and display_posts_shortcode_wrapper_close hooks to customize the opening/closing markup. The second parameter on those hooks is the `$atts` from the shortcode. The third parameter on both of those hooks is $dps_listing which is the global query. You can use that to access query data (ex: $dps_listing->current_post ).

            With Display Posts 3.0 I made $dps_listing a global variable so it’s accessible anywhere, not just if the hook includes it. Just add global $dps_query; to access it.

  2. Hello!
    Due to my lack of knowledge about programming, I don’t really know how and where to implement these codes. I managed to change a couple things with css, but it just doesn’t match my Wiral II theme. If you could spare some time to quickly explain it to me, I would highly appreciate it.

    1. Unfortunately this tutorial is very developer focused and depends upon a good understanding of PHP and WordPress development.

      I recommend you contact your theme’s support team for guidance on how this can be implemented with your specific theme.

      You could also hire a WordPress developer on Codeable to help implement it.

      The next large release of Display Posts will include a variety of pre-styled options to choose from, which should make it easier to display your post listings without having to make any code changes.

Leave a comment

Your email address will not be published. Required fields are marked *