How To Create A WordPress Custom Shortcode
Shortcode has become part of the WordPress for a long time. Without shortcode in WordPress, it feels like a body without a limb. Shortcode simplifies the process of adding features to a WordPress site without the need of writing codes in posts, pages or widgets. It makes a lot easier to insert HTML or another markup to be added to your WordPress site.
I guess some of you eager to know how to create a WordPress shortcode. And in this article, I will show you how to create a WordPress custom shortcode. I will also share with you other info related WordPress shortcode.
What is Shortcode?
A shortcode is a WordPress-specific code that allows you to do various things without any hassle. It introduced since WordPress version 2.5 for creating macros to be used on your WordPress site. There are 3 commonly used variations of WordPress shortcodes which are categorized as:
To create a WordPress custom shortcode, you need to save shortcode snippets in your theme functions.php or site-custom plugin. But I would strongly recommend you to save snippets in the site-custom plugin. You might want to read advantages of saving scripts in the site-custom plugin instead of functions.php. Or check out how to create a WordPress site-custom plugin.
Creating A Shortcode
Before we start creating a shortcode, let's run through the shortcode API (Application Programming Interface). A shortcode API is a set of WordPress functions which is used to create a shortcode easily by developers. This shortcode API will handle all the parsing without the need to write a custom regular expression for each shortcode. It also supports both enclosing and non-enclosing shortcodes.
For your information, in shortcodes, we don't echo anything instead everything is returned. To create a WordPress custom shortcode, you need:
- A PHP function which will return a string of HTML code.
- A call to WordPress add_shortcode() hook which binds a shortcode to above function.
There are 2 parameters in add_shortcode() hook which both are required and have no default value. The first parameter is a $tag string where this value will be your shortcode name.
For example, if your $tag string is awesome, then your shortcode will be [awesome]. The second parameter is called $func which will be used to call your function. In other words, your function name and $func value must be same otherwise our shortcode won't work. Please take a look at the code below.
Basic Shortcode or Non-Enclosing Shortcode
Basic shortcode or known as non-enclosing shortcode is the first variation of WordPress shortcode. It is a shortcode that does not require to wrap or contain other content. This variation of shortcode exists as a single self-closed shortcode similar to self-closing HTML tag such as <br /> tag. Let's take a look at the example of basic shortcode below.
After you save above snippet in your functions.php or preferably site-custom plugin, enter [mycode] somewhere on any post or page and save it. Next visit that page and you will see it's been dynamically replaced with a "This is my first shortcode!" paragraph. Pretty simple, isn't it?
Unlike Basic shortcode, Enclosing shortcode is required to wrap or contain other content. It is the second variation of WordPress shortcode. This variation of shortcode is quite similar to regular HTML tag which requires an opening and closing tag.
Some of the example usages of Enclosing shortcode is creating a button, a styled link or a span tag. Let's take a look at the code below for Enclosing Shortcode example.
If you notice, there are $content = null in the code above. Null serves as default value shall in case a user forgot to put a value on it. Feel free to change null to other value as per your need.
Now let's continue this tutorial by saving above snippet and enter [newcode]This is my sample note.[/newcode] anywhere in your post or page. Next, visit your post or page and view your HTML source code. You will see that your Enclosing Shortcode has been rendered just like in the code below.
As for our third variation of WordPress shortcode which called Attributes shortcode is quite similar to the Basic shortcode. It does not need to wrap or contain content. The only difference from Basic shortcode is it supports one or more attributes. Please take a look at example code below where we use 2 attributes for our Attributes shortcode.
As you have seen, I have set a default value for the title and author respectively as a fallback. Therefore, shall in case any attribute value isn't provided, this shortcode will still run by default.
Assuming that you already save above snippet, let's test our shortcode now by entering this shortcode below anywhere on your posts or pages. If everything is correct, your Attributes shortcode will be rendered as the second snippet.
By now, I'm sure you already have ideas about 3 commonly used variations of WordPress shortcode. But did you know that WordPress itself comes with built-in shortcodes? Please keep in mind that some themes or plugins may have their own shortcodes as well. Below are some of built-in WordPress default shortcodes:
- [audio] is a shortcode which allows you to embed audio files.
- [caption] allows you to wrap captions around content.
- [gallery] can be used when you to add one or more images to your posts and pages.
- [playlist] allows you to display a collection of WordPress audio or video files.
- [video] is a shortcode similar to [audio] but allows you to embed video files.
Disabling A Shortcode
There may be times where you want to disable your shortcode or simply want to show it as a plain word to your readers. In this case, you can do this by escaping your shortcode. To do this, you can use 2 sets of brackets instead of one. Please take a look at below example.
Usage In Other Areas
Originally, you can only use a shortcode directly within posts and pages. While to use a shortcode in the sidebar widgets will require you to add both of this filters which is add_filter('widget_text', 'shortcode_unautop'); and add_filter('widget_text', 'do_shortcode'); in this exact order to add support for the sidebar widgets.
But since WordPress version 4.9, it has been improved where you can now using shortcode directly on WordPress sidebar widgets without applying any filter.
In any case, you need to use a shortcode in another area such as in your theme specific section or create a nested shortcode; you can use a nifty WordPress function called do_shortcode(). Below is the example usage of do_shortcode() function.
If you follow the steps noted in this article, you should have a basic understanding of how to create a WordPress custom shortcode and 3 variations of most commonly used shortcodes. Please keep in mind that above snippets are just simply an easy example of how to create a WordPress custom shortcode.
By using the concept of FIEO (Filter Input Escape Output), don't forget to secure your codes where appropriate especially if you run a multi-author blog. You might want to read 5 basic security practices for additional info. I'm sure by now you have created your first shortcode. Please share with us about your first shortcode in the comment section below.
He is a web developer, a programmer, and a computer technician. He obsessed with coding and enjoy learning new things. In his spare time, he likes to play online games, musical instruments or watching anime and movies.