Function Documentation

WordPress Function Documentation Progress

Shortcodes API

WordPress 2.5 adds the ability to register bbcode style formats in plugins for post content only. I have a plugin that converts language specific bbcodes to genshi style. It however parses the content manually. Using the new API, it only needs to register each language or a single name and use an attribute for each language.

The functions for plugins are add_shortcode() and remove_shortcode(). The functions exist in wp-includes/shortcodes.php and offer a basic functionality. Overall, the addition will decrease the hassles of plugin authors and unify the standard of replacing short tags that a lot of plugins use in their plugins. This will be a great boon for plugin authors.

How to Add a Shortcode

Lets say that we want to support the bbcode code ‘b’ and add support for it in post content. We would first register the ‘b’ short code with the function which which will replace the ‘[b]‘ and ‘[/b'] with ‘<‘ and ‘>’ respectively.

function bbcodeplugin_b($attr, $content='')
{
    if( empty( $content ) )
    {
        return '';
    }

    return '<strong>'. $content .'</strong>';
}

add_shortcode('b', 'bbcodeplugin_b');

The first parameter catches any attributes that the user might have added between the “[b ...]content[/b]” that will be caught and given to your plugin function.

In the example of using geshi, lets create a plugin short code which, in theory, will allow any number of languages to be converted to geshi styles.

function genshiplugin_genshi($attr, $content='')
{
    if( empty( $content ) )
    {
        return '';
    }

    return genshi_conversion_function_or_method($attr['lang'], $content);
}

remove_shortcode('genshi');

add_shortcode('genshi', 'genshiplugin_genshi');

In this example, we remove any plugin that might have registered their own and replace it with our function instead. If you are going to create something that is generally generic, then it is a good idea to choose something that either has your plugin name or in the case of the above example used a generic ‘code’, so that the user doesn’t have to go through all post content to replace the bbcode style to switch over to your plugin. However, if the user wants to use multiple methods, then let the user decide with an option.

Most Common Replacement

Many plugins replace a “tag” in the content with their own content or run a special filter and add forms or pictures or any number of special content. Many plugins build their own regular expressions to process the content to look for the content. With the short code API, this is no longer necessary.

If I wanted to replace every instance of “[myplugin]” with “My Plugin is Awesome”. I can use the above examples and just return the “My Plugin is Awesome”.

function myplugin_is_awesome($attr)
{
    return 'My Plugin is Awesome';
}

add_shortcode('myplugin', 'myplugin_is_awesome');

Adding Shortcode to more filters

The default filter (as of this writing, it might be added to more when 2.5 is released), is ‘the_content’, but you might want to apply the code to comments and excerpts or any other filter. As a warning, some plugins might register codes which might make it unsafe to be used in comments, so be careful with what is exactly registered and confirmed with comments.

add_filter('the_excerpt', 'do_shortcode');

Or if you don’t want to use short codes, add the following to a plugin.

remove_filter('the_content', 'do_shortcode');

How Fast is Shortcode?

The API is extremely optimized and fast for what it does. It is doubtful that it can be optimized any further and barring any defects, it probably will stay quick. It also appears that it doesn’t use the built-in plugin API, so that means that one function can exist for each shortcode. You won’t be able to run a ‘code’ shortcode tag through two or more filters, only one can exist for the short code. This decreases the time spent, but removes one of the best features in the Plugin API.

About these ads

February 3, 2008 - Posted by | Writing Plugins Series | , , ,

9 Comments »

  1. [...] and is relatively well commented. Jacob Santos also has a nice and detailed overview of the API Share [...]

    Pingback by WordPress 2.5 ShortCodes API Overview « planetOzh | March 28, 2008 | Reply

  2. [...] ShortCode API. [...]

    Pingback by g30rg3 Blog » WordPress 2.5 “Michael Brecker” | April 2, 2008 | Reply

  3. is there a way to add a shortcode to a sidebar textwidget?

    Comment by albandi | May 30, 2008 | Reply

  4. The wordpress shortcodes will work only by default on posts and pages. You could add this statement add_filter(‘widget_text’, ‘do_shortcode’); to your wordpress themes functions.php file to make the shortcodes work in the Text Widget. You will need to replace “do_shortcode” with the name of your shortcode function.

    To use your shortcodes outside of posts, pages, and the text widget, you could always call your shortcode function directly like this:

    $text = yourShortCodeFunction('[your shortcode tag here]');
    echo $text;
    

    The above code will allow you to use wordpress shortcodes anywhere in your blog. Great post on using the wordpress shortcodes API.

    Comment by Eagle | October 9, 2008 | Reply

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

    [php]function shortcode_id() {
    $id = the_ID();
    echo $id;
    }
    add_shortcode(‘id’, ‘shortcode_id’);
    [/php]

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

    I also tried: [php]echo the_ID();[/php] but it doesn’t work either.

    Comment by Jasmine | February 18, 2009 | Reply

    • This is because the_ID() echos the ID and does not return it.

      Comment by Jacob Santos | February 18, 2009 | Reply

  6. I’m just trying to figure out whether I’ve noticed an issue with shortcodes that can hopefully by easily fixed. You seem to know a lot about the class so I thought I’d try my luck here as no response so far from the wordpress forums.

    Anyway, the bug is that code like this:

    Testing [intlink id="1" /] self close. [intlink id="2"]Testing content[/intlink]

    becomes:

    Testing selc close. Testing content

    As you can see, the first opening shortcode is running until the last closing tag, even thought it is self closed.

    Having read the manual I understand the shortcode parser can’t handle nesting of the same tags, but in this case I’m not trying to nest!

    Is this a bug or am I doing something wrong?

    Comment by Cohen | March 1, 2009 | Reply

    • The parsing of the short codes is very strict. So if it does self closing, it might need to not have a space between the quote and bracket. There does not seem to be a bug. The wautop is trying to fix your markup to prevent invalid XHTML. Might be an issue with the plugin.

      Comment by Jacob Santos | March 2, 2009 | Reply

  7. Thanks for getting back to me Jacob. I tried without the space after the attributes but no luck.

    I think the fault is in the shortcode functions, not the plugin. For a self closed tag I am being sent content in the second parameter. There are also no attributes or parameters to tell my function that it is a self closing tag.

    I’ve made a quick test page to highlight what I mean. http://blograndom.com/tests/shortcode/

    Do you happen to know where I can submit a bug? On the wordpress.org site it seems the forum is the only place.

    Comment by Cohen | March 2, 2009 | Reply


Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

Follow

Get every new post delivered to your Inbox.

%d bloggers like this: