Shortcodes with Parameters

Now that we know how to create a basic shortcode and how to use it as self-closing and enclosing, we will look at using parameters in shortcode [$tag] and handler function.

Shortcode [$tag] can accept parameters, known as attributes:

[wporg title="WordPress.org"]
Having fun with WordPress.org shortcodes.
[/wporg]

Shortcode handler function can accept 3 parameters:

  • $atts – array – [$tag] attributes
  • $content – string – post content
  • $tag – string – the name of the [$tag] (i.e. the name of the shortcode)
function wporg_shortcode( $atts = array(), $content = null, $tag = '' ) {}

Parsing Attributes Parsing Attributes

For the user, shortcodes are just strings with square brackets inside the post content. The user have no idea which attributes are available and what happens behind the scenes.

For plugin developers, there is no way to enforce a policy on the use of attributes. The user may include one attribute, two or none at all.

To gain control of how the shortcodes are used:

Top ↑

Complete Example Complete Example

Complete example using a basic shortcode structure, taking care of self-closing and enclosing scenarios, shortcodes within shortcodes and securing output.

A [wporg] shortcode that will accept a title and will display a box that we can style with CSS.

/**
 * The [wporg] shortcode.  Accepts a title and will display a box.
 *
 * @param array  $atts     Shortcode attributes. Default empty.
 * @param atring $content  Shortcode content. Default null.
 * @param string $tag      Shortcode tag (name). Default empty.
 *
 * @return string
 */
function wporg_shortcode( $atts = [], $content = null, $tag = '' ) {
	// normalize attribute keys, lowercase
	$atts = array_change_key_case( (array) $atts, CASE_LOWER );

	// override default attributes with user attributes
	$wporg_atts = shortcode_atts(
		array(
			'title' => 'WordPress.org',
		), $atts, $tag
	);

	// start box
	$o = '<div class="wporg-box">';

	// title
	$o .= '<h2>' . esc_html__( $wporg_atts['title'], 'wporg' ) . '</h2>';

	// enclosing tags
	if ( ! is_null( $content ) ) {
		// secure output by executing the_content filter hook on $content
		$o .= apply_filters( 'the_content', $content );

		// run shortcode parser recursively
		$o .= do_shortcode( $content );
	}

	// end box
	$o .= '</div>';

	// return output
	return $o;
}

/**
 * Central location to create all shortcodes.
 */
function wporg_shortcodes_init() {
	add_shortcode( 'wporg', 'wporg_shortcode' );
}

add_action( 'init', 'wporg_shortcodes_init' );