shortcode_atts( array $pairs, array $atts, string $shortcode = '' )

Combine user attributes with known attributes and fill in defaults when needed.

Contents

Description 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 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 value: ''

Top ↑

Return Return

(array) Combined and filtered attribute list.

Top ↑

Source Source

File: wp-includes/shortcodes.php 

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;
		}
	}
	/**
	 * Filters a shortcode's default 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.
	 */
	if ( $shortcode ) {
		$out = apply_filters( "shortcode_atts_{$shortcode}", $out, $pairs, $atts, $shortcode );
	}

	return $out;
}

Expand full source code Collapse full source code View on Trac

Top ↑

Changelog Changelog

Changelog
Version Description
2.5.0 Introduced.

Top ↑

Top ↑

User Contributed Notes User Contributed Notes

  1. Skip to note 1 content
    You must log in to vote on the helpfulness of this noteVote results for this note: 2You must log in to vote on the helpfulness of this note
    Contributed by Codex —

    Example

    /**
 * Callback to register a bartag shortcode.
 *
 * @param array $atts Shortcode attributes.
 * @return string Shortcode output.
function wpdocs_bartag_func( $atts ) {
	$atts = shortcode_atts(
		array(
			'foo' => 'no foo',
			'bar' => 'default bar',
		), $atts, 'bartag' );

	return 'bartag: ' . esc_html( $atts['foo'] ) . ' ' . esc_html( $atts['bar'] );
}
add_shortcode( 'bartag', 'wpdocs_bartag_func' );

    Expand full source codeCollapse full source code

    [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.

  2. Skip to note 2 content
    You must log in to vote on the helpfulness of this noteVote results for this note: 0You must log in to vote on the helpfulness of this note
    Contributed by zitomerh —

    I had to hunt around to find all the pieces, I hope others find this helpful.

    So, building on a previous example:

    /**
 * How to use shortcode callback parms with shortcode_atts to make
 * callback code flexible and re-useable.
 *
 * This allows filters to be applied to a callback depending on which
 * shortcode called it.
 *
 * @param array  $atts    Shortcode attributes.
 * @param string $content Shortcode content.
 * @param string $tag     The shortcode which invoked the callback
 * @return string Shortcode output.
 */
function my_callback_func( $atts, $content, $tag ) {
    $atts = shortcode_atts(
        array(
            'foo' => '',
            'bar' => '',
        ), $atts, $tag );

 //do something here(trivial example)
	if ( !empty($zoo) ) {
		return $zoo;  //where did $zoo come from? see below
	}
	else return $foo;
    
}

add_shortcode( 'myshortcode1', 'my_callback_func' );
add_shortcode( 'myshortcode2', 'my_callback_func' );

/* now make a filter that's applied ONLY when my_callback_func is invoked by myshortcode1 -
this example adds param 'zoo' to myshortcode1  */

add_filter ('shortcode_atts_myshortcode1', 'add_zoo', 10, 3);
function add_zoo ($out, $pairs, $atts ) {
	$out['zoo'] = '';
	return $out;
}
// Now we can use [myshortcode1 foo='myfoo' zoo='myzoo']  output: myzoo
// and [myshortcode2 foo='myfoo' zoo='myzoo']  output: myfoo

    Expand full source codeCollapse full source code

You must log in before being able to contribute a note or feedback.