Attributes:
← Older revision
Revision as of 19:12, 7 May 2014
(3 intermediate revisions not shown)
Line 38:
Line 38:
// [bartag foo="foo-value"]
// [bartag foo="foo-value"]
function bartag_func( $atts ) {
function bartag_func( $atts ) {
−
extract( shortcode_atts( array(
+
$a = shortcode_atts( array(
−
'foo' => 'something',
+
'foo' => 'something',
−
'bar' => 'something else',
+
'bar' => 'something else',
−
), $atts ) );
+
), $atts );
−
return "foo = {$foo}";
+
return "foo = {$a['foo']}";
}
}
add_shortcode( 'bartag', 'bartag_func' );
add_shortcode( 'bartag', 'bartag_func' );
</pre>
</pre>
−
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 return as foo = {the value of the foo attribute}
+
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 return as foo = {the value of the foo attribute}.
=== Overview ===
=== Overview ===
Line 56:
Line 56:
Shortcode names should be all lowercase and use all letters, but numbers and underscores should work fine too. Be wary of [[Shortcode_API#Hyphens|using hyphens]] (dashes), you'll be better off not using them.
Shortcode names should be all lowercase and use all letters, but numbers and underscores should work fine too. Be wary of [[Shortcode_API#Hyphens|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 body), and the callback function name.
+
The <code>[[Function Reference/add_shortcode|add_shortcode]]</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.
Three parameters are passed to the shortcode callback function. You can choose to use any number of them including none of them.
Three parameters are passed to the shortcode callback function. You can choose to use any number of them including none of them.
Line 74:
Line 74:
[myshortcode foo="bar" bar="bing"]
[myshortcode foo="bar" bar="bing"]
−
These attributes will be converted into an associative array like the following, passed to the handler function as its $atts parameter:
+
These attributes will be converted into an associative array like the following, passed to the handler function as its <code>$atts</code> parameter:
array( 'foo' => 'bar', 'bar' => 'bing' )
array( 'foo' => 'bar', 'bar' => 'bing' )
Line 86:
Line 86:
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.
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 important differences. Its parameters are:
+
<code>[[Function Reference/shortcode_atts|shortcode_atts()]]</code> resembles the <code>[[Function Reference/wp_parse_args|wp_parse_args]]</code> function, but has some important differences. Its parameters are:
shortcode_atts( $defaults_array, $atts );
shortcode_atts( $defaults_array, $atts );
−
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 return a normalized array containing all of the keys from the $defaults_array, filled in with values from the $atts array if present. For example:
+
Both parameters are required. <code>$defaults_array</code> is an associative array that specifies the recognized attribute names and their default values. <code>$atts</code> is the raw attributes array as passed into your shortcode handler. <code>shortcode_atts()</code> will return a normalized array containing all of the keys from the <code>$defaults_array</code>, filled in with values from the <code>$atts</code> array if present. For example:
<pre>
<pre>
$a = shortcode_atts( array(
$a = shortcode_atts( array(
−
'title' => 'My Title',
+
'title' => 'My Title',
−
'foo' => 123,
+
'foo' => 123,
), $atts );
), $atts );
</pre>
</pre>
−
If $atts were to contain array( 'foo' => 456, 'bar' => 'something' ), the resulting $a would be array( 'title' => 'My Title', 'foo' => 456 ). The value of $atts['foo'] overrides the default of 123. $atts['title'] is not set, so the default 'My Title' is used. And there is no 'bar' item in the defaults array, so it is not included in the result.
+
If <code>$atts</code> were to contain <samp>array( 'foo' => 456, 'bar' => 'something' )</samp>, the resulting <code>$a</code> would be <samp>array( 'title' => 'My Title', 'foo' => 456 )</samp>. The value of <code>$atts['foo']</code> overrides the default of 123. <code>$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.
−
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' ).
+
Attribute names are always converted to lowercase before they are passed into the handler function. Values are untouched. <code>[myshortcode FOO="BAR"]</code> produces <code>$atts = array( 'foo' => 'BAR' )</code>.
A suggested code idiom for declaring defaults and parsing attributes in a shortcode handler is as follows:
A suggested code idiom for declaring defaults and parsing attributes in a shortcode handler is as follows:
Line 107:
Line 107:
<pre>
<pre>
function my_shortcode_handler( $atts, $content = null ) {
function my_shortcode_handler( $atts, $content = null ) {
−
extract( shortcode_atts( array(
+
$a = shortcode_atts( array(
−
'attr_1' => 'attribute 1 default',
+
'attr_1' => 'attribute 1 default',
−
'attr_2' => 'attribute 2 default',
+
'attr_2' => 'attribute 2 default',
−
// ...etc
+
// ...etc
−
), $atts ) );
+
), $atts );
}
}
</pre>
</pre>
−
This will parse the attributes, set default values, eliminate any unsupported attributes, and (using [http://www.php.net/extract extract()]) store the results in local variables named for the attribute keys - $attr_1, $attr_2 and so on. In other words, the array of defaults approximates a list of local variable declarations. (extract() is safe to use in this context without special flags to handle collisions because shortcode_atts() will strip out any keys not included in the defaults array).
+
This will parse the attributes, set default values, eliminate any unsupported attributes, and store the results in a local array variable named <code>$a</code> with the attributes as keys - <code>$a['attr_1']</code>, <code>$a['attr_2']</code>, and so on. In other words, the array of defaults approximates a list of local variable declarations.
----
----
Line 219:
Line 219:
<pre>
<pre>
function caption_shortcode( $atts, $content = null ) {
function caption_shortcode( $atts, $content = null ) {
−
extract( shortcode_atts( array(
+
$a = shortcode_atts( array(
'class' => 'caption',
'class' => 'caption',
−
), $atts ) );
+
), $atts );
−
return '<span class="' . esc_attr($class) . '">' . $content . '</span>';
+
return '<span class="' . esc_attr($a['class']) . '">' . $content . '</span>';
}
}
</pre>
</pre>