img_caption_shortcode

Builds the Caption shortcode output.

Description

(string) img_caption_shortcode( (array) $attr, (null) $content = null ); 

Allows a plugin to replace the content that would otherwise be returned. The filter is and passes an empty string, the attr parameter and the content parameter values.

The supported attributes for the shortcode are id,, align, width, and 'caption'.

Returns (string)

HTML content to display the caption.

Parameters (2)

0. $attr (array)
Attributes of the caption shortcode.

Options

  • id (string) => ''

    ID of the div element for the caption.

  • align (string) => ''

    Class name that aligns the caption. Default alignnone.. Accepts alignleft,, aligncenter, alignright', alignnone..

  • width (int) => 0

    The width of the caption, in pixels.

  • caption (string) => ''

    The caption text.

array(

    /**
     * ID of the div element for the caption.
     *
     * @type string
     * @default ''
     */
    'id' => '',

    /**
     * Class name that aligns the caption. Default 'alignnone'. Accepts 'alignleft',
     * 'aligncenter', alignright', 'alignnone'.
     *
     * @type string
     * @default ''
     */
    'align' => '',

    /**
     * The width of the caption, in pixels.
     *
     * @type int
     */
    'width' => 0,

    /**
     * The caption text.
     *
     * @type string
     * @default ''
     */
    'caption' => ''
);        

1. $content — Optional. (null) => null
Shortcode content.

Usage

  1. if ( !function_exists( 'img_caption_shortcode' ) ) { 
  2. require_once ABSPATH . WPINC . '/media.php'; 
  3.  
  4. // Attributes of the caption shortcode. 
  5. $attr = array( 
  6. 'id' => '', 
  7. 'align' => '', 
  8. 'width' => 0, 
  9. 'caption' => '' 
  10. ); 
  11.  
  12. // Shortcode content. 
  13. $content = null; 
  14.  
  15. // NOTICE! Understand what this does before running. 
  16. $result = img_caption_shortcode($attr, $content); 
  17.  

Defined (1)

The function is defined in the following location(s).

/wp-includes/media.php  
  1. function img_caption_shortcode( $attr, $content = null ) { 
  2. // New-style shortcode with the caption inside the shortcode with the link and image tags. 
  3. if ( ! isset( $attr['caption'] ) ) { 
  4. if ( preg_match( '#((?:<a [^>]+>\s*)?<img [^>]+>(?:\s*</a>)?)(.*)#is', $content, $matches ) ) { 
  5. $content = $matches[1]; 
  6. $attr['caption'] = trim( $matches[2] ); 
  7. } elseif ( strpos( $attr['caption'], '<' ) !== false ) { 
  8. $attr['caption'] = wp_kses( $attr['caption'], 'post' ); 
  9.  
  10. /** 
  11. * Filters the default caption shortcode output. 
  12. * If the filtered output isn't empty, it will be used instead of generating 
  13. * the default caption template. 
  14. * @since 2.6.0 
  15. * @see img_caption_shortcode() 
  16. * @param string $output The caption output. Default empty. 
  17. * @param array $attr Attributes of the caption shortcode. 
  18. * @param string $content The image element, possibly wrapped in a hyperlink. 
  19. */ 
  20. $output = apply_filters( 'img_caption_shortcode', '', $attr, $content ); 
  21. if ( $output != '' ) 
  22. return $output; 
  23.  
  24. $atts = shortcode_atts( array( 
  25. 'id' => '',  
  26. 'align' => 'alignnone',  
  27. 'width' => '',  
  28. 'caption' => '',  
  29. 'class' => '',  
  30. ), $attr, 'caption' ); 
  31.  
  32. $atts['width'] = (int) $atts['width']; 
  33. if ( $atts['width'] < 1 || empty( $atts['caption'] ) ) 
  34. return $content; 
  35.  
  36. if ( ! empty( $atts['id'] ) ) 
  37. $atts['id'] = 'id="' . esc_attr( sanitize_html_class( $atts['id'] ) ) . '" '; 
  38.  
  39. $class = trim( 'wp-caption ' . $atts['align'] . ' ' . $atts['class'] ); 
  40.  
  41. $html5 = current_theme_supports( 'html5', 'caption' ); 
  42. // HTML5 captions never added the extra 10px to the image width 
  43. $width = $html5 ? $atts['width'] : ( 10 + $atts['width'] ); 
  44.  
  45. /** 
  46. * Filters the width of an image's caption. 
  47. * By default, the caption is 10 pixels greater than the width of the image,  
  48. * to prevent post content from running up against a floated image. 
  49. * @since 3.7.0 
  50. * @see img_caption_shortcode() 
  51. * @param int $width Width of the caption in pixels. To remove this inline style,  
  52. * return zero. 
  53. * @param array $atts Attributes of the caption shortcode. 
  54. * @param string $content The image element, possibly wrapped in a hyperlink. 
  55. */ 
  56. $caption_width = apply_filters( 'img_caption_shortcode_width', $width, $atts, $content ); 
  57.  
  58. $style = ''; 
  59. if ( $caption_width ) { 
  60. $style = 'style="width: ' . (int) $caption_width . 'px" '; 
  61.  
  62. if ( $html5 ) { 
  63. $html = '<figure ' . $atts['id'] . $style . 'class="' . esc_attr( $class ) . '">' 
  64. . do_shortcode( $content ) . '<figcaption class="wp-caption-text">' . $atts['caption'] . '</figcaption></figure>'; 
  65. } else { 
  66. $html = '<div ' . $atts['id'] . $style . 'class="' . esc_attr( $class ) . '">' 
  67. . do_shortcode( $content ) . '<p class="wp-caption-text">' . $atts['caption'] . '</p></div>'; 
  68.  
  69. return $html;