In: , , ,
On: 2008 / 03 / 28 Viewed: 77790 times
Shorter URL for this post: http://ozh.in/hb

WordPress 2.5 comes with a very handy API that plugin authors should love: shortcodes, ie. BBcode-like tags, that are parsed when found in post contents. The API is very easy to use, and well done enough that it's relatively foolproof.

Shortcode types

The API allows for all the possible combinations and forms you'd think of: selfclosing or open tags, attributes with single or double quotes.

  1. [tag]
  2. [tag /]
  3. [tag attribute="value" /]
  4. [tag attr1='value1' attr2="value2" ]
  5. [tag]enclosed content[/tag]
  6. [tag attr="value"]enclosed content[/tag]

The Concept

First, you have to define a function that will take care of your shortcodes, their potential attributes, and any enclosed content:

  1. function my_shortcode_func($attr, $content) {
  2.     // $attr is an array of $key=>$value pairs
  3.     // $content is a string containing the enclosed content
  4.     // ... do something with $attr and $content
  5.     // return the expected result
  6. }

Then, to register your new shortcode so that [tag attr="value"]content[/tag] is processed as wished by my_shortcode_func(), you just add:

  1. add_shortcode('tag', 'my_shortcode_func');

All API functions

The API comes with a set of mostly self explanatory functions you can use:

  1. add_shortcode('tag', 'function_name'); // register a new shortcode
  2. remove_shortcode('tag'); // unregister
  3. remove_all_shortcodes(); // just as it says
  4. $return = do_shortcode($content); // apply shortcodes to content without echoing anything

Examples

[tag1] → Some Longer Text

  1. function shortcode_example1() {
  2.     return 'Some Longer Text';
  3. }
  4. add_shortcode('tag1', 'shortcode_example1');

[tag2 param="something"] → Some Longer Text and something

  1. function shortcode_example2($attr) {
  2.     return 'Some Longer Text and '.$attr['param'];
  3. }
  4. add_shortcode('tag2', 'shortcode_example2');

[tag3]something[/tag3] → You just said "something", didn't you ?

  1. function shortcode_example3($attr, $content) {
  2.     return "You just said '$content', didn't you ?";
  3. }
  4. add_shortcode('tag3', 'shortcode_example3');

[tag4 any attribute]something[/tag4] → Attributes: {list of attributes}. Content: {content}

  1. function shortcode_example4($attr, $content) {
  2.     $attributes = '';
  3.     foreach ($attr as $key=>$value) {
  4.         $attributes .= "$key: $value\n";
  5.     }
  6.     return "Attributes: $attributes<br/>Content: $content";
  7. }
  8. add_shortcode('tag4', 'shortcode_example4');

Experiment and read more

Test and experiment: all the examples above are gathered into this simple Shortcodes plugin example (rename as shortcodes.php and put in your plugin directory). It's interesting to try to break things with unexpected attributes or enclosed content: the API is pretty foolproof and should ignore things just as you'd thought it should.

Read more : the whole API can be found in wp-includes/shortcodes.php and is relatively well commented. Jacob Santos also has a nice and detailed overview of the API

Shorter URL

Want to share or tweet this post? Please use this short URL: http://ozh.in/hb

Metastuff

This entry "WordPress 2.5 ShortCodes API Overview" was posted on 28/03/2008 at 12:35 pm and is tagged with , , ,
Watch this discussion : Comments RSS 2.0.

