wp_playlist_shortcode

Builds the Playlist shortcode output.

Description

(string) wp_playlist_shortcode( (array) $attr ); 

This implements the functionality of the playlist shortcode for displaying a collection of WordPress audio or video files in a post.

Returns (string)

Playlist output. Empty string if the passed type is unsupported.

Parameters (1)

0. $attr (array)
Array of default playlist attributes.

Options

  • type (string) => 'audio'

    Type of playlist to display. Accepts audio or video..

  • order (string) => 'ASC'

    Designates ascending or descending order of items in the playlist. Accepts ASC,, DESC..

  • orderby (string) => ''

    Any column, or columns, to sort the playlist. If $ids are passed, this defaults to the order of the $ids array ('post__in'). Otherwise default is menu_order ID..

  • id (int) => is the current post ID

    If an explicit $ids array is not present, this parameter will determine which attachments are used for the playlist.

  • ids (array) => null

    Create a playlist out of these explicit attachment IDs. If empty, a playlist will be created from all $type attachments of $id.

  • exclude (array) => null

    List of specific attachment IDs to exclude from the playlist.

  • style (string) => 'light'

    Playlist style to use. Accepts light or dark..

  • tracklist (bool) => true

    Whether to show or hide the playlist.

  • tracknumbers (bool) => true

    Whether to show or hide the numbers next to entries in the playlist.

  • images (bool) => true

    Show or hide the video or audio thumbnail (Featured Image/post thumbnail).

array(

    /**
     * Type of playlist to display. Accepts 'audio' or 'video'.
     *
     * @type string
     * @default 'audio'
     */
    'type' => 'audio',

    /**
     * Designates ascending or descending order of items in the playlist. Accepts 'ASC', 'DESC'.
     *
     * @type string
     * @default 'ASC'
     */
    'order' => 'ASC',

    /**
     * Any column, or columns, to sort the playlist. If $ids are passed, this defaults to the order of
     * the $ids array ('post__in'). Otherwise default is 'menu_order ID'.
     *
     * @type string
     * @default ''
     */
    'orderby' => '',

    /**
     * If an explicit $ids array is not present, this parameter will determine which attachments are
     * used for the playlist.
     *
     * @type int
     * @default is the current post ID
     */
    'id' => is the current post ID,

    /**
     * Create a playlist out of these explicit attachment IDs. If empty, a playlist will be created
     * from all $type attachments of $id.
     *
     * @type array
     * @default null
     */
    'ids' => null,

    /**
     * List of specific attachment IDs to exclude from the playlist.
     *
     * @type array
     * @default null
     */
    'exclude' => null,

    /**
     * Playlist style to use. Accepts 'light' or 'dark'.
     *
     * @type string
     * @default 'light'
     */
    'style' => 'light',

    /**
     * Whether to show or hide the playlist.
     *
     * @type bool
     * @default true
     */
    'tracklist' => true,

    /**
     * Whether to show or hide the numbers next to entries in the playlist.
     *
     * @type bool
     * @default true
     */
    'tracknumbers' => true,

    /**
     * Show or hide the video or audio thumbnail (Featured Image/post thumbnail).
     *
     * @type bool
     * @default true
     */
    'images' => true
);        


