WordPress.org

Make WordPress Core

Changeset 37915


Ignore:
Timestamp:
06/29/2016 05:28:00 PM (4 years ago)
Author:
joemcgill
Message:

Post Thumbnails: Add helper functions for attachment captions.

This adds three new functions for getting/displaying attachment captions:

  • wp_get_attachment_caption - Retrieves a caption for a specific attachment.
  • get_the_post_thumbnail_caption() - Returns the post thumbnail caption.
  • the_post_thumbnail_caption() - Displays the post thumbnail caption.

These are helpful for displaying a caption associated with an image directly
in a template, rather than using the caption shortcode.

This also introduces two new filters:

  • wp_get_attachment_caption - Filters the value of wp_get_attachment_caption().
  • the_post_thumbnail_caption - Filters the display of the post thumbnail caption.

the_post_thumbnail_caption() is automatically filtered by wptexturize(),
convert_smilies(), and convert_chars() in wp-includes/default-filters.php.

Props flixos90, joemcgill.
Fixes #12235.

Location:
trunk
Files:
5 edited

Legend:

Unmodified
Added
Removed
  • trunk/src/wp-includes/default-filters.php

    r37908 r37915  
    143143add_filter( 'the_excerpt',     'shortcode_unautop');
    144144add_filter( 'get_the_excerpt', 'wp_trim_excerpt'  );
     145
     146add_filter( 'the_post_thumbnail_caption', 'wptexturize'     );
     147add_filter( 'the_post_thumbnail_caption', 'convert_smilies' );
     148add_filter( 'the_post_thumbnail_caption', 'convert_chars'   );
    145149
    146150add_filter( 'comment_text', 'wptexturize'            );
  • trunk/src/wp-includes/post-thumbnail-template.php

    r37502 r37915  
    211211    }
    212212}
     213
     214/**
     215 * Returns the post thumbnail caption.
     216 *
     217 * @since 4.6.0
     218 *
     219 * @param int|WP_Post $post Optional. Post ID or WP_Post object. Default is global `$post`.
     220 * @return string Post thumbnail caption.
     221 */
     222function get_the_post_thumbnail_caption( $post = null ) {
     223    $post_thumbnail_id = get_post_thumbnail_id( $post );
     224    if ( ! $post_thumbnail_id ) {
     225        return '';
     226    }
     227
     228    $caption = wp_get_attachment_caption( $post_thumbnail_id );
     229
     230    if ( ! $caption ) {
     231        $caption = '';
     232    }
     233
     234    return $caption;
     235}
     236
     237/**
     238 * Displays the post thumbnail caption.
     239 *
     240 * @since 4.6.0
     241 *
     242 * @param int|WP_Post $post Optional. Post ID or WP_Post object. Default is global `$post`.
     243 */
     244function the_post_thumbnail_caption( $post = null ) {
     245    /**
     246     * Filters the displayed post thumbnail caption.
     247     *
     248     * @since 4.6.0
     249     *
     250     * @param string $caption Caption for the given attachment.
     251     */
     252    echo apply_filters( 'the_post_thumbnail_caption', get_the_post_thumbnail_caption( $post ) );
     253}
  • trunk/src/wp-includes/post.php

    r37890 r37915  
    49384938
    49394939/**
     4940 * Retrieves the caption for an attachment.
     4941 *
     4942 * @since 4.6.0
     4943 *
     4944 * @param int $post_id Optional. Attachment ID. Default 0.
     4945 * @return string|false False on failure. Attachment caption on success.
     4946 */
     4947function wp_get_attachment_caption( $post_id = 0 ) {
     4948    $post_id = (int) $post_id;
     4949    if ( ! $post = get_post( $post_id ) ) {
     4950        return false;
     4951    }
     4952
     4953    if ( 'attachment' !== $post->post_type ) {
     4954        return false;
     4955    }
     4956
     4957    $caption = $post->post_excerpt;
     4958
     4959    /**
     4960     * Filters the attachment caption.
     4961     *
     4962     * @since 4.6.0
     4963     *
     4964     * @param string $caption Caption for the given attachment.
     4965     * @param int    $post_id Attachment ID.
     4966     */
     4967    return apply_filters( 'wp_get_attachment_caption', $caption, $post->ID );
     4968}
     4969
     4970/**
    49404971 * Retrieve thumbnail for an attachment.
    49414972 *
  • trunk/tests/phpunit/tests/media.php

    r37702 r37915  
    903903
    904904    /**
     905     * @ticket 12235
     906     */
     907    function test_wp_get_attachment_caption() {
     908        $this->assertFalse( wp_get_attachment_caption( 0 ) );
     909
     910        $caption = 'This is a caption.';
     911
     912        $post_id = self::factory()->post->create();
     913        $attachment_id = self::factory()->attachment->create_object( $this->img_name, $post_id, array(
     914            'post_mime_type' => 'image/jpeg',
     915            'post_type'      => 'attachment',
     916            'post_excerpt'   => $caption,
     917        ) );
     918
     919        $this->assertFalse( wp_get_attachment_caption( $post_id ) );
     920
     921        $this->assertEquals( $caption, wp_get_attachment_caption( $attachment_id ) );
     922    }
     923
     924    /**
     925     * @ticket 12235
     926     */
     927    function test_wp_get_attachment_caption_empty() {
     928        $post_id = self::factory()->post->create();
     929        $attachment_id = self::factory()->attachment->create_object( $this->img_name, $post_id, array(
     930            'post_mime_type' => 'image/jpeg',
     931            'post_type'      => 'attachment',
     932            'post_excerpt'   => '',
     933        ) );
     934
     935        $this->assertEquals( '', wp_get_attachment_caption( $attachment_id ) );
     936    }
     937
     938    /**
    905939     * Helper function to get image size array from size "name"
    906940     */
  • trunk/tests/phpunit/tests/post/thumbnails.php

    r35244 r37915  
    7575    }
    7676
     77    /**
     78     * @ticket 12235
     79     */
     80    function test_get_the_post_thumbnail_caption() {
     81        $this->assertEquals( '', get_the_post_thumbnail_caption() );
     82
     83        $caption = 'This is a caption.';
     84
     85        $post_id = self::factory()->post->create();
     86        $attachment_id = self::factory()->attachment->create_object( 'image.jpg', $post_id, array(
     87            'post_mime_type' => 'image/jpeg',
     88            'post_type'      => 'attachment',
     89            'post_excerpt'   => $caption,
     90        ) );
     91
     92        set_post_thumbnail( $post_id, $attachment_id );
     93
     94        $this->assertEquals( $caption, get_the_post_thumbnail_caption( $post_id ) );
     95    }
     96
     97    /**
     98     * @ticket 12235
     99     */
     100    function test_get_the_post_thumbnail_caption_empty() {
     101        $post_id = self::factory()->post->create();
     102        $attachment_id = self::factory()->attachment->create_object( 'image.jpg', $post_id, array(
     103            'post_mime_type' => 'image/jpeg',
     104            'post_type'      => 'attachment',
     105            'post_excerpt'   => '',
     106        ) );
     107
     108        set_post_thumbnail( $post_id, $attachment_id );
     109
     110        $this->assertEquals( '', get_the_post_thumbnail_caption( $post_id ) );
     111    }
     112
     113    /**
     114     * @ticket 12235
     115     */
     116    function test_the_post_thumbnail_caption() {
     117        $caption = 'This is a caption.';
     118
     119        $post_id = self::factory()->post->create();
     120        $attachment_id = self::factory()->attachment->create_object( 'image.jpg', $post_id, array(
     121            'post_mime_type' => 'image/jpeg',
     122            'post_type'      => 'attachment',
     123            'post_excerpt'   => $caption,
     124        ) );
     125
     126        set_post_thumbnail( $post_id, $attachment_id );
     127
     128        ob_start();
     129        the_post_thumbnail_caption( $post_id );
     130
     131        $this->assertEquals( $caption, ob_get_clean() );
     132    }
     133
    77134    function test_get_the_post_thumbnail() {
    78135        $this->assertEquals( '', get_the_post_thumbnail() );
Note: See TracChangeset for help on using the changeset viewer.