Shortcodes
Overview #
In order to add an extra layer of security to your site, WordPress doesn’t allow you to add PHP code to a post. This prevents users from accidentally running code that causes their site to crash or become non-functioning. You may want to allow users to inject dynamic content that requires using PHP to accomplish a task, however. To do this you have to enter the shortcode.
A shortcode is analogous to a macro where a single instruction can expand to do a number of tasks. In short, a shortcode acts as a “shortcut” that can be used to represent a photo gallery, list of posts, contact form or other pieces of dynamic functionality. WordPress has supported shortcodes since Version 2.5.
Here is a simple example of a shortcode to add a gallery to a post or page:
[gallery]
Here is an example of a shortcode that includes attributes, i.e. additional instructions within the square brackets.
[gallery id="1" size="medium"]
To add a shortcode, type in the shortcode from the HTML or Visual views of the Post or Page edit area. If you are using a shortcode with more complex attributes, you may want to copy and paste it in from the shortcode’s documentation page if there is one to ensure you get the right syntax.
Why Shortcodes? #
Shortcodes are a valuable way of keeping content clean and semantic, and affording end users some ability to programmatically alter the presentation of their content. When the end user adds a photo gallery to their post using a shortcode, they’re using the least data possible to indicate how the gallery should be presented.
One key advantage: no markup is added to the post content, which means that markup and styling can easily be manipulated on the fly or at a later date. Shortcodes can also accept parameters, allowing users to modify how the shortcode behaves on an instance by instance basis based on the attributes entered.
Parameters #
At the minimum, using the Shortcode API involves registering both a shortcode and callback function with add_shortcode(). It’s as though you’re allowing the end user to use PHP functions within their post content, but in a much safer, more protected manner.
add_shortcode() callback functions can receive up to three parameters:
$atts, an associative array of attributes, or an empty string if no attributes are given$content, the enclosed content (if the shortcode wrapped around some content)$tag, the current shortcode tag, useful for shared callback functions
Shortcode Best Practices #
The best practices for developing shortcodes are similar to the general plugin development best practices however with shortcodes there is also an element the user interacts with. Here are a few general best practices for working with shortcodes.
- Return output, don’t echo it. Shortcodes are essentially filters, so sending output or altering global variables can create bugs that are difficult to track down.
- Prefix your shortcode names, to avoid collisions with other plugins.
- Sanitize the input, and escape the output.
- Provide users with clear documentation on any shortcode attributes.