Usage

  1. if ( !function_exists( 'wp_playlist_shortcode' ) ) { 
  2. require_once ABSPATH . WPINC . '/media.php'; 
  3.  
  4. // Array of default playlist attributes. 
  5. $attr = array( 
  6. 'type' => 'audio', 
  7. 'order' => 'ASC', 
  8. 'orderby' => '', 
  9. 'id' => is the current post ID, 
  10. 'ids' => null, 
  11. 'exclude' => null, 
  12. 'style' => 'light', 
  13. 'tracklist' => true, 
  14. 'tracknumbers' => true, 
  15. 'images' => true 
  16. ); 
  17.  
  18. // NOTICE! Understand what this does before running. 
  19. $result = wp_playlist_shortcode($attr); 
  20.  

Defined (1)

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

/wp-includes/media.php  
  1. function wp_playlist_shortcode( $attr ) { 
  2. global $content_width; 
  3. $post = get_post(); 
  4.  
  5. static $instance = 0; 
  6. $instance++; 
  7.  
  8. if ( ! empty( $attr['ids'] ) ) { 
  9. // 'ids' is explicitly ordered, unless you specify otherwise. 
  10. if ( empty( $attr['orderby'] ) ) { 
  11. $attr['orderby'] = 'post__in'; 
  12. $attr['include'] = $attr['ids']; 
  13.  
  14. /** 
  15. * Filters the playlist output. 
  16. * Passing a non-empty value to the filter will short-circuit generation 
  17. * of the default playlist output, returning the passed value instead. 
  18. * @since 3.9.0 
  19. * @since 4.2.0 The `$instance` parameter was added. 
  20. * @param string $output Playlist output. Default empty. 
  21. * @param array $attr An array of shortcode attributes. 
  22. * @param int $instance Unique numeric ID of this playlist shortcode instance. 
  23. */ 
  24. $output = apply_filters( 'post_playlist', '', $attr, $instance ); 
  25. if ( $output != '' ) { 
  26. return $output; 
  27.  
  28. $atts = shortcode_atts( array( 
  29. 'type' => 'audio',  
  30. 'order' => 'ASC',  
  31. 'orderby' => 'menu_order ID',  
  32. 'id' => $post ? $post->ID : 0,  
  33. 'include' => '',  
  34. 'exclude' => '',  
  35. 'style' => 'light',  
  36. 'tracklist' => true,  
  37. 'tracknumbers' => true,  
  38. 'images' => true,  
  39. 'artists' => true 
  40. ), $attr, 'playlist' ); 
  41.  
  42. $id = intval( $atts['id'] ); 
  43.  
  44. if ( $atts['type'] !== 'audio' ) { 
  45. $atts['type'] = 'video'; 
  46.  
  47. $args = array( 
  48. 'post_status' => 'inherit',  
  49. 'post_type' => 'attachment',  
  50. 'post_mime_type' => $atts['type'],  
  51. 'order' => $atts['order'],  
  52. 'orderby' => $atts['orderby'] 
  53. ); 
  54.  
  55. if ( ! empty( $atts['include'] ) ) { 
  56. $args['include'] = $atts['include']; 
  57. $_attachments = get_posts( $args ); 
  58.  
  59. $attachments = array(); 
  60. foreach ( $_attachments as $key => $val ) { 
  61. $attachments[$val->ID] = $_attachments[$key]; 
  62. } elseif ( ! empty( $atts['exclude'] ) ) { 
  63. $args['post_parent'] = $id; 
  64. $args['exclude'] = $atts['exclude']; 
  65. $attachments = get_children( $args ); 
  66. } else { 
  67. $args['post_parent'] = $id; 
  68. $attachments = get_children( $args ); 
  69.  
  70. if ( empty( $attachments ) ) { 
  71. return ''; 
  72.  
  73. if ( is_feed() ) { 
  74. $output = "\n"; 
  75. foreach ( $attachments as $att_id => $attachment ) { 
  76. $output .= wp_get_attachment_link( $att_id ) . "\n"; 
  77. return $output; 
  78.  
  79. $outer = 22; // default padding and border of wrapper 
  80.  
  81. $default_width = 640; 
  82. $default_height = 360; 
  83.  
  84. $theme_width = empty( $content_width ) ? $default_width : ( $content_width - $outer ); 
  85. $theme_height = empty( $content_width ) ? $default_height : round( ( $default_height * $theme_width ) / $default_width ); 
  86.  
  87. $data = array( 
  88. 'type' => $atts['type'],  
  89. // don't pass strings to JSON, will be truthy in JS 
  90. 'tracklist' => wp_validate_boolean( $atts['tracklist'] ),  
  91. 'tracknumbers' => wp_validate_boolean( $atts['tracknumbers'] ),  
  92. 'images' => wp_validate_boolean( $atts['images'] ),  
  93. 'artists' => wp_validate_boolean( $atts['artists'] ),  
  94. ); 
  95.  
  96. $tracks = array(); 
  97. foreach ( $attachments as $attachment ) { 
  98. $url = wp_get_attachment_url( $attachment->ID ); 
  99. $ftype = wp_check_filetype( $url, wp_get_mime_types() ); 
  100. $track = array( 
  101. 'src' => $url,  
  102. 'type' => $ftype['type'],  
  103. 'title' => $attachment->post_title,  
  104. 'caption' => $attachment->post_excerpt,  
  105. 'description' => $attachment->post_content 
  106. ); 
  107.  
  108. $track['meta'] = array(); 
  109. $meta = wp_get_attachment_metadata( $attachment->ID ); 
  110. if ( ! empty( $meta ) ) { 
  111.  
  112. foreach ( wp_get_attachment_id3_keys( $attachment ) as $key => $label ) { 
  113. if ( ! empty( $meta[ $key ] ) ) { 
  114. $track['meta'][ $key ] = $meta[ $key ]; 
  115.  
  116. if ( 'video' === $atts['type'] ) { 
  117. if ( ! empty( $meta['width'] ) && ! empty( $meta['height'] ) ) { 
  118. $width = $meta['width']; 
  119. $height = $meta['height']; 
  120. $theme_height = round( ( $height * $theme_width ) / $width ); 
  121. } else { 
  122. $width = $default_width; 
  123. $height = $default_height; 
  124.  
  125. $track['dimensions'] = array( 
  126. 'original' => compact( 'width', 'height' ),  
  127. 'resized' => array( 
  128. 'width' => $theme_width,  
  129. 'height' => $theme_height 
  130. ); 
  131.  
  132. if ( $atts['images'] ) { 
  133. $thumb_id = get_post_thumbnail_id( $attachment->ID ); 
  134. if ( ! empty( $thumb_id ) ) { 
  135. list( $src, $width, $height ) = wp_get_attachment_image_src( $thumb_id, 'full' ); 
  136. $track['image'] = compact( 'src', 'width', 'height' ); 
  137. list( $src, $width, $height ) = wp_get_attachment_image_src( $thumb_id, 'thumbnail' ); 
  138. $track['thumb'] = compact( 'src', 'width', 'height' ); 
  139. } else { 
  140. $src = wp_mime_type_icon( $attachment->ID ); 
  141. $width = 48; 
  142. $height = 64; 
  143. $track['image'] = compact( 'src', 'width', 'height' ); 
  144. $track['thumb'] = compact( 'src', 'width', 'height' ); 
  145.  
  146. $tracks[] = $track; 
  147. $data['tracks'] = $tracks; 
  148.  
  149. $safe_type = esc_attr( $atts['type'] ); 
  150. $safe_style = esc_attr( $atts['style'] ); 
  151.  
  152. ob_start(); 
  153.  
  154. if ( 1 === $instance ) { 
  155. /** 
  156. * Prints and enqueues playlist scripts, styles, and JavaScript templates. 
  157. * @since 3.9.0 
  158. * @param string $type Type of playlist. Possible values are 'audio' or 'video'. 
  159. * @param string $style The 'theme' for the playlist. Core provides 'light' and 'dark'. 
  160. */ 
  161. do_action( 'wp_playlist_scripts', $atts['type'], $atts['style'] ); 
  162. } ?> 
  163. <div class="wp-playlist wp-<?php echo $safe_type ?>-playlist wp-playlist-<?php echo $safe_style ?>"> 
  164. <?php if ( 'audio' === $atts['type'] ): ?> 
  165. <div class="wp-playlist-current-item"></div> 
  166. <?php endif ?> 
  167. <<?php echo $safe_type ?> controls="controls" preload="none" width="<?php 
  168. echo (int) $theme_width; 
  169. ?>"<?php if ( 'video' === $safe_type ): 
  170. echo ' height="', (int) $theme_height, '"'; 
  171. endif; ?>></<?php echo $safe_type ?>> 
  172. <div class="wp-playlist-next"></div> 
  173. <div class="wp-playlist-prev"></div> 
  174. <noscript> 
  175. <ol><?php 
  176. foreach ( $attachments as $att_id => $attachment ) { 
  177. printf( '<li>%s</li>', wp_get_attachment_link( $att_id ) ); 
  178. ?></ol> 
  179. </noscript> 
  180. <script type="application/json" class="wp-playlist-script"><?php echo wp_json_encode( $data ) ?></script> 
  181. </div> 
  182. <?php 
  183. return ob_get_clean();