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

WordPress Shortcode Fundamentals

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

Shortcodes 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.)

... 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...

$output .= "the";
$output .= "best

"; // ... 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.

I'm the best

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:

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)