The best place to find information is on the Efficient Related Posts page which is updated regularly. However, here are some of the new FAQs.

How can I add a list of related posts to my posts?

You can configure Efficient Related Posts to add related posts automatically in Settings -> Related Posts. Alternatively you can use the shortcode [relatedPosts] or the helper functions wp_get_related_posts() and wp_related_posts() in your theme files.

How exactly do you use the [relatedPosts] shortcode?

To use the default settings (from Settings -> Related Posts) you just need to add [relatedPosts] to your post or page where you want to list to be. You can also add some attributes to it such as num_to_display (Number of related posts to display), no_rp_text (Text to display if there are no related posts), and title (Title for related posts list, empty for none) like this:

• [relatedPosts title="Most Related Post" num_to_display="1"]
• [relatedPosts num_to_display="1" no_rp_text="No Related Posts Found"]
• [relatedPosts title="Try these related posts:" num_to_display="3" no_rp_text="No Related Posts Found"]

How do the theme helper functions work?

You can use wp_get_related_posts() and wp_related_posts() to display a list of related posts in your theme. They need to be used in “the loop” and the only difference is that wp_get_related_posts() returns the list and wp_related_posts() echos the list. You can also pass an associative array of arguments to it such as num_to_display (Number of related posts to display), no_rp_text (Text to display if there are no related posts), and title (Title for related posts list, empty for none) like this:

• wp_related_posts(array('title'=>'Most Related Post', 'num_to_display'=>1))
• echo wp_get_related_posts(array('num_to_display'=>1, 'no_rp_text'=>'No Related Posts Found'))
• wp_related_posts(array('title'=>'Most Related Post', 'num_to_display'=>3, 'no_rp_text'=>'No Related Posts Found'))

Related Posts:

• The Problem with Related Post Plugins
• Manual Related Links
• Efficient Related Posts
• WordPress 2.5 Shortcodes

First I touched on the topic in my first impressions of WordPress 2.5. Then I whined a little about the tickets relating to them, and eventually I released my Google Maps Plugin that uses them. In the end, WordPress’s new shortcodes are really nice.

What are they?

First of all, a shortcode called “mycode” can look like any of these:

[mycode]
[mycode foo="bar" id="123" color="red" something="data"]
[mycode]Some Content[/mycode]
[mycode]<p><a href="http://example.com/">HTML Content</a></p>[/mycode]
[mycode]Content [another-shotcode] more content[/mycode]
[mycode foo="bar" id="123"]Some Content[/mycode]

As you can see, shortcodes allow a user to put a code into a post or page, and a plugin can then easily handle those codes. They can be nested, contain content (including HTML), attributes, etc. Sounds great, but how can you leverage shortcodes for your benefit?

How can I use them?

You want to leverage the new, powerful shortcode system in WordPress 2.5, but where do you start?

First of all, you need to add your shortcode:

add_shortcode('mycode', 'yourFunction');

Your function should take two arguments and return the content that you want to replace the shortcode with. The first argument will be an associative array of attributes (keys will be the attribute names, and the value will be the corresponding attribute value), and the second will be the content between the tags.

To handle default attributes, you can use shortcode_atts($defaultsArray, $attributesArray):

function yourFunction ($attr, $content) {
    $attr = shortcode_atts(array('foo'   => 'bar',
                                 'id'    => '',
                                 'color' => 'blue'), $attr);
    return '<h2>Attributes</h2><pre>' . print_r($attr, true) . '</pre><h2>content</h2>' . $content;
}

That’s it! That’s why they are so great, it takes next to nothing to handle! However, maybe you’re thinking about a relatively complex way to use these, and you want to take it to the next level.

The Next Level

Maybe you’re worried that you’re users won’t grasp the intricacies of your shortcodes, or will be plagued by typos. It’s a valid concern. For example, I don’t want to assume that my users will be able to create a Google map by flawlessly entering:

