shortcode_atts( array $pairs, array $atts, string $shortcode = '' ): array
Combines user attributes with known attributes and fill in defaults when needed.
Contents
Description
The pairs should be considered to be all of the attributes which are supported by the caller and given as a list. The returned attributes will only contain the attributes in the $pairs list.
If the $atts list has unsupported attributes, then they will be ignored and removed from the final returned list.
Parameters
-
$pairs
array Required -
Entire list of supported attributes and their defaults.
-
$atts
array Required -
User defined attributes in shortcode tag.
-
$shortcode
string Optional -
The name of the shortcode, provided for context to enable filtering
Default:
''
Return
array Combined and filtered attribute list.
Source
File: wp-includes/shortcodes.php
.
View all references
function shortcode_atts( $pairs, $atts, $shortcode = '' ) {
$atts = (array) $atts;
$out = array();
foreach ( $pairs as $name => $default ) {
if ( array_key_exists( $name, $atts ) ) {
$out[ $name ] = $atts[ $name ];
} else {
$out[ $name ] = $default;
}
}
if ( $shortcode ) {
/**
* Filters shortcode attributes.
*
* If the third parameter of the shortcode_atts() function is present then this filter is available.
* The third parameter, $shortcode, is the name of the shortcode.
*
* @since 3.6.0
* @since 4.4.0 Added the `$shortcode` parameter.
*
* @param array $out The output array of shortcode attributes.
* @param array $pairs The supported attributes and their defaults.
* @param array $atts The user defined shortcode attributes.
* @param string $shortcode The shortcode name.
*/
$out = apply_filters( "shortcode_atts_{$shortcode}", $out, $pairs, $atts, $shortcode );
}
return $out;
}
Hooks
-
apply_filters( "shortcode_atts_{$shortcode}",
array $out ,array $pairs ,array $atts ,string $shortcode ) -
Filters shortcode attributes.
Changelog
Version | Description |
---|---|
2.5.0 | Introduced. |
User Contributed Notes
You must log in before being able to contribute a note or feedback.
It might be really useful to note that attribute names must be all lowercase…
If your shortcode looks like this:
[shortcode attOne="foo" attTwo="bar"]
The array passed to the callback function will look like this:
Array( attone => "foo", atttwo => "bar" )
So, I guess you could use camelCase in the shortcode, just remember to expect those camelCase to be all lowercase in your
shortcode_atts
…Top ↑
Feedback
This is not true, but can seem true: see explanation. — By crstauf —
To clear up any confusion: Aaron’s post is correct, while the the explanation by crstauf is technically correct. It is true that
shortcode_atts()
makes a case-sensitive comparison between the first argument (array of supported attributes and their defaults) and the second argument (array of user-defined attributes in shortcode tag). But the user-defined attributes are normalized to lowercase by WordPress before being passed to the shortcode callback function (seeshortcode_parse_atts()
). So the case-sensitivity ofshortcode_atts()
only becomes an issue if you define supported attributes using uppercase characters. — By Bart Kuijper —Example
[bartag foo=”koala” bar=”bears”] outputs the following:
bartag: koala bears
[bartag foo=”koala”] outputs the following:
bartag: koala default bar
This creates a “
[bartag]
” shortcode that supports two attributes:[bartag foo="something" bar="something else"]
. Both attributes are optional and will take on default options if they are not provided.Clarification on Aaron’s note:
The case of the keys on the
$pairs
must match the keys on the$atts
, or the value will be discarded.See these examples:
To ensure this function works and allow for case insensitive attributes, I use
array_change_key_case
in a one-liner like thisI had to hunt around to find all the pieces, I hope others find this helpful.
So, building on a previous example:
Top ↑
Feedback
The example function `my_callback_func` gets the attributes into an array, but uses the individual attribute names as variables. No `extract` was done. Also, the filter `add_zoo` only sets it to ”, not the value the user entered. — By Joy —