• About Us
    • New York
  • Work
  • Capabilities
  • Careers
  • Technology
  • Blog
  • Contact Us
  • About Us
    • New York
  • Work
  • Capabilities
  • Careers
  • Technology
  • Blog
  • Contact Us
March 02, 2016

Flexible WordPress Shortcodes with Locate Template

Posted by Christopher Davis

Underlying the entire WordPress template hierarchy is the locate_template function. locate_template pretty easy one to understand: it checks the child theme for the template, then the parent theme and either returns the template path it found or loads it for you.

The idea is you pass it an array of template names with the more specific template names at the beginning. For instance, WordPress creates the array ["single-{$post->post_type}.php", "single.php"] when it loads single templates.

What’s a Shortcode Anyway?

Shortcodes are a way to pull blocks of content (or whatever you want) into post content. We’ll make an imaginary shortcode that renders pulls in a little feature box for another post. You might use it like

[pmg_post_snippet id="123"]

and get something back like…

Screen Shot 2016-02-25 at 12.51.55 PM

The code for this is pretty simple. We’ll wrap it up in a class to keep the hooks into init and callbacks for add_shortcode close by.

This small example exposes a big weakness to this approach: it’s nearly impossible for an end user to modify the content of the shortcode. Even if that end user will only ever be you, some flexibility is a good thing to build.

A way around this would be to add a filter that lets a user short circuit the display part of the shortcode callback.

This isn’t bad, but I think there’s a better approach that makes it easy for theme developers to integrate with third party shortcodes and make them look good.

Using Locate Template

Rather than hard coding the HTML into the shortcode, use locate_template to look for a template in the theme to render the shortcode content. Fall back to your own template if one isn’t found in the themes.

Now all a theme developer has to do is drop a pmg-post-snippet.php template in their theme to customize the output. As a nice side effect, it’s a great way to separate the view part of your shortcode from the logic aspect(s) — like checking to see if a post is published, etc.

The only thing of note in the example above is the safeInclude static method that’s used to avoid giving the included template access to the objects $this variable or any of the other variables in the showSnippet method.

Why Not get_template_part?

Because we want to control the context passed to the included template. In the example above, I wanted to give the template access only to the $post variable, not the usual set of the global variables that load_template sets up.

get_template_part also doesn’t allow additional context (other variables) to be passed in. This isn’t a big deal in this example, but becomes more important with complicated shortcodes.

Other Applications

This same pattern works great for hiding re-usable theme components behind a function and when get_template_part won’t suffice for the reasons outlined above.

For example, we wrote a small abstractions around loading a template to render a grid of posts this week for a client.

The custom query object meant get_template_part was not going to work without messing with the global $wp_query variable.

Previous
Next

Latest White Papers

  • Shifting Plans for 2020 & Beyond
  • Game On: How Brands Can Log Into A Diverse Multi-Billion Dollar Industry
  • What CCPA Means For Brands
  • How Google is Improving Consumer Data Privacy
  • Ways to Prepare for the Cookieless Future
  • See all White Papers

Featured Posts

  • Ad Age Names PMG #1 Best Place to Work in 2021
  • Hindsight 2020 & Looking Ahead to 2021
  • Preparing for Streaming’s Growth & The Future of TV Buying
  • MediaPost Names PMG Independent Agency of the Year
  • PMG Client Portfolio Trends During Amazon Prime Day 2020

Categories

  • Consumer Insights
  • Content
  • Creative Design
  • Data Analytics
  • Development
  • Digital TV & Video
  • Ecommerce
  • Industry News
  • Local
  • Mobile
  • Paid Search
  • PMG Culture
  • Programmatic & Display
  • SEO
  • Social Media
  • Structured Data
Fort Worth

2845 West 7th Street
Fort Worth, TX 76107

Dallas

3102 Oak Lawn Avenue
Suite 650
Dallas, TX 75219

Austin

823 Congress Avenue
Suite 800
Austin, TX 78701

London

33 Broadwick Street
London
W1F 0DQ

New York

120 East 23rd Street
New York, NY 10010

Get in touch

(817) 420 9970
info@pmg.com

Subscribe to the PMG Newsletter
© 2021 PMG Worldwide, LLC, All Rights Reserved
  • Contact
  • Privacy Policy
 Tweet
 Share
 Tweet
 Share
 Tweet
 Share
 LinkedIn
We and our partners use cookies to personalize content, analyze traffic, and deliver ads. By using our website, you agree to the use of cookies as described in our Cookie Policy.