The solution is to create a way for your users to generate the shortcodes and have them sent to the editor, but where to start? First, you need to add a meta box to the writing/editing pages (these are the dropdown boxes below the editor, such as Tags, Categories, etc). To do this, create a function that you will use to display the form used to generate your shortcode (I’m going to call it “insertForm”). Then you need to hook into the admin_menu action, and use it to create the metaboxes:

<?php
function handleAdminMenu() {
    // You have to add one to the "post" writing/editing page, and one to the "page" writing/editing page
    add_meta_box('yourMetaBoxID', 'Your Meta Box Title', 'insertForm', 'post', 'normal');
    add_meta_box('yourMetaBoxID', 'Your Meta Box Title', 'insertForm', 'page', 'normal');
}

function insertForm() {
?>
        <table class="form-table">
            <tr valign="top">
                <th scope="row"><label for="wpYourPluginName_content"><?php _e('Tag Content:')?></label></th>
                <td>
                    <input type="text" size="40" style="width:95%;" name="wpYourPluginName[content]" id="wpYourPluginName_content" />
                </td>
            </tr>
            <tr valign="top">
                <th scope="row"><label for="wpYourPluginName_foo"><?php _e('Foo Attribute:')?></label></th>
                <td>
                    <input type="text" size="40" style="width:95%;" name="wpYourPluginName[foo]" id="wpYourPluginName_foo" />
                </td>
            </tr>
            <tr valign="top">
                <th scope="row"><label for="wpYourPluginName_bar"><?php _e('Bar Attribute:')?></label></th>
                <td>
                    <input type="text" size="40" style="width:95%;" name="wpYourPluginName[bar]" id="wpYourPluginName_bar" />
                </td>
            </tr>
        </table>
        <p class="submit">
            <input type="button" onclick="return wpYourPluginAdmin.sendToEditor(this.form);" value="<?php _e('Send Map to Editor &raquo;'); ?>" />
        </p>
<?php
}

function adminHead () {
    if ($GLOBALS['editing']) {
        wp_enqueue_script('wpYourPluginNameAdmin', 'path/to/yourJsFile.js', array('jquery'), '1.0.0');
    }
}

add_action('admin_menu', 'handleAdminMenu');
add_filter('admin_print_scripts', 'adminHead');
?>

The specifics:
yourMetaBoxID becomes the id of the metabox div.
“Your Meta Box Title” will be the displayed title for the metabox.

You may have noticed that the submit button calls some javascript (specifically wpYourPluginAdmin.sendToEditor(this.form)), and we enqueue a JavaScript file. Here is that file:

/**
 * Handle: wpYourPluginNameAdmin
 * Version: 0.0.1
 * Deps: jquery
 * Enqueue: true
 */

var wpYourPluginNameAdmin = function () {}

wpYourPluginNameAdmin.prototype = {
    options           : {},
    generateShortCode : function() {
        var content = this['options']['content'];
        delete this['options']['content'];

        var attrs = '';
        jQuery.each(this['options'], function(name, value){
            if (value != '') {
                attrs += ' ' + name + '="' + value + '"';
            }
        });
        return '


'
    },
    sendToEditor      : function(f) {
        var collection = jQuery(f).find("input[id^=wpYourPluginName]:not(input:checkbox),input[id^=wpYourPluginName]:checkbox:checked");
        var $this = this;
        collection.each(function () {
            var name = this.name.substring(13, this.name.length-1);
            $this['options'][name] = this.value;
        });
        send_to_editor(this.generateShortCode());
        return false;
    }
}

var wpYourPluginAdmin = new wpYourPluginNameAdmin();

This JavaScript parses items from the form, formats a shortcode, and sends it to the editor! Now you can create an interface for your user, to allow to easily generate VALID shortcodes for you to parse.

Related Posts:

• Reorder Gallery now in WordPress Core
• WordPress Should Update get_sidebar to Work With Multiple Sidebars
• Speaking at WordCamp San Francisco 2011
• WordPress Q & A
• Google Summer of Code 2010