[Coding Snippets #4]: Custom Wordpress Shortcodes

Hello everyone once again, time for another Coding Snippet! This time, we will create our own shortcode. Shortcodes are like custom functions, but are to be executed almost everywhere in Wordpress. This opens up a world of unlimited power to customize our site as we see fit!

Intro

Wordpress has a few shortcodes included, mainly for multimedia. As the Plugin Developer Handbook suggests:

Shortcodes are a valuable way of keeping content clean and semantic while allowing end users some ability to programmatically alter the presentation of their content.

But we have to be very careful with our shortcodes, as they may have unintended consequences if they are not done correctly.

Basic shortcode: hello-world

Note: all code should go in the functions.php file of the theme you are currently using, or if you are a little bit more advanced, you could create a plugin for this. I will write a post in the future about creating an custom plugin. To put the code in the functions.php file of your theme, go to Appearance -> Theme Editor and on the right sidebar choose Theme Functions

As it is fit for any tutorial, we will create a "Hello World" shortcode. Wherever we put the shortcode [hivehi], it will print "Hello World of Hive!".

function short_hello_hive() {
    return "Hello World of Hive!";
}
add_shortcode( 'hivehi', 'short_hello_hive' );

We save the file and then we create a new post or page to test it out. Just type [hivehi] as the post/page content, save the post/page and navigate to see it.

The image above shows on the top side what should you type in the editor, and on the bottom the actual result of the shortcode.

So what can I do with this?

Basically, anything! You could add the current user's display name at some point of the text, to make it personalised to the current reader:

function short_hello_hive() {
    $user = wp_get_current_user();
    $display_name = $user->display_name;
    return "Hello World of Hive and " . $display_name;
}
add_shortcode( 'hivehi', 'short_hello_hive' );

If the current viewer's Display Name is dimitrisp, it should show:

However, if the viewer is a guest, the output will be:

So, we should also check if user is logged, and return the appropriate value:

function short_hello_hive() {
    if (is_user_logged_in()) {
    $user = wp_get_current_user();
        $display_name = $user->display_name;    
    } else {
        $display_name = "visitor";
    }
    
    return "Hello World of Hive and " . $display_name;
}
add_shortcode( 'hivehi', 'short_hello_hive' );

And at this point, a not-logged in reader will see this message:

Can I add parameters?

Sure, they are usually called "attributes" in the shortcode world of Wordpress. We should define an input parameter, such as $atts on the function, and then use it for output on our return (or anywhere else we might want to manipulate the input):

function short_hello_hive($atts) {
    if (is_user_logged_in()) {
    $user = wp_get_current_user();
        $display_name = $user->display_name;    
    } else {
        $display_name = "visitor";
    }
    
    return "Hello World of Hive and " . $display_name . " from " . $atts['from'];
}
add_shortcode( 'hivehi', 'short_hello_hive' );

So, when we add [hivehi from="test"] to our post, we will get this message:

Is that it?

If your shortcode has parameters, you should put a check for actual content (and validate that it is of the correct form), otherwise on the final example the output will be Hello World of Hive and dimitrisp from. I'll leave this part as an exercise for you!

Feel free to write a comment if you have any questions!

_{WordPress is a registered trademark of The Wordpress Foundation. Wordpress and the code I talked about in the post are both released under the GPLv2 license. You can read the license terms here}