add_shortcode( string $tag, callable $callback )
Adds a new shortcode.
Contents
Description
Care should be taken through prefixing or other means to ensure that the shortcode tag being added is unique and will not conflict with other, already-added shortcode tags. In the event of a duplicated tag, the tag loaded last will take precedence.
Parameters
-
$tag
string Required -
Shortcode tag to be searched in post content.
-
$callback
callable Required -
The callback function to run when the shortcode is found.
Every shortcode callback is passed three parameters by default, including an array of attributes ($atts
), the shortcode content or null if not set ($content
), and finally the shortcode tag itself ($shortcode_tag
), in that order.
More Information
The shortcode callback will be passed three arguments: the shortcode attributes, the shortcode content (if any), and the name of the shortcode.
There can only be one hook for each shortcode. This means that if another plugin has a similar shortcode, it will override yours, or yours will override theirs depending on which order the plugins are included and/or ran.
Shortcode attribute names are always converted to lowercase before they are passed into the handler function. Values are untouched.
Note that the function called by the shortcode should never produce an output of any kind. Shortcode functions should return the text that is to be used to replace the shortcode. Producing the output directly will lead to unexpected results. This is similar to the way filter functions should behave, in that they should not produce unexpected side effects from the call since you cannot control when and where they are called from.
Source
File: wp-includes/shortcodes.php
.
View all references
function add_shortcode( $tag, $callback ) {
global $shortcode_tags;
if ( '' === trim( $tag ) ) {
_doing_it_wrong(
__FUNCTION__,
__( 'Invalid shortcode name: Empty name given.' ),
'4.4.0'
);
return;
}
if ( 0 !== preg_match( '@[<>&/\[\]\x00-\x20=]@', $tag ) ) {
_doing_it_wrong(
__FUNCTION__,
sprintf(
/* translators: 1: Shortcode name, 2: Space-separated list of reserved characters. */
__( 'Invalid shortcode name: %1$s. Do not use spaces or reserved characters: %2$s' ),
$tag,
'& / < > [ ] ='
),
'4.4.0'
);
return;
}
$shortcode_tags[ $tag ] = $callback;
}
Changelog
Version | Description |
---|---|
2.5.0 | Introduced. |
User Contributed Notes
You must log in before being able to contribute a note or feedback.
Examples
Simplest example of a shortcode tag using the API:
[footag foo="bar"]
Example with nice attribute defaults:
[bartag foo="bar"]
Example with enclosed content:
[baztag]content[/baztag]
If your plugin is designed as a class write as follows:
When adding `add_shortcode()` function in a plugin, it’s good to add it in a function that is hooked to `init` hook. So that WordPress has time to initialize properly.
As described in the plugins handbook.
Top ↑
Feedback
There is currently (2020-12-23) no such recommendation in the plugins handbook nor in the codex. — By Bart Kuijper —
For wppb plugin boilerplate I add code to define_public_hooks()
$this->loader->add_action( 'init', $plugin_public, 'register_shortcodes' );
Then in public folder, in class_public file I added:
Example of
add_shortcode
function that usesget_template_part
function to include a template.Notes (from the Codex — https://codex.wordpress.org/Function_Reference/add_shortcode#Notes)
Beware that the first argument passed to the callback is an empty string if no attributes are set in the shortcode. So a type declaration will fail:
“Fatal error: Uncaught Error: Argument 1 passed to shortcode_callback() must be of the type array, string given”
Use a check whether
$arguments
is not an array and if so, replace it with an empty array:$atts: an associative array of attributes, you can access the associative array anywhere.
$content: the enclosed content (if the shortcode is used in its enclosing form)
When passing values via the shortcode e.g.
[myshortcode FooBar="one" SomethingElse="two"]
the keys in the array are transformed to lowercaseThe array passed to the callback function will be:
Array( foobar => "one", somethingelse=> "two" )
Don’t be like me and spend hours trying to figure out why the values weren’t being passed.