driftwood-fort-kid header-shot for "WordPress Shortcode Fundamentals"

WordPress Shortcode Fundamentals

The WordPress shortcode is a wonderful tool. Shortcodes allow developer to give control of their code-snippets to the WordPress-admininstrators.

It let’s developers allow users to place/embed the developer’s code anywhere they like.

The developer writes the output, and the user adds the shortcode in their WordPress editor wherever they would like to output that code.

For Users

Shortcodes Accept “arguments”.

Arguments are declarative statements (basically x = “this”) which can modify the shortcode output.

This shortcode, for example: [hello name=”Bob” weather=”rainy”]
… Might output the following: “Hi Bob! It’s another beautiful, rainy day”
Whereas: [hello name=”jane” weather=”sunny”]
… Would output: “Hi Jane! It’s another beautiful, sunny day”

For Developers

Here’s a “dead-simple” shotcode example (You can find this and more in the WordPress.org docs… But I phrase things so nicely, you may as well just read about them here.)

<?php 
function my_shortcode(){ // The function that is our shortode output.
 return "I'm the best.";
}
add_shortcode( 'my-shortcode', 'my_shortcode' ); 
/* use wordpress' add_shortcode function to assign the 'my_shortcode'-function's output (via the return command) to the 'my-shortcode' handle */

… So when we type [my-shortcode] in to the wordpress editor (or widget areas if you have that filter turned on) we get: I’m the best.

Alright, let’s continue kicking-ass. Next step is to make it easier to modify the output of this shortcode… If you’ve worked with php for more then 20 minutes you’ve probably figured out that strings can suck.

What if you want your short-code to return a bunch of html…


<?php 
function my_shortcode(){ // The function that is our shortode output.
$output = ''; // add an empty string
$output .= "<div class="my-shortcode-output"><em>I'm";
$output .= "<strong>the";
$output .= "best</strong></em></div>"; // ... this is going to get old fast.
 return $output;
}
add_shortcode( 'my-shortcode', 'my_shortcode' ); 

So, between strings breaking and editing the content being a pain in the ***… We’ve established that this isn’t the best way to do things. So we’ll use this: ob_start();

ob_start gives you a chunk of memory to work with… Put whatever you want in there and you’ll get it back, without worrying about string output.


<?php 
function my_shortcode(){ // The function that is our shortode output.
ob_start();?>

<div class="my-shortcode-output">
  <em>I'm <strong>the best</strong></em>
</div>

<?php
return $ob_get_clean();
}
add_shortcode( 'my-shortcode', 'my_shortcode' ); 

Much nicer, right? ob_start (Turn on output buffering) with shortcodes. Weird things (like shortcode output appears wrong) can happen because of not using php’s output buffering. When developers starting juggling, concatenating, mixing single / double quotes, html… it’s best done within a memory buffer which gives the encapsulated code enough time to run.

WordPress Shortcode Arguments

Shortcodes don’t just allow you to embed a snippet of code anywhere you want within WordPress… Shortcodes also allow you to pass information to those snippets of code. Arguments, or parameters can be passed to any shortcode. Those arguments (declarative meta-info) are then executed by the shortcode when it’s rendered.

We read earlier that:

  • This shortcode, for example: [hello name=”Bob” weather=”rainy”]
  • … Might output the following: “Hi Bob! It’s another beautiful, rainy day”

But what if we want to output many names? How can we output: “Hi Bob! Hi Doug! It’s another beautiful, rainy day”

In my next post I’ll be reviewing this topic and others. The short-answer is: Use php’s implode / explode to convert the csv-strings in to iterable arrays. (or use regex, but implode / explode is the standard I’ve seen & preferred)

Thanks For Sharing!Share on FacebookShare on Google+Tweet about this on TwitterShare on LinkedIn