home *** CD-ROM | disk | FTP | other *** search
/ HTML Examples / WP.iso / wordpress / wp-includes / post-thumbnail-template.php < prev    next >
Encoding:
PHP Script  |  2017-08-18  |  8.0 KB  |  256 lines
  1. <?php
  2. /**
  3.  * WordPress Post Thumbnail Template Functions.
  4.  *
  5.  * Support for post thumbnails.
  6.  * Theme's functions.php must call add_theme_support( 'post-thumbnails' ) to use these.
  7.  *
  8.  * @package WordPress
  9.  * @subpackage Template
  10.  */
  11.  
  12. /**
  13.  * Check if post has an image attached.
  14.  *
  15.  * @since 2.9.0
  16.  * @since 4.4.0 `$post` can be a post ID or WP_Post object.
  17.  *
  18.  * @param int|WP_Post $post Optional. Post ID or WP_Post object. Default is global `$post`.
  19.  * @return bool Whether the post has an image attached.
  20.  */
  21. function has_post_thumbnail( $post = null ) {
  22.     return (bool) get_post_thumbnail_id( $post );
  23. }
  24.  
  25. /**
  26.  * Retrieve post thumbnail ID.
  27.  *
  28.  * @since 2.9.0
  29.  * @since 4.4.0 `$post` can be a post ID or WP_Post object.
  30.  *
  31.  * @param int|WP_Post $post Optional. Post ID or WP_Post object. Default is global `$post`.
  32.  * @return string|int Post thumbnail ID or empty string.
  33.  */
  34. function get_post_thumbnail_id( $post = null ) {
  35.     $post = get_post( $post );
  36.     if ( ! $post ) {
  37.         return '';
  38.     }
  39.     return get_post_meta( $post->ID, '_thumbnail_id', true );
  40. }
  41.  
  42. /**
  43.  * Display the post thumbnail.
  44.  *
  45.  * When a theme adds 'post-thumbnail' support, a special 'post-thumbnail' image size
  46.  * is registered, which differs from the 'thumbnail' image size managed via the
  47.  * Settings > Media screen.
  48.  *
  49.  * When using the_post_thumbnail() or related functions, the 'post-thumbnail' image
  50.  * size is used by default, though a different size can be specified instead as needed.
  51.  *
  52.  * @since 2.9.0
  53.  *
  54.  * @see get_the_post_thumbnail()
  55.  *
  56.  * @param string|array $size Optional. Image size to use. Accepts any valid image size, or
  57.  *                           an array of width and height values in pixels (in that order).
  58.  *                           Default 'post-thumbnail'.
  59.  * @param string|array $attr Optional. Query string or array of attributes. Default empty.
  60.  */
  61. function the_post_thumbnail( $size = 'post-thumbnail', $attr = '' ) {
  62.     echo get_the_post_thumbnail( null, $size, $attr );
  63. }
  64.  
  65. /**
  66.  * Update cache for thumbnails in the current loop.
  67.  *
  68.  * @since 3.2.0
  69.  *
  70.  * @global WP_Query $wp_query
  71.  *
  72.  * @param WP_Query $wp_query Optional. A WP_Query instance. Defaults to the $wp_query global.
  73.  */
  74. function update_post_thumbnail_cache( $wp_query = null ) {
  75.     if ( ! $wp_query )
  76.         $wp_query = $GLOBALS['wp_query'];
  77.  
  78.     if ( $wp_query->thumbnails_cached )
  79.         return;
  80.  
  81.     $thumb_ids = array();
  82.     foreach ( $wp_query->posts as $post ) {
  83.         if ( $id = get_post_thumbnail_id( $post->ID ) )
  84.             $thumb_ids[] = $id;
  85.     }
  86.  
  87.     if ( ! empty ( $thumb_ids ) ) {
  88.         _prime_post_caches( $thumb_ids, false, true );
  89.     }
  90.  
  91.     $wp_query->thumbnails_cached = true;
  92. }
  93.  
  94. /**
  95.  * Retrieve the post thumbnail.
  96.  *
  97.  * When a theme adds 'post-thumbnail' support, a special 'post-thumbnail' image size
  98.  * is registered, which differs from the 'thumbnail' image size managed via the
  99.  * Settings > Media screen.
  100.  *
  101.  * When using the_post_thumbnail() or related functions, the 'post-thumbnail' image
  102.  * size is used by default, though a different size can be specified instead as needed.
  103.  *
  104.  * @since 2.9.0
  105.  * @since 4.4.0 `$post` can be a post ID or WP_Post object.
  106.  *
  107.  * @param int|WP_Post  $post Optional. Post ID or WP_Post object.  Default is global `$post`.
  108.  * @param string|array $size Optional. Image size to use. Accepts any valid image size, or
  109.  *                           an array of width and height values in pixels (in that order).
  110.  *                           Default 'post-thumbnail'.
  111.  * @param string|array $attr Optional. Query string or array of attributes. Default empty.
  112.  * @return string The post thumbnail image tag.
  113.  */
  114. function get_the_post_thumbnail( $post = null, $size = 'post-thumbnail', $attr = '' ) {
  115.     $post = get_post( $post );
  116.     if ( ! $post ) {
  117.         return '';
  118.     }
  119.     $post_thumbnail_id = get_post_thumbnail_id( $post );
  120.  
  121.     /**
  122.      * Filters the post thumbnail size.
  123.      *
  124.      * @since 2.9.0
  125.      * @since 4.9.0 Added the `$post_id` parameter.
  126.      *
  127.      * @param string|array $size    The post thumbnail size. Image size or array of width and height
  128.      *                              values (in that order). Default 'post-thumbnail'.
  129.      * @param int          $post_id The post ID.
  130.      */
  131.     $size = apply_filters( 'post_thumbnail_size', $size, $post->ID );
  132.  
  133.     if ( $post_thumbnail_id ) {
  134.  
  135.         /**
  136.          * Fires before fetching the post thumbnail HTML.
  137.          *
  138.          * Provides "just in time" filtering of all filters in wp_get_attachment_image().
  139.          *
  140.          * @since 2.9.0
  141.          *
  142.          * @param int          $post_id           The post ID.
  143.          * @param string       $post_thumbnail_id The post thumbnail ID.
  144.          * @param string|array $size              The post thumbnail size. Image size or array of width
  145.          *                                        and height values (in that order). Default 'post-thumbnail'.
  146.          */
  147.         do_action( 'begin_fetch_post_thumbnail_html', $post->ID, $post_thumbnail_id, $size );
  148.         if ( in_the_loop() )
  149.             update_post_thumbnail_cache();
  150.         $html = wp_get_attachment_image( $post_thumbnail_id, $size, false, $attr );
  151.  
  152.         /**
  153.          * Fires after fetching the post thumbnail HTML.
  154.          *
  155.          * @since 2.9.0
  156.          *
  157.          * @param int          $post_id           The post ID.
  158.          * @param string       $post_thumbnail_id The post thumbnail ID.
  159.          * @param string|array $size              The post thumbnail size. Image size or array of width
  160.          *                                        and height values (in that order). Default 'post-thumbnail'.
  161.          */
  162.         do_action( 'end_fetch_post_thumbnail_html', $post->ID, $post_thumbnail_id, $size );
  163.  
  164.     } else {
  165.         $html = '';
  166.     }
  167.     /**
  168.      * Filters the post thumbnail HTML.
  169.      *
  170.      * @since 2.9.0
  171.      *
  172.      * @param string       $html              The post thumbnail HTML.
  173.      * @param int          $post_id           The post ID.
  174.      * @param string       $post_thumbnail_id The post thumbnail ID.
  175.      * @param string|array $size              The post thumbnail size. Image size or array of width and height
  176.      *                                        values (in that order). Default 'post-thumbnail'.
  177.      * @param string       $attr              Query string of attributes.
  178.      */
  179.     return apply_filters( 'post_thumbnail_html', $html, $post->ID, $post_thumbnail_id, $size, $attr );
  180. }
  181.  
  182. /**
  183.  * Return the post thumbnail URL.
  184.  *
  185.  * @since 4.4.0
  186.  *
  187.  * @param int|WP_Post  $post Optional. Post ID or WP_Post object.  Default is global `$post`.
  188.  * @param string|array $size Optional. Registered image size to retrieve the source for or a flat
  189.  *                           array of height and width dimensions. Default 'post-thumbnail'.
  190.  * @return string|false Post thumbnail URL or false if no URL is available.
  191.  */
  192. function get_the_post_thumbnail_url( $post = null, $size = 'post-thumbnail' ) {
  193.     $post_thumbnail_id = get_post_thumbnail_id( $post );
  194.     if ( ! $post_thumbnail_id ) {
  195.         return false;
  196.     }
  197.     return wp_get_attachment_image_url( $post_thumbnail_id, $size );
  198. }
  199.  
  200. /**
  201.  * Display the post thumbnail URL.
  202.  *
  203.  * @since 4.4.0
  204.  *
  205.  * @param string|array $size Optional. Image size to use. Accepts any valid image size,
  206.  *                           or an array of width and height values in pixels (in that order).
  207.  *                           Default 'post-thumbnail'.
  208.  */
  209. function the_post_thumbnail_url( $size = 'post-thumbnail' ) {
  210.     $url = get_the_post_thumbnail_url( null, $size );
  211.     if ( $url ) {
  212.         echo esc_url( $url );
  213.     }
  214. }
  215.  
  216. /**
  217.  * Returns the post thumbnail caption.
  218.  *
  219.  * @since 4.6.0
  220.  *
  221.  * @param int|WP_Post $post Optional. Post ID or WP_Post object. Default is global `$post`.
  222.  * @return string Post thumbnail caption.
  223.  */
  224. function get_the_post_thumbnail_caption( $post = null ) {
  225.     $post_thumbnail_id = get_post_thumbnail_id( $post );
  226.     if ( ! $post_thumbnail_id ) {
  227.         return '';
  228.     }
  229.  
  230.     $caption = wp_get_attachment_caption( $post_thumbnail_id );
  231.  
  232.     if ( ! $caption ) {
  233.         $caption = '';
  234.     }
  235.  
  236.     return $caption;
  237. }
  238.  
  239. /**
  240.  * Displays the post thumbnail caption.
  241.  *
  242.  * @since 4.6.0
  243.  *
  244.  * @param int|WP_Post $post Optional. Post ID or WP_Post object. Default is global `$post`.
  245.  */
  246. function the_post_thumbnail_caption( $post = null ) {
  247.     /**
  248.      * Filters the displayed post thumbnail caption.
  249.      *
  250.      * @since 4.6.0
  251.      *
  252.      * @param string $caption Caption for the given attachment.
  253.      */
  254.     echo apply_filters( 'the_post_thumbnail_caption', get_the_post_thumbnail_caption( $post ) );
  255. }
  256.