img_caption_shortcode( array $attr, string $content = null )
Builds the Caption shortcode output.
Description Description
Allows a plugin to replace the content that would otherwise be returned. The filter is ‘img_caption_shortcode’ and passes an empty string, the attr parameter and the content parameter values.
The supported attributes for the shortcode are ‘id’, ‘caption_id’, ‘align’, ‘width’, ‘caption’, and ‘class’.
Parameters Parameters
- $attr
-
(array) (Required) Attributes of the caption shortcode.
- 'id'
(string) ID of the image and caption container element, i.e.<figure>
or<div>
. - 'caption_id'
(string) ID of the caption element, i.e.<figcaption>
or<p>
. - 'align'
(string) Class name that aligns the caption. Default 'alignnone'. Accepts 'alignleft', 'aligncenter', alignright', 'alignnone'. - 'width'
(int) The width of the caption, in pixels. - 'caption'
(string) The caption text. - 'class'
(string) Additional class name(s) added to the caption container.
- 'id'
- $content
-
(string) (Optional) Shortcode content.
Default value: null
Return Return
(string) HTML content to display the caption.
Source Source
File: wp-includes/media.php
function img_caption_shortcode( $attr, $content = null ) { // New-style shortcode with the caption inside the shortcode with the link and image tags. if ( ! isset( $attr['caption'] ) ) { if ( preg_match( '#((?:<a [^>]+>\s*)?<img [^>]+>(?:\s*</a>)?)(.*)#is', $content, $matches ) ) { $content = $matches[1]; $attr['caption'] = trim( $matches[2] ); } } elseif ( strpos( $attr['caption'], '<' ) !== false ) { $attr['caption'] = wp_kses( $attr['caption'], 'post' ); } /** * Filters the default caption shortcode output. * * If the filtered output isn't empty, it will be used instead of generating * the default caption template. * * @since 2.6.0 * * @see img_caption_shortcode() * * @param string $output The caption output. Default empty. * @param array $attr Attributes of the caption shortcode. * @param string $content The image element, possibly wrapped in a hyperlink. */ $output = apply_filters( 'img_caption_shortcode', '', $attr, $content ); if ( ! empty( $output ) ) { return $output; } $atts = shortcode_atts( array( 'id' => '', 'caption_id' => '', 'align' => 'alignnone', 'width' => '', 'caption' => '', 'class' => '', ), $attr, 'caption' ); $atts['width'] = (int) $atts['width']; if ( $atts['width'] < 1 || empty( $atts['caption'] ) ) { return $content; } $id = ''; $caption_id = ''; $describedby = ''; if ( $atts['id'] ) { $atts['id'] = sanitize_html_class( $atts['id'] ); $id = 'id="' . esc_attr( $atts['id'] ) . '" '; } if ( $atts['caption_id'] ) { $atts['caption_id'] = sanitize_html_class( $atts['caption_id'] ); } elseif ( $atts['id'] ) { $atts['caption_id'] = 'caption-' . str_replace( '_', '-', $atts['id'] ); } if ( $atts['caption_id'] ) { $caption_id = 'id="' . esc_attr( $atts['caption_id'] ) . '" '; $describedby = 'aria-describedby="' . esc_attr( $atts['caption_id'] ) . '" '; } $class = trim( 'wp-caption ' . $atts['align'] . ' ' . $atts['class'] ); $html5 = current_theme_supports( 'html5', 'caption' ); // HTML5 captions never added the extra 10px to the image width $width = $html5 ? $atts['width'] : ( 10 + $atts['width'] ); /** * Filters the width of an image's caption. * * By default, the caption is 10 pixels greater than the width of the image, * to prevent post content from running up against a floated image. * * @since 3.7.0 * * @see img_caption_shortcode() * * @param int $width Width of the caption in pixels. To remove this inline style, * return zero. * @param array $atts Attributes of the caption shortcode. * @param string $content The image element, possibly wrapped in a hyperlink. */ $caption_width = apply_filters( 'img_caption_shortcode_width', $width, $atts, $content ); $style = ''; if ( $caption_width ) { $style = 'style="width: ' . (int) $caption_width . 'px" '; } if ( $html5 ) { $html = sprintf( '<figure %s%s%sclass="%s">%s%s</figure>', $id, $describedby, $style, esc_attr( $class ), do_shortcode( $content ), sprintf( '<figcaption %sclass="wp-caption-text">%s</figcaption>', $caption_id, $atts['caption'] ) ); } else { $html = sprintf( '<div %s%sclass="%s">%s%s</div>', $id, $style, esc_attr( $class ), str_replace( '<img ', '<img ' . $describedby, do_shortcode( $content ) ), sprintf( '<p %sclass="wp-caption-text">%s</p>', $caption_id, $atts['caption'] ) ); } return $html; }
Expand full source code Collapse full source code View on Trac
Changelog Changelog
Version | Description |
---|---|
5.1.0 | The caption_id attribute was added. |
3.9.0 | The class attribute was added. |
2.6.0 | Introduced. |