WordPress.org
Get WordPress

Make WordPress Core

Ticket #25621: post-template.2.diff

File post-template.2.diff, 13.7 KB (added by Toru, 10 years ago)

  • src/wp-includes/post-template.php

     
    107107
    108108        if ( ! is_admin() ) {
    109109                if ( ! empty( $post->post_password ) ) {
     110                        /**
     111                         * Filter the text which prepends the post title of protected posts.
     112                         *
     113                         * By default, this filter returns 'Protected: %s', where %s specifier is replaced with post title. This filter only apply on the front-end.
     114                         *
     115                         * @since  2.8.0
     116                         */
    110117                        $protected_title_format = apply_filters( 'protected_title_format', __( 'Protected: %s' ) );
    111118                        $title = sprintf( $protected_title_format, $title );
    112119                } else if ( isset( $post->post_status ) && 'private' == $post->post_status ) {
     120                        /**
     121                         * Filter the text which prepends the post title of private posts.
     122                         *
     123                         * By default, this filter returns 'Private: %s', where %s specifier is replaced with post title. This filter only apply on the front-end.
     124                         *
     125                         * @since 2.8.0
     126                         */
    113127                        $private_title_format = apply_filters( 'private_title_format', __( 'Private: %s' ) );
    114128                        $title = sprintf( $private_title_format, $title );
    115129                }
    116130        }
    117131
     132        /**
     133         * Filter the post title.
     134         *
     135         * @since 1.2.1
     136         *
     137         * @param string $title Post title.
     138         * @param int    $id    Post ID.
     139         */
    118140        return apply_filters( 'the_title', $title, $id );
    119141}
    120142
    … …  
    150172function get_the_guid( $id = 0 ) {
    151173        $post = get_post($id);
    152174
    153         return apply_filters('get_the_guid', $post->guid);
     175        /**
     176         * Filter the Global Unique Identifier (guid) of the post.
     177         *
     178         * @since 1.5.2
     179         *
     180         * @param string $post_guid Global Unique Identifier (guid) of the post.
     181         */
     182        return apply_filters( 'get_the_guid', $post->guid );
    154183}
    155184
    156185/**
    … …  
    159188 * @since 0.71
    160189 *
    161190 * @param string $more_link_text Optional. Content for when there is more text.
    162  * @param bool $strip_teaser Optional. Strip teaser content before the more text. Default is false.
     191 * @param bool   $strip_teaser  Optional. Strip teaser content before the more text. Default is false.
    163192 */
    164193function the_content( $more_link_text = null, $strip_teaser = false) {
    165194        $content = get_the_content( $more_link_text, $strip_teaser );
     195        /**
     196         * Filter the post content.
     197         *
     198         * @since 1.2.1
     199         *
     200         * @param string $content Content of the current post.
     201         */
    166202        $content = apply_filters( 'the_content', $content );
    167203        $content = str_replace( ']]>', ']]>', $content );
    168204        echo $content;
    … …  
    221257                        $output .= '<span id="more-' . $post->ID . '"></span>' . $content[1];
    222258                } else {
    223259                        if ( ! empty( $more_link_text ) )
     260                                /**
     261                                 * Filter the Read More link.
     262                                 *
     263                                 * @since 2.8.0
     264                                 *
     265                                 * @param string $more_link_text Read More link element.
     266                                 */
    224267                                $output .= apply_filters( 'the_content_more_link', ' <a href="' . get_permalink() . "#more-{$post->ID}\" class=\"more-link\">$more_link_text</a>", $more_link_text );
    225268                        $output = force_balance_tags( $output );
    226269                }
    … …  
    248291 * Display the post excerpt.
    249292 *
    250293 * @since 0.71
     294 *
    251295 * @uses apply_filters() Calls 'the_excerpt' hook on post excerpt.
    252296 */
    253297function the_excerpt() {
    254         echo apply_filters('the_excerpt', get_the_excerpt());
     298        echo apply_filters( 'the_excerpt', get_the_excerpt() );
    255299}
    256300
    257301/**
    … …  
    272316                return __( 'There is no excerpt because this is a protected post.' );
    273317        }
    274318
     319        /**
     320         * Filter the post excerpt.
     321         *
     322         * @since 1.5.2
     323         *
     324         * @param string $post_excerpt Post excerpt.
     325         */
    275326        return apply_filters( 'get_the_excerpt', $post->post_excerpt );
    276327}
    277328
    … …  
    379430
    380431        $classes = array_map('esc_attr', $classes);
    381432
    382         return apply_filters('post_class', $classes, $class, $post->ID);
     433        /**
     434         * Filter the CSS classes for the current post.
     435         *
     436         * @since 2.7.0
     437         *
     438         * @param array  $classes  An array of post classes.
     439         * @param string $class    A comma-separated list of additional classes added to the post.
     440         * @param int    $post_id Post ID.
     441         */
     442        return apply_filters( 'post_class', $classes, $class, $post->ID );
    383443}
    384444
    385445/**
    … …  
    563623
    564624        $classes = array_map( 'esc_attr', $classes );
    565625
     626        /**
     627         * Filter the returned CSS classes for the body of current post or page.
     628         *
     629         * @since 2.7.0
     630         *
     631         * @param array  $classes An array of body classes.
     632         * @param string $class   A comma-separated list of additional classes added to the body.
     633         */
    566634        return apply_filters( 'body_class', $classes, $class );
    567635}
    568636
    … …  
    650718        );
    651719
    652720        $r = wp_parse_args( $args, $defaults );
     721        /**
     722         * Filter the arguments used in retrieving page links for paginated posts
     723         *
     724         * @since 3.0.0
     725         *
     726         * @param array $r Overwrite the output format defaults.
     727         */
    653728        $r = apply_filters( 'wp_link_pages_args', $r );
    654729        extract( $r, EXTR_SKIP );
    655730
    … …  
    663738                                $link = $link_before . str_replace( '%', $i, $pagelink ) . $link_after;
    664739                                if ( $i != $page || ! $more && 1 == $page )
    665740                                        $link = _wp_link_page( $i ) . $link . '</a>';
     741                                /**
     742                                 * Filter the HTML output of individual page number links, in paginated posts' page links.
     743                                 *
     744                                 * @since 3.6.0
     745                                 *
     746                                 * @param string $link
     747                                 * @param int    $i    Page number for paginated posts' page links.
     748                                 */
    666749                                $link = apply_filters( 'wp_link_pages_link', $link, $i );
    667750                                $output .= $separator . $link;
    668751                        }
    … …  
    672755                        $i = $page - 1;
    673756                        if ( $i ) {
    674757                                $link = _wp_link_page( $i ) . $link_before . $previouspagelink . $link_after . '</a>';
     758                                /** This filter is documented in wp-includes/post-template.php */
    675759                                $link = apply_filters( 'wp_link_pages_link', $link, $i );
    676760                                $output .= $separator . $link;
    677761                        }
    678762                        $i = $page + 1;
    679763                        if ( $i <= $numpages ) {
    680764                                $link = _wp_link_page( $i ) . $link_before . $nextpagelink . $link_after . '</a>';
     765                                /** This filter is documented in wp-includes/post-template.php */
    681766                                $link = apply_filters( 'wp_link_pages_link', $link, $i );
    682767                                $output .= $separator . $link;
    683768                        }
    … …  
    685770                }
    686771        }
    687772
     773        /**
     774         * Filter the HTML output of page-links for paginated posts.
     775         *
     776         * @since 3.6.0
     777         *
     778         * @param string $output HTML output of paginated posts' page-links.
     779         * @param array  $args   Arguments.
     780         */
    688781        $output = apply_filters( 'wp_link_pages', $output, $args );
    689782
    690783        if ( $echo )
    … …  
    759852                                continue;
    760853                        $values = array_map('trim', get_post_custom_values($key));
    761854                        $value = implode($values,', ');
    762                         echo apply_filters('the_meta_key', "<li><span class='post-meta-key'>$key:</span> $value</li>\n", $key, $value);
     855                        /**
     856                         * Filter the HTML output of post custom fields list.
     857                         *
     858                         * This filters each li element of post custom fields list, which is an output of the_meta() function. Function the_meta() output in unordered list format.
     859                         *
     860                         * The default format:
     861                         *
     862                         *     <li><span class='post-meta-key'>$key:</span> $value</li>\n
     863                         *
     864                         * @since 2.2.0
     865                         *
     866                         * @param string $key   Key of the meta-data.
     867                         * @param string $value Value of the meta-data.
     868                         */
     869                        echo apply_filters( 'the_meta_key', "<li><span class='post-meta-key'>$key:</span> $value</li>\n", $key, $value );
    763870                }
    764871                echo "</ul>\n";
    765872        }
    … …  
    805912                $output .= "</select>\n";
    806913        }
    807914
    808         $output = apply_filters('wp_dropdown_pages', $output);
     915        /**
     916         * Filters the output of list of pages as dropdown (select list).
     917         *
     918         * @since 2.1.0
     919         *
     920         * @param string $output HTML dropdown list of pages.
     921         */
     922        $output = apply_filters( 'wp_dropdown_pages', $output );
    809923
    810924        if ( $echo )
    811925                echo $output;
    … …  
    842956
    843957        // Allow plugins to filter an array of excluded pages (but don't put a nullstring into the array)
    844958        $exclude_array = ( $r['exclude'] ) ? explode(',', $r['exclude']) : array();
    845         $r['exclude'] = implode( ',', apply_filters('wp_list_pages_excludes', $exclude_array) );
     959        /**
     960         * Filter an array of excluded pages for wp_list_pages().
     961         *
     962         * @since 2.1.0
     963         *
     964         * @param array $exclude_array Array of Page IDs to exclude from wp_list_pages() output.
     965         */
     966        $r['exclude'] = implode( ',', apply_filters( 'wp_list_pages_excludes', $exclude_array ) );
    846967
    847968        // Query pages.
    848969        $r['hierarchical'] = 0;
    … …  
    861982                        $output .= '</ul></li>';
    862983        }
    863984
    864         $output = apply_filters('wp_list_pages', $output, $r);
     985        /**
     986         * Filters the HTML output of the link list of WordPress Pages.
     987         *
     988         * Function wp_list_pages() displays a list of WordPress Pages as a link list. Filter wp_list_pages filters HTML output of this function wp_list_pages().
     989         *
     990         * @since 1.5.2
     991         *
     992         * @param string $output HTML output of the pages list.
     993         * @param array  $r      Array of arguments {
     994         *     @see wp_list_pages()
     995         * }
     996         */
     997        $output = apply_filters( 'wp_list_pages', $output, $r );
    865998
    866999        if ( $r['echo'] )
    8671000                echo $output;
    … …  
    8981031function wp_page_menu( $args = array() ) {
    8991032        $defaults = array('sort_column' => 'menu_order, post_title', 'menu_class' => 'menu', 'echo' => true, 'link_before' => '', 'link_after' => '');
    9001033        $args = wp_parse_args( $args, $defaults );
     1034        /**
     1035         * Filter the arguments passed to wp_page_menu().
     1036         *
     1037         * @since 2.7.0
     1038         *
     1039         * @param array $args An array of arguments {
     1040         *     @see wp_page_menu()
     1041         * }
     1042         */
    9011043        $args = apply_filters( 'wp_page_menu_args', $args );
    9021044
    9031045        $menu = '';
    … …  
    9331075                $menu = '<ul>' . $menu . '</ul>';
    9341076
    9351077        $menu = '<div class="' . esc_attr($args['menu_class']) . '">' . $menu . "</div>\n";
     1078        /**
     1079         * Filter the output and arguments of wp_page_menu().
     1080         *
     1081         * @since 2.7.0
     1082         *
     1083         * @param string $menu HTML output.
     1084         * @param array  $args An array of arguments {
     1085         *     @see wp_page_menu()
     1086         * }
     1087         */
    9361088        $menu = apply_filters( 'wp_page_menu', $menu, $args );
    9371089        if ( $args['echo'] )
    9381090                echo $menu;
    … …  
    10661218                        $css_class[] = 'current_page_parent';
    10671219                }
    10681220
     1221                /**
     1222                 * Filters the class attribute of li element in a list of WordPress Pages.
     1223                 *
     1224                 * Function wp_list_pages() displays a list of WordPress pages as a nested unordered link list, by default. Each li element has one or more classes applied. page_css_class filters these classes applied to each li elements.
     1225                 *
     1226                 * @since 2.8.0
     1227                 *
     1228                 * @param array  $css_class    An array of CSS classes to be applied to each list item.
     1229                 * @param object $page         Page data object.
     1230                 * @param int    $depth        Depth of page, used for padding.
     1231                 * @param array  $args         An array of arguments.
     1232                 * @param int    $current_page Page ID.
     1233                 */
    10691234                $css_class = implode( ' ', apply_filters( 'page_css_class', $css_class, $page, $depth, $args, $current_page ) );
    10701235
    10711236                if ( '' === $page->post_title )
    10721237                        $page->post_title = sprintf( __( '#%d (no title)' ), $page->ID );
    1073 
     1238               
    10741239                /** This filter is documented in wp-includes/post-template.php */
    10751240                $output .= $indent . '<li class="' . $css_class . '"><a href="' . get_permalink($page->ID) . '">' . $link_before . apply_filters( 'the_title', $page->post_title, $page->ID ) . $link_after . '</a>';
    10761241
    … …  
    11391304                if ( $page->ID == $args['selected'] )
    11401305                        $output .= ' selected="selected"';
    11411306                $output .= '>';
     1307                /**
     1308                 * Filters Page title of page list, retrieved by Walker::start_el(), used when creating HTML dropdown list of pages.
     1309                 *
     1310                 * @since 3.1.0
     1311                 *
     1312                 * @param string $page->post_title Page title.
     1313                 * @param object $page             Page data object.
     1314                 */
    11421315                $title = apply_filters( 'list_pages', $page->post_title, $page );
    11431316                $output .= $pad . esc_html( $title );
    11441317                $output .= "</option>\n";
    … …  
    11821355 * @param string|bool $text Optional, default is false. If string, then will be link text.
    11831356 * @return string HTML content.
    11841357 */
    1185 function wp_get_attachment_link( $id = 0, $size = 'thumbnail', $permalink = false, $icon = false, $text = false ) {
     1358function apply( $id = 0, $size = 'thumbnail', $permalink = false, $icon = false, $text = false ) {
    11861359        $id = intval( $id );
    11871360        $_post = get_post( $id );
    11881361
    … …  
    12041377        if ( trim( $link_text ) == '' )
    12051378                $link_text = $_post->post_title;
    12061379
     1380        /**
     1381         * Filters a retrieved attachment page link.
     1382         *
     1383         * @since 2.7.0
     1384         *
     1385         * @param int         $id        Post ID.
     1386         * @param string      $size      Size of an image, either array or string. Default is 'thumbnail'.
     1387         * @param bool        $permalink Whether to add permalink to image. Default is false.
     1388         * @param bool        $icon      Whether to include an icon. Default is false.
     1389         * @param string|bool $text      If string, then will be link text. Default is false.
     1390         */
    12071391        return apply_filters( 'wp_get_attachment_link', "<a href='$url'>$link_text</a>", $id, $size, $permalink, $icon, $text );
    12081392}
    12091393
    … …  
    12261410        // show the medium sized image representation of the attachment if available, and link to the raw file
    12271411        $p .= wp_get_attachment_link(0, 'medium', false);
    12281412        $p .= '</p>';
    1229         $p = apply_filters('prepend_attachment', $p);
     1413        /**
     1414         * Filter attachment markup to be prepended to post content.
     1415         *
     1416         * Function prepend_attachment() output attachment link with medium sized representation, wrapped with <p class="attachment"> attribute. Filter prepend_attachmnet filters this HTML output.
     1417         *
     1418         * @since 2.0.0
     1419         *
     1420         * @param string $p HTML output containing medium sized image representation of the attachment with a link to the raw file, wrapped with <p class="attachment"> attribute.
     1421         */
     1422        $p = apply_filters( 'prepend_attachment', $p );
    12301423
    12311424        return "$p\n$content";
    12321425}
    … …  
    12511444        <p><label for="' . $label . '">' . __( 'Password:' ) . ' <input name="post_password" id="' . $label . '" type="password" size="20" /></label> <input type="submit" name="Submit" value="' . esc_attr__( 'Submit' ) . '" /></p>
    12521445        </form>
    12531446        ';
     1447        /**
     1448         * Filter the output of protected post password form.
     1449         *
     1450         * @since 2.7.0
     1451         *
     1452         * @param string $output HTML output of protected post password form.
     1453         */
    12541454        return apply_filters( 'the_password_form', $output );
    12551455}
    12561456