WordPress shortcodes allow developers to let authors customize certain aspects of their posts in a controlled way. Since the TinyMCE editor does tend to yield inconsistent results for raw HTML (even when entered in the Text tab), shortcodes are a great way to be sure that code will output as intended when used in the WordPress WYSIWYG editor. Furthermore, it’s not that hard! If you have a basic knowledge of PHP you can dive right in; you’ll need an understanding of variables and functions (and if you don’t, still give it a try).
I am going to just graze the surface of shortcodes in order to give a basic understanding of how they work, but they can get as crazy as needed. Feel free to comment with any questions.
Getting started
In your theme directory, find the functions.php file. This file is one of the first files to be loaded by the WordPress CMS, and is where your shortcodes (along with MANY other customizations are stored).
Open functions.php and let’s add our function at the bottom- make sure not to add anything (even a space) after the closing ?> tag! We will be using a core WordPress function called add_shortcode() to create ours. The first parameter of this function is the shortcode name that will trigger it, and the second is the function that will be triggered. I would recommend prepending your function name to prevent conflicts with others. In this case, I’m calling my shortcode “yolo” which will be triggered with [yolo], and the function it will call when triggered is named “gearside_yolo_shortcode”.
Here is the basic framework of a shortcode function:
PHP
Passing Parameters
Your custom function will need parameters itself, too! The standard shortcode parameters are $atts and $content. $atts are attributes within the opening tag of the shortcode, and $content is whatever is inbetween the opening and closing shortcode tags.
Generally, I like to pass classes and styles as optional attributes, and also set the $content to an empty string by default. Here is how to do that:
PHP
In the extract line is where you will declare which variables you want to detect from the $atts. In the above example I’m using “class” and “style” and setting them both to an empty string by default (this allows them to be optional attributes). The $content variable is declared as a standard function parameter in the line above.
Most importantly about the $atts parameters is that each one is stored as it’s own variable once it is extracted. So in the above example, I can now work with the following variables: $class, $style, and $content.
Let’s Do Some Stuff
Now we can get to the fun action. This part will depend entirely on what you want to do! Every shortcode will be different. In this one let’s wrap the passed content in a div with white text and a blue background.
PHP
Pretty easy, right? Just return a string of HTML. If you are learning PHP, the periods that are separating the strings and variables are for concatenating (a $5 word for combining). I also like to add a hard-coded class of the shortcode name so that it can be targeted globally from a stylesheet.
Here is an example implementation of this shortcode followed by what it would return with the example function.
[yolo]Lorem ipsum dolor sit amet.[/yolo]
Here is the same thing with additional attributes:
[yolo style=”text-align: center; padding: 5px; text-transform: uppercase;”]Lorem ipsum dolor sit amet.[/yolo]
If you’d like to peak at some more advanced shortcodes, check out this file that I use for my Nebula WordPress theme starter framework. It shows some additional things like flags (attributes without values) and more.
I hope this is a good stepping stone for learning WordPress shortcodes and even PHP in general. There is much more to be discovered with shortcodes, and if you come up with something really clever let me know!
