Can I just get everyone's ok that using shortcodes embedded within templates is the 'correct' thing to do? I've tested them and they work just fine - but I just wanted everyone's thoughts. Thanks

Here's an example:

<?php echo do_shortcode('[course_complete]'); ?>
  • You may get an opinion based answers not an definitive answer. – bravokeyl May 26 '16 at 8:52
  • 2
    Yes it'll be opinionated. In my view it's a handy way of showing a shortcode in a template. If it's your own code you could write a template tag to remove the regex overhead. If it's third party, see if the author has also supplied a documented template tag. And people will point out you've got a typo: an extra square bracket. I tried to remove it but my edits have to be more than 6 characters! – Andy Macaulay-Brook May 26 '16 at 8:58
  • 2
    Please explain a specific technical problem. "Get everyone's OK" isn't one. – fuxia May 26 '16 at 9:09

Is it Ok?


Is it Optimal?


What Would Be Better?

Shortcodes map on to PHP functions, so why not cut out the middle man and go straight to the original function?

Are there any other downsides?


That shortcode had to come from somewhere, now you have a dependency, maybe the plugin that has the shortcode gets deactivated, who knows

Are There Any Upsides?

Yes! It's much easier to build a gallery shortcode programmatically then pass it into do_shortcode than it is to create one from scratch.

Even if you do bypass the shortcode and go straight to the original function, you still have the same problem mentioned above. If the shortcode doesn't exist, it'll degrade gracefully back to an empty string. You can use the shortcode inside post content too

So, best to use shotcodes ONLY in widgets + pages + posts?

Is it Ok? Yes! But is it the best? Probably not

Shortcodes are awesome! But remember their purpose, if you need to put stuff in a template, you don't need to use a shortcode, but if needs must, that option's always there. The do_shortcode function is just a tool, and they're for embedding things in content, don't go using it as the foundations for your site or framework. I've built plenty of sites, and I've not had to do this

  • Almost the same than other answers but much better explained. +1 – cybmeta May 28 '16 at 7:46
  • Just a pedantic note: actually regarding dependencies is better to use shortcodes than calling original functions. do_shortcode('[thing]') is less harmful than a direct call to do_thing_shortcode() if the plugin that provides the shortcode (and the function) is not available. – gmazzap Jun 9 '16 at 13:36
  • That's mentioned in the answer, but it's fixed by a function_exists check – Tom J Nowell Jun 9 '16 at 18:14

Shortcodes done that way is a less sinister relative of eval. It is ok if you intend to give a user an option but not an acceptable coding practice.

When activating a function that way you lose three things

  1. Code readability. What is exactly you intended to do there? I will not be able to guess it without looking at the implementation of the shortcode which no tool will help me to find.

  2. Predictability. What happens when the shortcode attributes are changed in a new version? What happens when the short code itself is just doing something totally else than you expect? When you call a function directly you are likely to get errors that will prompt your attention to incompatible changes in the interface but using a shortcode you will just not know before users complain.

  3. Testability. Follows from the second point but worth to emphasize it. How are you going to test your code when you don't actually know what supposed to happen?

If you are specifically looking for flexibility, It seems to me that a better approach is to create your own action hook and let people hook on it. You can supply what ever implementations of the hook you feel are useful, and people will be able to change it if they will want to. The point here is that the intention of the hook as a means to "something random can go here" is more explicit then using a shortcode.

  • So, in summary - would you say that shortcodes only 'belong' in widgets and pages + posts? I'm confused why a shortcode embedded within a widget would be any different to a template but I also must confess that I don't have your depth of php understanding... – henry May 26 '16 at 14:11
  • 1
    @henry shortcodes are an option for the author, they are macros that make author's life easier. They belong to user input, in whatever is the applicable place for it. They obviously can be used by code but it creates a fragile code that is best avoided. It does not have actually anything to do with PHP, maybe software development experience, you become with time to prefer "contracts" over flexibility because problem caused by flexibility are hard to recreate and debug – Mark Kaplun May 26 '16 at 18:35

A shortcode is a placeholder for a PHP callback. As placeholder, it is intended to be used where PHP can not be used directly.

Additionally, do_shortcode() will do a regex in the passed string looking for all registered shortcodes, which is not appropiate from a performance point of view if you just want to execute one shortocode, not to look for all shortcodes in a string.

So, there is almost no reason to use do_shortcode( '[my_shortcode]' ) in a template file; it is more appropiate to use the callback instead of the placeholder.

However, it is OK to use do_shortcode() to parse strings or to filter content that may contain shortcodes that you want to be executed, but again a template file may be not the correct place to parse strings or filter content. For example, you may want to filter Text Widget content and allow shortcodes in it:

add_filter( 'widget_text', 'do_shortcode' );

do_shortcode() can be also useful when you need the functionality of a shortcode, no matter the exact output you get or what callback it is used, you need the functionality.

For example, a plugin/theme could redefine a shortcode, for example the gallery shortcode:

remove_shortcode( 'gallery', 'gallery_shortcode' );
add_shortcode( 'gallery', 'my_gallery_shortcode' );

In this case, if you need the gallery functionality, not the specific output of callback, using do_shortcode( '[gallery]' ) within a theme could be justified. But no one should redeclare the gallery shortcode, instead post_gallery filter should be used to modify the gallery shortcode output. So, the use of do_shortcode('[gallery]') would be a very edge use case.

Same argument applies to any shortcode and the use of do_shortcode() is a very edge case in general.

  • So, best to use shotcodes ONLY in widgets + pages + posts? – henry May 26 '16 at 9:37
  • 3
    I disagree on "no reason". Shortcode is a layer of abstraction. [gallery] shortcode is abstraction for gallery functionality. It very well might call entirely different callbacks, depending on site configuration. Is it a good idea? Probably not in most cases. Is it universally useless and pointless technique? Absolutely not. – Rarst May 26 '16 at 10:11
  • 1
    @cybmeta I think there's value and information in this answer, just because it isn't perfect doesn't mean it can't be edited or serve a purpose as is, e.g. the other answers have nothing about replacing core shortcodes or the filters involved. I vote to undelete! But I'll leave that as your choice – Tom J Nowell May 28 '16 at 13:51

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.