The\u00a0Shortcode API<\/strong>\u00a0is a simple set of functions for creating WordPress\u00a0shortcodes<\/a>\u00a0for use in posts and pages. For instance, the following shortcode (in the body of a post or page) would add a photo gallery of images attached to that post or page:\u00a0 The API enables plugin developers to create special kinds of content (e.g. forms, content generators) that users can attach to certain pages by adding the corresponding shortcode into the page text.<\/p>\n\n\n\n The Shortcode API makes it easy to create shortcodes that support attributes like this:<\/p>\n\n\n\n The API handles all the tricky parsing, eliminating the need for writing a custom regular expression for each shortcode. Helper functions are included for setting and fetching default attributes. The API supports both self-closing and enclosing shortcodes.<\/p>\n\n\n\n As a quick start for those in a hurry, here’s a minimal example of the PHP code required to create a shortcode:<\/p>\n\n\n\n This will create With attributes:<\/p>\n\n\n\n This creates a The Shortcode API was introduced in WordPress 2.5.<\/p>\n\n\n\n Shortcodes are written by providing a handler function. Shortcode handlers are broadly similar to WordPress filters: they accept parameters (attributes) and return a result (the shortcode output).<\/p>\n\n\n\n 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.<\/p>\n\n\n\n The Three parameters are passed to the shortcode callback function. You can choose to use any number of them including none of them.<\/p>\n\n\n\n The API call to register the shortcode handler would look something like this:<\/p>\n\n\n\n When the_content<\/a> is displayed, the shortcode API will parse any registered shortcodes such as Shortcode attributes are entered like this:<\/p>\n\n\n\n These attributes will be converted into an associative array like the following, passed to the handler function as its The array keys are the attribute names; array values are the corresponding attribute values. In addition, the zeroeth entry ( The raw\u00a0 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()<\/a> function.<\/p>\n\n\n\n Both parameters are required. If Attribute names are always converted to lowercase before they are passed into the handler function. Values are untouched. A suggested code idiom for declaring defaults and parsing attributes in a shortcode handler is as follows:<\/p>\n\n\n\n This will parse the attributes, set default values, eliminate any unsupported attributes, and store the results in a local array variable named IMPORTANT – Don’t use camelCase or UPPER-CASE for your NOTE on confusing regex\/callback name reference:<\/strong><\/p>\n\n\n\n The zeroeth entry of the attributes array ( This is confusing and perhaps reflects an underlying bug, but an overloaded 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 allows for common code.)<\/p>\n\n\n\n The return value of a shortcode handler function is inserted into the post content output in place of the shortcode macro. Remember to use return and not echo – anything that is echoed will be output to the browser, but it won’t appear in the correct place on the page<\/strong>.<\/p>\n\n\n\n Shortcodes are parsed after wpautop<\/a> and wptexturize<\/a> post formatting has been applied. 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 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 wrapped in an appropriate block tag such as If the shortcode produces a lot of HTML then The examples above show self-closing shortcode macros such as If a shortcode macro is used to enclose content, its handler function will receive a second parameter containing that content. Users might write shortcodes in either form, so it is necessary to allow for either case by providing a default value for the second parameter to your handler function:<\/p>\n\n\n\n When content is enclosed, the complete shortcode macro including its content will be replaced 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.<\/p>\n\n\n\n Here’s a trivial example of an enclosing shortcode:<\/p>\n\n\n\n When used like this:<\/p>\n\n\n\n The output would be:<\/p>\n\n\n\n Since Which would produce:<\/p>\n\n\n\n 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.<\/p>\n\n\n\n The shortcode parser uses a single pass on the post content. This means that if the This would produce:<\/p>\n\n\n\n If the enclosing shortcode is intended to permit other shortcodes in its output, the handler function can call do_shortcode()<\/a> recursively:<\/p>\n\n\n\n In the previous example, this would ensure the The parser does not handle mixing of enclosing and non-enclosing forms of the same shortcode as you would want it to. For example, if you have:<\/p>\n\n\n\n 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 Enclosing shortcodes support attributes in the same way as self-closing shortcodes. Here’s an example of the The following Shortcode API functions are available:<\/p>\n\n\n\n Registers a new shortcode handler function. Only one handler function may exist for a given shortcode. Calling Deregisters an existing shortcode. Deregisters all shortcodes.<\/p>\n\n\n\n Process a raw array of attributes Parse any known shortcode macros in the do_shortcode()<\/a> is registered as a default filter on ‘the_content’ with a priority of 11.<\/p>\n\n\n\n The shortcode parser correctly deals with nested shortcode macros, provided their handler functions support it by recursively calling do_shortcode()<\/a>:<\/p>\n\n\n\n However the parser will fail if a shortcode macro is used to enclose another macro of the same name:<\/p>\n\n\n\n This is a limitation of the context-free regexp parser used by In future versions of WordPress, it may be necessary for plugins having a nested shortcode syntax to ensure that the 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:<\/p>\n\n\n\n Starting with version 4.0.1, if a plugin fails to register tag-b and tag-c as valid shortcodes, the 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 between shortcode tags, at least consider using the no_texturize_shortcodes<\/a> filter to prevent texturization of the contents of tag-a:<\/p>\n\n\n\n In certain cases the shortcode parser cannot correctly deal with the use of both closed and unclosed shortcodes. For instance in this case the parser will only correctly identify the second instance of the shortcode:<\/p>\n\n\n\n However in this case the parser will identify both:<\/p>\n\n\n\n Take caution when using hyphens in the name of your shortcodes. In the following instance WordPress may see the second opening shortcode as equivalent to the first (basically WordPress sees the first part before the hyphen):<\/p>\n\n\n\n It all depends on which shortcode is defined first. If you are going to use hyphens then define the shortest shortcode first.<\/p>\n\n\n\n To avoid this, use an underscore or simply no separator:<\/p>\n\n\n\n If the first part of the shortcode is different from one another, you can get away with using hyphens:<\/p>\n\n\n\n Important:<\/strong> 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):<\/p>\n\n\n\n The shortcode parser does not accept square brackets within attributes. Thus the following will fail:<\/p>\n\n\n\n[ gallery ]<\/code><\/p>\n\n\n\n[ gallery id=\"123\" size=\"medium\" ]<\/code><\/pre>\n\n\n\n\/\/ [foobar]\nfunction wporg_foobar_func( $atts ) {\n\treturn \"foo and bar\";\n}\nadd_shortcode( 'foobar', 'wporg_foobar_func' );<\/code><\/pre>\n\n\n\n[foobar]<\/code> shortcode that returns as: foo and bar<\/p>\n\n\n\n\/\/ [bartag foo=\"foo-value\"]\nfunction bartag_func( $atts ) {\n\t$a = shortcode_atts( array(\n\t\t'foo' => 'something',\n\t\t'bar' => 'something else',\n\t), $atts );\n\n\treturn \"foo = {$a['foo']}\";\n}\nadd_shortcode( 'bartag', 'bartag_func' );<\/code><\/pre>\n\n\n\n[bartag]<\/code> shortcode that supports two attributes: “foo” and “bar”. Both attributes are optional and will take on default options [foo=\"something\" bar=\"something else\"]<\/code> if they are not provided. The shortcode will return as foo = {the value of the foo attribute}<\/code>.<\/p>\n\n\n\nHistory<\/h2>\n\n\n\n
Overview<\/h2>\n\n\n\n
add_shortcode<\/a><\/code> function is used to register a shortcode handler. It takes two parameters: the shortcode name (the string used in a post body), and the callback function name.<\/p>\n\n\n\n$atts<\/code>: an associative array of attributes, or an empty string if no attributes are given<\/li>$content<\/code>: the enclosed content (if the shortcode is used in its enclosing form)<\/li>$tag<\/code>: the shortcode tag, useful for shared callback functions<\/li><\/ul>\n\n\n\nadd_shortcode( 'wporgshortcode', 'wporg_shortcode_handler' );<\/code><\/pre>\n\n\n\n[myshortcode]<\/code>, separate and parse the attributes and content, if any, and pass them the corresponding shortcode handler function. Any string returned<\/em> (not echoed) by the shortcode handler will be inserted into the post body in place of the shortcode itself.<\/p>\n\n\n\n[wporgshortcode foo=\"bar\" bar=\"bing\"]<\/code><\/p>\n\n\n\n$atts<\/code> parameter:<\/p>\n\n\n\narray( 'foo' => 'bar', 'bar' => 'bing' )<\/code><\/pre>\n\n\n\n$atts[0]<\/code>) will hold the string that matched the shortcode regex, but ONLY IF that is different from the callback name.<\/p>\n\n\n\nHandling Attributes<\/h3>\n\n\n\n
$atts<\/code>\u00a0array 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.)<\/p>\n\n\n\nshortcode_atts()<\/a><\/code> resembles the wp_parse_args<\/a><\/code> function, but has some important differences. Its parameters are:<\/p>\n\n\n\nshortcode_atts( $defaults_array, $atts );<\/code><\/pre>\n\n\n\n$defaults_array<\/code> is an associative array that specifies the recognized attribute names and their default values. $atts<\/code> is the raw attributes array as passed into your shortcode handler. shortcode_atts()<\/code> will return a normalized array containing all of the keys from the $defaults_array<\/code>, filled in with values from the $atts<\/code> array if present. For example:<\/p>\n\n\n\n$a = shortcode_atts( array(\n\t'title' => 'My Title',\n\t'foo' => 123,\n), $atts );<\/code><\/pre>\n\n\n\n$atts<\/code> were to contain array( 'foo' => 456, 'bar' => 'something' )<\/code>, the resulting $a<\/code> would be array( 'title' => 'My Title', 'foo' => 456 )<\/code>. The value of $atts['foo']<\/code> overrides the default of 123. $atts['title']<\/code> 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.<\/p>\n\n\n\n[myshortcode FOO=\"BAR\"]<\/code> produces $atts = array( 'foo' => 'BAR' )<\/code>.<\/p>\n\n\n\nfunction wporg_shortcode_handler( $atts, $content = null ) {\n\t$a = shortcode_atts( array(\n\t\t'attr_1' => 'attribute 1 default',\n\t\t'attr_2' => 'attribute 2 default',\n\t\t\/\/ ...etc\n\t), $atts );\n}<\/code><\/pre>\n\n\n\n$a<\/code> with the attributes as keys – $a['attr_1']<\/code>, $a['attr_2']<\/code>, and so on. In other words, the array of defaults approximates a list of local variable declarations.<\/p>\n\n\n\n$atts<\/code> attribute names<\/strong>:<\/p>\n\n\n\n$atts<\/code> values are lower-cased<\/strong><\/em> during shortcode_atts( array( 'attr_1' => 'attr_1 default', \/\/ ...etc ), $atts )<\/code> processing, so you might want to just use lower-case<\/em>.<\/p>\n\n\n\n$atts[0]<\/code><\/strong>) will contain the string that matched the shortcode regex, but ONLY if that differs from the callback name, which otherwise appears as the third argument to the callback function.<\/p>\n\n\n\nadd_shortcode('foo','foo'); \/\/ two shortcodes referencing the same callback\n add_shortcode('bar','foo');\n produces this behavior:\n [foo a='b'] ==> callback to: foo(array('a'=>'b'),NULL,\"foo\");\n [bar a='c'] ==> callback to: foo(array(0 => 'bar', 'a'=>'c'),NULL,\"\");<\/code><\/pre>\n\n\n\nOutput<\/h3>\n\n\n\n
wpautop()<\/code> or wptexturize()<\/code> directly when you return the output from your shortcode handler.<\/p>\n\n\n\n<p><\/code> or <div><\/code>.<\/p>\n\n\n\nob_start<\/code> can be used to capture output and convert it to a string as follows:<\/p>\n\n\n\nfunction wporg_shortcode() {\n\tob_start();\n\t?> <HTML> <here> ... <?php\n\treturn ob_get_clean();\n}<\/code><\/pre>\n\n\n\nEnclosing vs self-closing shortcodes<\/h3>\n\n\n\n
[myshortcode]<\/code>. The API also supports enclosing shortcodes such as [myshortcode]content[\/myshortcode]<\/code>.<\/p>\n\n\n\nfunction wporg_shortcode_handler( $atts, $content = null )<\/code><\/pre>\n\n\n\nempty( $content )<\/code> can be used to distinguish between the self-closing and enclosing cases.<\/p>\n\n\n\nfunction wporg_caption_shortcode( $atts, $content = null ) {\n\treturn '<span class=\"caption\">' . $content . '<\/span>';\n}\nadd_shortcode( 'caption', 'wporg_caption_shortcode' );<\/code><\/pre>\n\n\n\nMy Caption<\/code><\/pre>\n\n\n\n<span class=\"caption\">My Caption<\/span><\/code><\/pre>\n\n\n\n$content<\/code> is included in the return value without any escaping or encoding, the user can include raw HTML:<\/p>\n\n\n\n<a href=\"http:\/\/example.com\/\">My Caption<\/a><\/code><\/pre>\n\n\n\n<span class=\"caption\"><a href=\"http:\/\/example.com\/\">My Caption<\/a><\/span><\/code><\/pre>\n\n\n\n$content<\/code> parameter of a shortcode handler contains another shortcode, it won’t be parsed:<\/p>\n\n\n\nCaption: [myshortcode]<\/code><\/pre>\n\n\n\n<span class=\"caption\">Caption: [myshortcode]<\/span><\/code><\/pre>\n\n\n\nfunction wporg_caption_shortcode( $atts, $content = null ) {\n return '<span class=\"caption\">' . do_shortcode($content) . '<\/span>';\n}<\/code><\/pre>\n\n\n\n[myshortcode]<\/code> macro in the enclosed content is parsed, and its output enclosed by the caption span:<\/p>\n\n\n\n<span class=\"caption\">Caption: The result of myshortcode's handler function<\/span><\/code><\/pre>\n\n\n\n[myshortcode example='non-enclosing' \/] non-enclosed content [myshortcode] enclosed content [\/myshortcode]<\/code><\/pre>\n\n\n\n[myshortcode]<\/code> enclosed content”.<\/p>\n\n\n\ncaption_shortcode()<\/code> improved to support a ‘class’ attribute:<\/p>\n\n\n\nfunction wporg_caption_shortcode( $atts, $content = null ) {\n\t$a = shortcode_atts( array(\n\t\t'class' => 'caption',\n\t), $atts );\n\n\treturn '<span class=\"' . esc_attr($a['class']) . '\">' . $content . '<\/span>';\n}<\/code><\/pre>\n\n\n\nMy Caption<\/code><\/pre>\n\n\n\n<span class=\"headline\">My Caption<\/span><\/code><\/pre>\n\n\n\nOther features in brief<\/h3>\n\n\n\n
[myshortcode \/]<\/code>, but this is optional.<\/li>[myshortcode foo='123' bar=456]<\/code> is equivalent to [myshortcode foo=\"123\" bar=\"456\"]<\/code>. 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.<\/li>$atts<\/code> array. For example, [myshortcode 123]<\/code> will produce $atts = array( 0 => 123 )<\/code>. Positional attributes may be mixed with named ones, and quotes may be used if the values contain spaces or other significant characters.<\/li>Function reference<\/h3>\n\n\n\n
function add_shortcode( $tag, $func )<\/code><\/pre>\n\n\n\n$tag<\/code> is the shortcode string as written by the user (without braces), such as “myshortcode”. $func is the handler function name.<\/p>\n\n\n\nadd_shortcode()<\/code> again with the same $tag name will overwrite the previous handler.<\/p>\n\n\n\nfunction remove_shortcode( $tag )<\/code><\/pre>\n\n\n\n$tag<\/code> is the shortcode name as used in add_shortcode()<\/code>.<\/p>\n\n\n\nfunction remove_all_shortcodes()<\/code><\/pre>\n\n\n\nfunction shortcode_atts( $pairs, $atts )<\/code><\/pre>\n\n\n\n$atts<\/code> against the set of defaults specified in $pairs<\/code>. Returns an array. The result will contain every key from $pairs<\/code>, merged with values from $atts<\/code>. Any keys in $atts<\/code> that do not exist in $pairs are ignored.<\/p>\n\n\n\nfunction do_shortcode( $content )<\/code><\/pre>\n\n\n\n$content<\/code> string. Returns a string containing the original content with shortcode macros replaced by their handler functions output.<\/p>\n\n\n\nLimitations<\/h3>\n\n\n\n
Nested Shortcodes<\/h4>\n\n\n\n
[tag-a]\n [tag-b]\n [tag-c]\n [\/tag-b]\n[\/tag-a]<\/code><\/pre>\n\n\n\n[tag-a]\n [tag-a]\n [\/tag-a]\n[\/tag-a]<\/code><\/pre>\n\n\n\ndo_shortcode()<\/code> – it is very fast but does not count levels of nesting, so it can’t match each opening tag with its correct closing tag in these cases.<\/p>\n\n\n\nwptexturize()<\/code> processor does not interfere with the inner codes. It is recommended that for such complex syntax, the no_texturize_shortcodes<\/a> 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()<\/code> before calling do_shortcode()<\/code> as described above.<\/p>\n\n\n\nUnregistered Names<\/h4>\n\n\n\n
[tag-a unit=\"north\"]\n [tag-b size=\"24\"]\n [tag-c color=\"red\"]\n [\/tag-b]\n[\/tag-a]<\/code><\/pre>\n\n\n\nwptexturize()<\/code> processor will output the following text prior to any shortcode being parsed:<\/p>\n\n\n\n[tag-a unit=\"north\"]\n [tag-b size=\u201d24\u201d]\n [tag-c color=\u201dred\u201d]\n [\/tag-b]\n[\/tag-a]<\/code><\/pre>\n\n\n\nadd_shortcode( 'tag-a', 'wporg_tag_a_handler' );\nadd_filter( 'no_texturize_shortcodes', 'wporg_ignore_tag_a' );\n\nfunction wporg_ignore_tag_a( $list ) {\n $list[] = 'tag-a';\n return $list;\n}<\/code><\/pre>\n\n\n\nUnclosed Shortcodes<\/h4>\n\n\n\n
[tag]\n[tag]\n CONTENT\n[\/tag]<\/code><\/pre>\n\n\n\n[tag]\n CONTENT\n[\/tag]\n[tag]<\/code><\/pre>\n\n\n\nHyphens<\/h4>\n\n\n\n
[tag]\n[tag-a]<\/code><\/pre>\n\n\n\n[tag]\n[tag_a]\n\n[tag]\n[taga]<\/code><\/pre>\n\n\n\n[tag]\n[tagfoo-a]<\/code><\/pre>\n\n\n\n\/\/ plugin-A\n[is-logged-in]\n\n\/\/ plugin-B\n[is-admin]<\/code><\/pre>\n\n\n\nSquare Brackets<\/h4>\n\n\n\n
[tag attribute=\"[Some value]\"]<\/code><\/pre>\n\n\n\n