gallery_shortcode

Builds the Gallery shortcode output.

Description

(string) gallery_shortcode( (array) $attr ); 

This implements the functionality of the Gallery Shortcode for displaying WordPress images on a post.

Returns (string)

HTML content to display gallery.

Parameters (1)

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

Options

  • order (string) => ''

    Order of the images in the gallery. Default ASC.. Accepts ASC., DESC,.

  • orderby (string) => ''

    The field to use when ordering the images. Default menu_order ID.. Accepts any valid SQL ORDERBY statement.

  • id (int) => 0

    Post ID.

  • itemtag (string) => 'dl'

    HTML tag to use for each image in the gallery.

  • icontag (string) => 'dt'

    HTML tag to use for each image's icon.

  • captiontag (string) => 'dd'

    HTML tag to use for each image's caption.

  • columns (int) => 3

    Number of columns of images to display.

  • size (string|array) => 'thumbnail'

    Size of the images to display. Accepts any valid image size, or an array of width and height values in pixels (in that order).

  • ids (string) => ''

    A comma-separated list of IDs of attachments to display.

  • include (string) => ''

    A comma-separated list of IDs of attachments to include.

  • exclude (string) => ''

    A comma-separated list of IDs of attachments to exclude.

array(

    /**
     * Order of the images in the gallery. Default 'ASC'. Accepts 'ASC', 'DESC'.
     *
     * @type string
     * @default ''
     */
    'order' => '',

    /**
     * The field to use when ordering the images. Default 'menu_order ID'. Accepts any valid SQL
     * ORDERBY statement.
     *
     * @type string
     * @default ''
     */
    'orderby' => '',

    /**
     * Post ID.
     *
     * @type int
     */
    'id' => 0,

    /**
     * HTML tag to use for each image in the gallery.
     *
     * @type string
     * @default 'dl'
     */
    'itemtag' => 'dl',

    /**
     * HTML tag to use for each image's icon.
     *
     * @type string
     * @default 'dt'
     */
    'icontag' => 'dt',

    /**
     * HTML tag to use for each image's caption.
     *
     * @type string
     * @default 'dd'
     */
    'captiontag' => 'dd',

    /**
     * Number of columns of images to display.
     *
     * @type int
     * @default 3
     */
    'columns' => 3,

    /**
     * Size of the images to display. Accepts any valid image size, or an array of width and height
     * values in pixels (in that order).
     *
     * @type string|array
     * @default 'thumbnail'
     */
    'size' => 'thumbnail',

    /**
     * A comma-separated list of IDs of attachments to display.
     *
     * @type string
     * @default ''
     */
    'ids' => '',

    /**
     * A comma-separated list of IDs of attachments to include.
     *
     * @type string
     * @default ''
     */
    'include' => '',

    /**
     * A comma-separated list of IDs of attachments to exclude.
     *
     * @type string
     * @default ''
     */
    'exclude' => ''
);        