12 Blablas

  1. 1
    johnbillion United Kingdom »
    thought, on 28/Mar/08 at 6:20 pm # :

    Ozh, I'm really loving your introductions to the new APIs in WordPress. Great examples and great writing. Thanks and keep it up!

  2. 2
    Paul Menard United States »
    wrote, on 12/May/08 at 1:07 am # :

    So one thing I've wondered about with the new shortcode. Since this is created in the actual post content what safe guards are in place to prevent the unfiltered shortcode from being passed the the presentation layer or viewable user version?

    This was my biggest issue with some of the earlier shortcode plugin for like SWF or youtube videos. I add the code and link to the video into my post. Then if later I deactivated the plugin or changed plugins the shortcode would be revealed to the user.

  3. 3
    Ozh France »
    wrote, on 12/May/08 at 1:19 am # :

    Paul Menard » I had the same concern and proposed that instead/in parallel of [stuff] it should be <!–stuff–> but despite some traction the idea was rejected…
    So basically, yes, when you disable a plugin that parses shortcodes, everybody see them. Quite lame.

  4. 4
    WordPress 2.5 Shortcode API - bueltge.de... Germany »
    pingback on 28/May/08 at 7:18 am # :

    […] kleine Einführung und ersichtliche Erfolge gibt es in Kurzversion in den folgenden Zeilen. Wie es genau geht und ein Plugin mit verschiedenen Beispielen gibt es bei Ozh, der derzeit auch die neue WordPress Funktion […]

  5. 5
    WordPress Shortcode API - WP Engineer Germany »
    pingback on 17/Nov/08 at 3:08 pm # :

    […] It's easy to understand and to use. I will give a short introduction with some results below. The functionality and all details behind, plus a plugin with different examples are available at Ozh. […]

  6. 6
    Jasmine United Kingdom »
    thought, on 18/Feb/09 at 7:38 pm # :

    I am trying to use short code to display the post id inside a post, however when I use [id] it is showing the post ID at the start of the post of the post content, not where I have typed it.

    The shortcode I am using, I have placed this in the plugin folder.

    1. function shortcode_id() {
    2.    $id = the_ID();
    3. echo $id;
    4. }
    5. add_shortcode('id', 'shortcode_id');

    What displays on the post page: 10741This is a good post. This is Post ID:

    I also tried:

    1. echo the_ID();

    but it doesn't work either.

  7. 7
    Ozh France »
    commented, on 18/Feb/09 at 9:20 pm # :

    Jasmine » Your shortcode function *echoes* something when it's supposed to *return* content.

  8. 8
    Alper Turkey »
    said, on 25/Oct/09 at 4:03 am # :

    Hi Ozh i have the same problem with Jasmine and my shortcode returns the code part as always, i mean my shortcode is [ gpc id= "name" ] and on the top of all my pages/posts that i used shortcode name variable is seen.
    in the function tried that if user enter "name" as shortcode show a div that named as "name".. How can i stop that? Thanks right now..

  9. 9
    Alper Turkey »
    thought, on 25/Oct/09 at 4:22 am # :

    Problem is solved, i'am sorry for excess post. You all right, i've forgotten an echo command for testing.. Thanks for that nice writing..

  10. 10
    Kris Canada »
    replied, on 23/Aug/10 at 9:14 am # :

    So,,

    I created a basic plugin and inserted this into it

    // [tag3]something[/tag3] -> You just said "something", didn't you ?
    function shortcode_example3($attr, $content) {
    return "You just said '$content', didn't you ?";
    }
    add_shortcode('tag3′, 'shortcode_example3′);

    In the post I inserted this:

    [tag3]Hello[/tag3]

    and my output in the post is still

    [tag3]something[/tag3]

  11. 11
    Kris Canada »
    wrote, on 23/Aug/10 at 9:15 am # :

    Sorry,,

    My output is still

    [tag3]Hello[/tag3]

    not [tag3]something[/tag3]

  12. 12
    Kristina Canada »
    commented, on 24/Aug/10 at 5:17 pm # :

    Ahh,, figured it out. Works fine,,, except

    My short-code shows in the xml feed of the site as short-code. How would I apply the filter to prevent this from happening?

Leave a Reply

Comment Guidelines or Die

  • HTML: You can use these tags: <a href=""> <em> <i> <b> <strong> <blockquote>
  • Posting code: Post raw code (no <> &lt; etc) within appropriate tags : [php][/php], [css][/css], [html][/html], [js][/js], [sql][/sql], [xml][/xml], or generic [code][code]
  • Gravatars: Curious about the little images next to each commenter's name ? Go to Gravatar.
  • Spam: Various spam plugins on patrol. I'll put pins in a Voodoo doll if you spam me.
  • I will mark as Spam test comments, all comments with SEO names (ie "My Cool Online Shop" instead of "Joe") or containing forum-like signatures.

Read more ?