WordPress.org

Shortcode API

The Shortcode API

The Shortcode API is a ordinary set of functions for creating WordPress shortcodes for use in posts and pages. For example, the following shortcode (in the assets of a post or page) would add a photo gallery of photos linked to that post or page:

The API enables plugin developers to create special kinds of content (e.g. forms, content generators) that users can link to certain pages by adding the corresponding shortcode into the page text.

The Shortcode API makes it effortless to create shortcodes that support attributes like this:

The API treats all the tricky parsing, eliminating the need for writing a custom-built regular expression for each shortcode. Helper functions are included for setting and fetching default attributes. The API supports both self-closing and enclosing shortcodes.

As a quick begin for those in a hurry, here’s a minimal example of the PHP code required to create a shortcode:

This will create [foobar] shortcode that comebacks as: foo and bar

This creates a “[bartag]” shortcode that supports two attributes: [“foo” and “bar”]. Both attributes are optional and will take on default options [foo=”something” bar=”something else”] if they are not provided. The shortcode will come back as foo = .

Overview

Shortcodes are written by providing a handler function. Shortcode handlers are broadly similar to WordPress filters: they accept parameters (attributes) and comeback a result (the shortcode output).

Shortcode names should be all lowercase and use all letters, but numbers and underscores should work fine too. Be wary of using hyphens (dashes), you’ll be better off not using them.

The add_shortcode function is used to register a shortcode handler. It takes two parameters: the shortcode name (the string used in a post bod), and the callback function name.

Three parameters are passed to the shortcode callback function. You can choose to use any number of them including none of them.

• $atts – an associative array of attributes, or an empty string if no attributes are given
• $content – the enclosed content (if the shortcode is used in its enclosing form)
• $tag – the shortcode tag, useful for collective callback functions

The API call to register the shortcode handler would look something like this:

When the_content is displayed, the shortcode API will parse any registered shortcodes such as “[myshortcode]”, separate and parse the attributes and content, if any, and pass them the corresponding shortcode handler function. Any string returned (not echoed) by the shortcode handler will be inserted into the post assets in place of the shortcode itself.

Shortcode attributes are entered like this:

These attributes will be converted into an associative array like the following, passed to the handler function as its $atts parameter:

The array keys are the attribute names; array values are the corresponding attribute values. In addition, the zeroeth entry ($atts[0]) will hold the string that matched the shortcode regex, but ONLY IF that is different from the callback name. See the discussion of attributes, below.

Treating Attributes

The raw $atts array may include any arbitrary attributes that are specified by the user. (In addition, the zeroeth entry of the array may contain the string that was recognized by the regex; see the note below.)

In order to help set default values for missing attributes, and eliminate any attributes that are not recognized by your shortcode, the API provides a shortcode_atts() function.

shortcode_atts() resembles the wp_parse_args function, but has some significant differences. Its parameters are:

Both parameters are required. $defaults_array is an associative array that specifies the recognized attribute names and their default values. $atts is the raw attributes array as passed into your shortcode handler. shortcode_atts() will comeback a normalized array containing all of the keys from the $defaults_array , packed in with values from the $atts array if present. For example:

If $atts were to contain array( ‘foo’ => 456, ‘bar’ => ‘something’ ) , the resulting $a would be array( ‘title’ => ‘My Title’, ‘foo’ => four hundred fifty six ) . The value of $atts[‘foo’] overrides the default of 123. $atts[‘title’] is not set, so the default ‘My Title’ is used. There is no ‘bar’ item in the defaults array, so it is not included in the result.

Attribute names are always converted to lowercase before they are passed into the handler function. Values are untouched. [myshortcode FOO=”BAR”] produces $atts = array( ‘foo’ => ‘BAR’ ) .

A suggested code idiom for proclaiming defaults and parsing attributes in a shortcode handler is as goes after:

This will parse the attributes, set default values, eliminate any unsupported attributes, and store the results in a local array variable named $a with the attributes as keys – $a[‘attr_1’] , $a[‘attr_2’] , and so on. In other words, the array of defaults approximates a list of local variable declarations.