Usage

  1. if ( !function_exists( 'gallery_shortcode' ) ) { 
  2. require_once ABSPATH . WPINC . '/media.php'; 
  3.  
  4. // Attributes of the gallery shortcode. 
  5. $attr = array( 
  6. 'order' => '', 
  7. 'orderby' => '', 
  8. 'id' => 0, 
  9. 'itemtag' => 'dl', 
  10. 'icontag' => 'dt', 
  11. 'captiontag' => 'dd', 
  12. 'columns' => 3, 
  13. 'size' => 'thumbnail', 
  14. 'ids' => '', 
  15. 'include' => '', 
  16. 'exclude' => '' 
  17. ); 
  18.  
  19. // NOTICE! Understand what this does before running. 
  20. $result = gallery_shortcode($attr); 
  21.  

Defined (1)

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

/wp-includes/media.php  
  1. function gallery_shortcode( $attr ) { 
  2. $post = get_post(); 
  3.  
  4. static $instance = 0; 
  5. $instance++; 
  6.  
  7. if ( ! empty( $attr['ids'] ) ) { 
  8. // 'ids' is explicitly ordered, unless you specify otherwise. 
  9. if ( empty( $attr['orderby'] ) ) { 
  10. $attr['orderby'] = 'post__in'; 
  11. $attr['include'] = $attr['ids']; 
  12.  
  13. /** 
  14. * Filters the default gallery shortcode output. 
  15. * If the filtered output isn't empty, it will be used instead of generating 
  16. * the default gallery template. 
  17. * @since 2.5.0 
  18. * @since 4.2.0 The `$instance` parameter was added. 
  19. * @see gallery_shortcode() 
  20. * @param string $output The gallery output. Default empty. 
  21. * @param array $attr Attributes of the gallery shortcode. 
  22. * @param int $instance Unique numeric ID of this gallery shortcode instance. 
  23. */ 
  24. $output = apply_filters( 'post_gallery', '', $attr, $instance ); 
  25. if ( $output != '' ) { 
  26. return $output; 
  27.  
  28. $html5 = current_theme_supports( 'html5', 'gallery' ); 
  29. $atts = shortcode_atts( array( 
  30. 'order' => 'ASC',  
  31. 'orderby' => 'menu_order ID',  
  32. 'id' => $post ? $post->ID : 0,  
  33. 'itemtag' => $html5 ? 'figure' : 'dl',  
  34. 'icontag' => $html5 ? 'div' : 'dt',  
  35. 'captiontag' => $html5 ? 'figcaption' : 'dd',  
  36. 'columns' => 3,  
  37. 'size' => 'thumbnail',  
  38. 'include' => '',  
  39. 'exclude' => '',  
  40. 'link' => '' 
  41. ), $attr, 'gallery' ); 
  42.  
  43. $id = intval( $atts['id'] ); 
  44.  
  45. if ( ! empty( $atts['include'] ) ) { 
  46. $_attachments = get_posts( array( 'include' => $atts['include'], 'post_status' => 'inherit', 'post_type' => 'attachment', 'post_mime_type' => 'image', 'order' => $atts['order'], 'orderby' => $atts['orderby'] ) ); 
  47.  
  48. $attachments = array(); 
  49. foreach ( $_attachments as $key => $val ) { 
  50. $attachments[$val->ID] = $_attachments[$key]; 
  51. } elseif ( ! empty( $atts['exclude'] ) ) { 
  52. $attachments = get_children( array( 'post_parent' => $id, 'exclude' => $atts['exclude'], 'post_status' => 'inherit', 'post_type' => 'attachment', 'post_mime_type' => 'image', 'order' => $atts['order'], 'orderby' => $atts['orderby'] ) ); 
  53. } else { 
  54. $attachments = get_children( array( 'post_parent' => $id, 'post_status' => 'inherit', 'post_type' => 'attachment', 'post_mime_type' => 'image', 'order' => $atts['order'], 'orderby' => $atts['orderby'] ) ); 
  55.  
  56. if ( empty( $attachments ) ) { 
  57. return ''; 
  58.  
  59. if ( is_feed() ) { 
  60. $output = "\n"; 
  61. foreach ( $attachments as $att_id => $attachment ) { 
  62. $output .= wp_get_attachment_link( $att_id, $atts['size'], true ) . "\n"; 
  63. return $output; 
  64.  
  65. $itemtag = tag_escape( $atts['itemtag'] ); 
  66. $captiontag = tag_escape( $atts['captiontag'] ); 
  67. $icontag = tag_escape( $atts['icontag'] ); 
  68. $valid_tags = wp_kses_allowed_html( 'post' ); 
  69. if ( ! isset( $valid_tags[ $itemtag ] ) ) { 
  70. $itemtag = 'dl'; 
  71. if ( ! isset( $valid_tags[ $captiontag ] ) ) { 
  72. $captiontag = 'dd'; 
  73. if ( ! isset( $valid_tags[ $icontag ] ) ) { 
  74. $icontag = 'dt'; 
  75.  
  76. $columns = intval( $atts['columns'] ); 
  77. $itemwidth = $columns > 0 ? floor(100/$columns) : 100; 
  78. $float = is_rtl() ? 'right' : 'left'; 
  79.  
  80. $selector = "gallery-{$instance}"; 
  81.  
  82. $gallery_style = ''; 
  83.  
  84. /** 
  85. * Filters whether to print default gallery styles. 
  86. * @since 3.1.0 
  87. * @param bool $print Whether to print default gallery styles. 
  88. * Defaults to false if the theme supports HTML5 galleries. 
  89. * Otherwise, defaults to true. 
  90. */ 
  91. $gallery_style = " 
  92. <style type='text/css'> 
  93. #{$selector} { 
  94. margin: auto; 
  95. #{$selector} .gallery-item { 
  96. float: {$float}; 
  97. margin-top: 10px; 
  98. text-align: center; 
  99. width: {$itemwidth}%; 
  100. #{$selector} img { 
  101. border: 2px solid #cfcfcf; 
  102. #{$selector} .gallery-caption { 
  103. margin-left: 0; 
  104. /* see gallery_shortcode() in wp-includes/media.php */ 
  105. </style>\n\t\t"; 
  106.  
  107. $size_class = sanitize_html_class( $atts['size'] ); 
  108. $gallery_div = "<div id='$selector' class='gallery galleryid-{$id} gallery-columns-{$columns} gallery-size-{$size_class}'>"; 
  109.  
  110. /** 
  111. * Filters the default gallery shortcode CSS styles. 
  112. * @since 2.5.0 
  113. * @param string $gallery_style Default CSS styles and opening HTML div container 
  114. * for the gallery shortcode output. 
  115. */ 
  116. $output = apply_filters( 'gallery_style', $gallery_style . $gallery_div ); 
  117.  
  118. $i = 0; 
  119. foreach ( $attachments as $id => $attachment ) { 
  120.  
  121. $attr = ( trim( $attachment->post_excerpt ) ) ? array( 'aria-describedby' => "$selector-$id" ) : ''; 
  122. if ( ! empty( $atts['link'] ) && 'file' === $atts['link'] ) { 
  123. $image_output = wp_get_attachment_link( $id, $atts['size'], false, false, false, $attr ); 
  124. } elseif ( ! empty( $atts['link'] ) && 'none' === $atts['link'] ) { 
  125. $image_output = wp_get_attachment_image( $id, $atts['size'], false, $attr ); 
  126. } else { 
  127. $image_output = wp_get_attachment_link( $id, $atts['size'], true, false, false, $attr ); 
  128. $image_meta = wp_get_attachment_metadata( $id ); 
  129.  
  130. $orientation = ''; 
  131. if ( isset( $image_meta['height'], $image_meta['width'] ) ) { 
  132. $orientation = ( $image_meta['height'] > $image_meta['width'] ) ? 'portrait' : 'landscape'; 
  133. $output .= "<{$itemtag} class='gallery-item'>"; 
  134. $output .= " 
  135. <{$icontag} class='gallery-icon {$orientation}'> 
  136. $image_output 
  137. </{$icontag}>"; 
  138. if ( $captiontag && trim($attachment->post_excerpt) ) { 
  139. $output .= " 
  140. <{$captiontag} class='wp-caption-text gallery-caption' id='$selector-$id'> 
  141. " . wptexturize($attachment->post_excerpt) . " 
  142. </{$captiontag}>"; 
  143. $output .= "</{$itemtag}>"; 
  144. if ( ! $html5 && $columns > 0 && ++$i % $columns == 0 ) { 
  145. $output .= '<br style="clear: both" />'; 
  146.  
  147. if ( ! $html5 && $columns > 0 && $i % $columns !== 0 ) { 
  148. $output .= " 
  149. <br style='clear: both' />"; 
  150.  
  151. $output .= " 
  152. </div>\n"; 
  153.  
  154. return $output;