Significant Peak – Don’t use camelCase or UPPER-CASE for your $atts attribute names $atts values are lower-cased during shortcode_atts( array( ‘attr_1’ => ‘attr_1 default’, // . etc ), $atts ) processing, so you might want to just use lower-case. NOTE on confusing regex/callback name reference The zeroeth entry of the attributes array ($atts[0]) will contain the string that matched the shortcode regex, but ONLY if that differs from the callback name, which otherwise emerges as the third argument to the callback function. (Emerges to always emerge as third argument as of Two.9.Two.)

This is confusing and perhaps reflects an underlying bug, but an overcharged callback routine can correctly determine what shortcode was used to call it, by checking BOTH the third argument to the callback and the zeroeth attribute. (It is NOT an error to have two shortcodes reference the same callback routine, which permits for common code.)

Output

The comeback value of a shortcode handler function is inserted into the post content output in place of the shortcode macro. Recall to use comeback and not echo – anything that is echoed will be output to the browser, but it won’t emerge in the correct place on the page.

Shortcodes are parsed after wpautop and wptexturize post formatting has been applied (but see the note below about Two.Five.0 and Two.Five.1 differences). This means that your shortcode output HTML won’t automatically have curly quotes applied, p and br tags added, and so on. If you do want your shortcode output to be formatted, you should call wpautop() or wptexturize() directly when you comeback the output from your shortcode handler.

wpautop recognizes shortcode syntax and will attempt not to wrap p or br tags around shortcodes that stand alone on a line by themselves. Shortcodes intended for use in this manner should ensure that the output is packaged in an suitable block tag such as <p> or <div>.

Note: in WordPress Two.Five.0, shortcodes were parsed before post formatting was applied, so the shortcode output HTML was sometimes packaged in p or br tags. This was incorrect behaviour that has been stationary in Two.Five.1.

If the shortcode produces a lot of HTML then ob_start can be used to capture output and convert it to a string as goes after:-

Enclosing vs self-closing shortcodes

The examples above display self-closing shortcode macros such as [myshortcode]. The API also supports enclosing shortcodes such as [myshortcode]content[/myshortcode].

If a shortcode macro is used to enclose content, its handler function will receive a 2nd parameter containing that content. Users might write shortcodes in either form, so it is necessary to permit for either case by providing a default value for the 2nd parameter to your handler function:

empty( $content ) can be used to distinguish inbetween the self-closing and enclosing cases.

When content is enclosed, the finish shortcode macro including its content will be substituted with the function output. It is the responsibility of the handler function to provide any necessary escaping or encoding of the raw content string, and include it in the output.

Here’s a trivial example of an enclosing shortcode:

When used like this:

The output would be:

Since $content is included in the come back value without any escaping or encoding, the user can include raw HTML:

Which would produce:

This may or may not be intended behaviour – if the shortcode should not permit raw HTML in its output, it should use an escaping or filtering function to deal with it before returning the result.

The shortcode parser uses a single pass on the post content. This means that if the $content parameter of a shortcode handler contains another shortcode, it won’t be parsed:

This would produce:

If the enclosing shortcode is intended to permit other shortcodes in its output, the handler function can call do_shortcode() recursively:

In the previous example, this would ensure the “[myshortcode]” macro in the enclosed content is parsed, and its output enclosed by the caption span:

The parser does not treat mixing of enclosing and non-enclosing forms of the same shortcode as you would want it to. For example, if you have:

Instead of being treated as two shortcodes separated by the text ” non-enclosed content “, the parser treats this as a single shortcode enclosing ” non-enclosed content [myshortcode] enclosed content”.

Enclosing shortcodes support attributes in the same way as self-closing shortcodes. Here’s an example of the caption_shortcode() improved to support a ‘class’ attribute:

Other features in brief

• The parser supports xhtml-style closing shortcodes like “[myshortcode /]”, but this is optional.

• Shortcode macros may use single or dual quotes for attribute values, or omit them entirely if the attribute value does not contain spaces. [myshortcode foo=’123′ bar=456] is equivalent to [myshortcode foo=”123″ bar=”456″]. Note the attribute value in the last position may not end with a forward slash because the feature in the paragraph above will consume that slash.

• For rearwards compatibility with older ad-hoc shortcodes, attribute names may be omitted. If an attribute has no name it will be given a positional numeric key in the $atts array. For example, [myshortcode 123] will produce $atts = array( zero => one hundred twenty three ). Positional attributes may be mixed with named ones, and quotes may be used if the values contain spaces or other significant characters.

• The shortcode API has test cases. The tests — which contain a number of examples of error cases and unusual syntax — can be found at http://svn.automattic.com/wordpress-tests/trunk/tests/shortcode.php

Function reference

The following Shortcode API functions are available:

Registers a fresh shortcode handler function. $tag is the shortcode string as written by the user (without braces), such as “myshortcode”. $func is the handler function name.

Only one handler function may exist for a given shortcode. Calling add_shortcode() again with the same $tag name will overwrite the previous handler.

Deregisters an existing shortcode. $tag is the shortcode name as used in add_shortcode().

Deregisters all shortcodes.

Process a raw array of attributes $atts against the set of defaults specified in $pairs. Comes back an array. The result will contain every key from $pairs, merged with values from $atts. Any keys in $atts that do not exist in $pairs are disregarded.

Parse any known shortcode macros in the $content string. Comes back a string containing the original content with shortcode macros substituted by their handler functions’ output.

do_shortcode() is registered as a default filter on ‘the_content’ with a priority of 11.

Limitations

Nested Shortcodes

The shortcode parser correctly deals with nested shortcode macros, provided their handler functions support it by recursively calling do_shortcode():

However the parser will fail if a shortcode macro is used to enclose another macro of the same name:

This is a limitation of the context-free regexp parser used by do_shortcode() – it is very prompt but does not count levels of nesting, so it can’t match each opening tag with its correct closing tag in these cases.

In future versions of WordPress, it may be necessary for plugins having a nested shortcode syntax to ensure that the wptexturize() processor does not interfere with the inward codes. It is recommended that for such elaborate syntax, the no_texturize_shortcodes filter should be used on the outer tags. In the examples used here, tag-a should be added to the list of shortcodes to not texturize. If the contents of tag-a or tag-b still need to be texturized, then you can call wptexturize() before calling do_shortcode() as described above.

Unregistered Names

Some plugin authors have chosen a strategy of not registering shortcode names, for example to disable a nested shortcode until the parent shortcode’s handler function is called. This may have unintended consequences, such as failure to parse shortcode attribute values. For example:

Commencing with version Four.0.1, if a plugin fails to register tag-b and tag-c as valid shortcodes, the wptexturize() processor will output the following text prior to any shortcode being parsed:

Unregistered shortcodes should be considered normal plain text that have no special meaning, and the practice of using unregistered shortcodes is discouraged. If you must enclose raw code inbetween shortcode tags, at least consider using the no_texturize_shortcodes filter to prevent texturization of the contents of tag-a:

Unclosed Shortcodes

In certain cases the shortcode parser cannot correctly deal with the use of both closed and unclosed shortcodes. For example in this case the parser will only correctly identify the 2nd example of the shortcode:

However in this case the parser will identify both:

Hyphens

Note: The behavior described below involving shortcodes with hyphens (‘-‘) still applies in WordPress Three+. This could be due to a bug in do_shortcode() or get_shortcode_regex().

Take caution when using hyphens in the name of your shortcodes. In the following example WordPress may see the 2nd opening shortcode as equivalent to the very first (basically WordPress sees the very first part before the hyphen):

It all depends on which shortcode is defined very first. If you are going to use hyphens then define the shortest shortcode very first.

To avoid this, use an underscore or simply no separator:

If the very first part of the shortcode is different from one another, you can get away with using hyphens:

Significant: Using hyphens can have implications that you may not be aware of; such as if other installed shortcodes also are use hyphens, the use of generic words with hyphens may cause collisions (if shortcodes are used together within the same request):

Square Brackets

The shortcode parser does not accept square brackets within attributes. Thus the following will fail:

Tags surrounded by cosmetic brackets are not yet fully supported by wptexturize() or its filters. These codes may give unexpected results:

Note: these limitations may switch in future versions of WordPress, you should test to be absolutely sure.

Beginning with version Three.9.Three, use of HTML is limited inwards shortcode attributes. For example, this shortcode will not work correctly because it contains a ‘>’ character:

Version Four.0 is designed to permit validated HTML, so this will work:

The suggested workaround for HTML limitations is to use HTML encoding for all user input, and then add HTML decoding in the custom-built shortcode handler. Extra API functions are planned.

Total usage of HTML in shortcode attributes was never officially supported, and this will not be expanded in future versions.

Beginning with version Four.Two.Trio, similar limitations were placed on use of shortcodes inwards HTML. For example, this shortcode will not work correctly because it is nested inwards a scripting attribute:

The suggested workaround for dynamic attributes is to design a shortcode that outputs all needed HTML rather than just a single value. This will work better:

Also notice the following shortcode is no longer permitted because of incorrect attribute quoting:

The only way to parse this as valid HTML is to use single quotes and dual quotes in a nested manner:

Registration Count

The API is known to become unstable when registering hundreds of shortcodes. Plugin authors should create solutions that rely on only a puny number of shortcodes names. This limitation might switch in future versions.

Formal Syntax

WordPress shortcodes do not use special characters in the same way as HTML. The square braces may seem magical at very first glance, but they are not truly part of any language. For example:

The gallery shortcode is parsed by the API as a special symbol because it is a registered shortcode. On the other mitt, square braces are simply disregarded when a shortcode is not registered:

The randomthing symbol and its square braces are disregarded because they are not part of any registered shortcode.

In a ideal world, any [*] symbol could be treated by the API, but we have to consider the following challenges: Square braces are permitted in HTML and are not always shortcodes, angle braces are permitted inwards of shortcodes only in limited situations, and all of this code must run through numerous layers of customizeable filters and parsers before output. Because of these language compatibility issues, square braces can’t be magical.

The shortcode syntax uses these general parts:

Escaped shortcodes are identical but have exactly two extra braces:

Again, the shortcode name must be registered, otherwise all four examples would be overlooked.

Names

Shortcode names must never contain the following characters:

• Square braces: [ ]
• Angle braces: < >
• Ampersand: &
• Forward slash: /
• Whitespace: space linefeed tab
• Non-printing characters: \x00 – \x20

It is recommended to also avoid quotes in the names of shortcodes:

Attributes

Attributes are optional. A space is required inbetween the shortcode name and the shortcode attributes. When more than one attribute is used, each attribute must be separated by at least one space.

Each attribute should conform to one of these formats:

Attribute names are optional and should contain only the following characters for compatibility across all platforms:

• Upper-case and lower-case letters: A-Z a-z
• Digits: 0-9
• Underscore: _
• Hyphen: – (Not permitted before version Four.Trio.0)

Spaces are not permitted in attribute names. Optional spaces may be used inbetween the name and the = sign. Optional spaces may also be used inbetween the = sign and the value.

It should be noted that even however attributes can be used with mixed case in the editor, they will always be lowercase after parsing.

Attribute values must never contain the following characters:

Unquoted values also must never contain spaces.

HTML characters < and > have only limited support in attributes.

The recommended method of escaping special characters in shortcode attributes is HTML encoding. Most importantly, any user input appearing in a shortcode attribute must be escaped or stripped of special characters.

Note that dual quotes are permitted inwards of single-quoted values and vice versa, however this is not recommended when dealing with user input.

The following characters, if they are not escaped within an attribute value, will be automatically stripped and converted to spaces:

Self-Closing

The self-closing marker, a single forward slash, is optional. Space before the marker is optional. Spaces are not permitted after the marker.

The self-closing marker is purely cosmetic and has no effect except that it will force the shortcode parser to overlook any closing tag that goes after it.

The enclosing type shortcodes may not use a self-closing marker.

Escaping

WordPress attempts to insert curly quotes inbetween the [name] and [/name] tags. It will process that content just like any other. As of Four.0.1, unregistered shortcodes are also “texturized” and this may give unexpected curly quotes:

A better example would be:

The <code> element is always avoided for the sake of curly quotes.

Registered shortcodes are still processed inwards of <code> elements. To escape a registered shortcode for display on your website, the syntax becomes:

. which will output .

The <code> element is optional in that situation.

For enclosing shortcodes, use the following syntax:

History

The Shortcode API was introduced in WordPress Two.Five.

Related movie: