WordPress.org

Make WordPress Core

Ticket #29808: 29808.3.diff

File 29808.3.diff, 8.2 KB (added by obenland, 5 years ago)

Updated docs based on DrewAPicture's feedback.

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

     
    21882188}
    21892189
    21902190/**
     2191 * Return navigation to next/previous post when applicable.
     2192 *
     2193 * @since 4.1.0
     2194 *
     2195 * @param array $args {
     2196 *     Optional. Default post navigation arguments.
     2197 *
     2198 *     @type string $prev_text Anchor text to display in the previous post link.
     2199 *                             Default: `<span class="meta-nav">&larr;</span> %title`.
     2200 *     @type string $next_text Anchor text to display in the next post link.
     2201 *                             Default: `%title <span class="meta-nav">&rarr;</span>`.
     2202 * }
     2203 * @return string
     2204 */
     2205function get_the_post_navigation( $args = array() ) {
     2206        $args = wp_parse_args( $args, array(
     2207                'prev_text' => _x( '<span class="meta-nav">&larr;</span> %title', 'Previous post link' ),
     2208                'next_text' => _x( '%title <span class="meta-nav">&rarr;</span>', 'Next post link' ),
     2209        ) );
     2210
     2211        $navigation = '';
     2212        $previous   = get_previous_post_link( '<div class="nav-previous">%link</div>', $args['prev_text'] );
     2213        $next       = get_next_post_link( '<div class="nav-next">%link</div>', $args['next_text'] );
     2214
     2215        // Only add markup if there's somewhere to navigate to.
     2216        if ( $next || $previous ) {
     2217                $navigation = _navigation_markup( $next . $previous, 'post-navigation', __( 'Post navigation' ) );
     2218        }
     2219
     2220        return $navigation;
     2221}
     2222
     2223/**
     2224 * Display navigation to next/previous post when applicable.
     2225 *
     2226 * @since 4.1.0
     2227 *
     2228 * @param array $args {
     2229 *     Optional. Default post navigation arguments.
     2230 *
     2231 *     @type string $prev_text Anchor text to display in the previous post link.
     2232 *                             Default: `<span class="meta-nav">&larr;</span> %title`.
     2233 *     @type string $next_text Anchor text to display in the next post link.
     2234 *                             Default: `%title <span class="meta-nav">&rarr;</span>`.
     2235 * }
     2236 */
     2237function the_post_navigation( $args = array() ) {
     2238        echo get_the_post_navigation( $args );
     2239}
     2240
     2241/**
     2242 * Return navigation to next/previous set of posts when applicable.
     2243 *
     2244 * @since 4.1.0
     2245 *
     2246 * @global WP_Query $wp_query WordPress Query object.
     2247 * @param array $args {
     2248 *     Optional. Default paging navigation arguments.
     2249 *
     2250 *     @type string $prev_text Anchor text to display in the previous posts link.
     2251 *                             Default: `<span class="meta-nav">&larr;</span> Older posts`.
     2252 *     @type string $next_text Anchor text to display in the next posts link.
     2253 *                             Default: `Newer posts <span class="meta-nav">&rarr;</span>`.
     2254 * }
     2255 * @return string
     2256 */
     2257function get_the_paging_navigation( $args = array() ) {
     2258        $navigation = '';
     2259
     2260        // Don't print empty markup if there's only one page.
     2261        if ( $GLOBALS['wp_query']->max_num_pages > 1 ) {
     2262                $args = wp_parse_args( $args, array(
     2263                        'prev_text' => __( '<span class="meta-nav">&larr;</span> Older posts' ),
     2264                        'next_text' => __( 'Newer posts <span class="meta-nav">&rarr;</span>' ),
     2265                ) );
     2266
     2267                $next_link = get_next_posts_link( $args['prev_text'] );
     2268                $prev_link = get_previous_posts_link( $args['next_text'] );
     2269
     2270                if ( $next_link ) {
     2271                        $navigation .= '<div class="nav-previous">' . $next_link . '</div>';
     2272                }
     2273
     2274                if ( $prev_link ) {
     2275                        $navigation .= '<div class="nav-next">' . $prev_link . '</div>';
     2276                }
     2277
     2278                $navigation = _navigation_markup( $navigation );
     2279        }
     2280
     2281        return $navigation;
     2282}
     2283
     2284/**
     2285 * Display navigation to next/previous set of posts when applicable.
     2286 *
     2287 * @since 4.1.0
     2288 *
     2289 * @param array $args {
     2290 *     Optional. Default paging navigation arguments.
     2291 *
     2292 *     @type string $prev_text Anchor text to display in the previous posts link.
     2293 *                             Default: `<span class="meta-nav">&larr;</span> Older posts`.
     2294 *     @type string $next_text Anchor text to display in the next posts link.
     2295 *                             Default: `Newer posts <span class="meta-nav">&rarr;</span>`.
     2296 * }
     2297 */
     2298function the_paging_navigation( $args = array() ) {
     2299        echo get_the_paging_navigation( $args );
     2300}
     2301
     2302/**
     2303 * Return a paginated navigation to next/previous set of posts,
     2304 * when applicable.
     2305 *
     2306 * @since 4.1.0
     2307 *
     2308 * @param array $args {
     2309 *     Optional. Default pagination arguments.
     2310 *
     2311 *     @type string $base               URL to be used to create the paginated links.
     2312 *                                      Example: `http://example.com/all_posts.php%_%`
     2313 *                                      The `%_%` is required and will be replaced by the contents of the
     2314 *                                      'format' argument.
     2315 *                                      Default: Current page number link with appended `%_%`.
     2316 *     @type string $format             Used to replace the page number. Example: `?page=%#%`
     2317 *                                      The `%#%` is required and will be replaced with the page number.
     2318 *                                      Default: Current permalink format with appended `%#%`.
     2319 *     @type int    $total              The total amount of pages. Default: Value of 'max_num_pages' of current query.
     2320 *     @type int    $current            The current page number. Default: Value of 'paged' query var.
     2321 *     @type bool   $prev_next          Whether to include previous and next links. Default: true.
     2322 *     @type string $prev_text          Anchor text to display in the previous posts link. Default: `&larr; Previous`.
     2323 *     @type string $next_text          Anchor text to display in the next posts link. Default: `Next &rarr;`.
     2324 *     @type bool   $show_all           Whether to show all pages.
     2325 *                                      Default: false, shows short list of the pages near the current page.
     2326 *     @type int    $end_size           Amount of numbers on either the start and the end list edges. Default: 1.
     2327 *     @type int    $mid_size           Amount of numbers to either side of current page but not including current page.
     2328 *                                      Default: 1.
     2329 *     @type array  $add_args           Query vars to be added to the links. Accepts an associative array of arguments.
     2330 *                                      Default: Empty array.
     2331 *     @type string $before_page_number Text to prepend to the anchor text. Default: Empty string.
     2332 *     @type string $after_page_number  Text to append to the anchor text. Default: Empty string.
     2333 * }
     2334 * @return string
     2335 */
     2336function get_the_pagination( $args = array() ) {
     2337        $navigation = '';
     2338
     2339        // Don't print empty markup if there's only one page.
     2340        if ( $GLOBALS['wp_query']->max_num_pages > 1 ) {
     2341                $args = wp_parse_args( $args, array(
     2342                        'mid_size'  => 1,
     2343                        'prev_text' => __( '&larr; Previous' ),
     2344                        'next_text' => __( 'Next &rarr;' ),
     2345                ) );
     2346                // Make sure we get plain links, so we can work with it.
     2347                $args['type'] = 'plain';
     2348
     2349                // Set up paginated links.
     2350                $links = paginate_links( $args );
     2351
     2352                if ( $links ) {
     2353                        $navigation = _navigation_markup( $links, 'pagination' );
     2354                }
     2355        }
     2356
     2357        return $navigation;
     2358}
     2359
     2360/**
     2361 * Display a paginated navigation to next/previous set of posts,
     2362 * when applicable.
     2363 *
     2364 * @since 4.1.0
     2365 *
     2366 * @param array $args {@see get_the_pagination()} for available arguments.
     2367 */
     2368function the_pagination( $args = array() ) {
     2369        echo get_the_pagination( $args );
     2370}
     2371
     2372/**
     2373 * Wraps passed links in navigational markup.
     2374 *
     2375 * @since 4.1.0
     2376 * @access private
     2377 *
     2378 * @param string $links              Navigational links.
     2379 * @param string $class              Optional. Custom class for nav element. Default: 'paging-navigation'.
     2380 * @param string $screen_reader_text Optional. Screen reader text for nav element. Default: 'Posts navigation'.
     2381 * @return string
     2382 */
     2383function _navigation_markup( $links, $class = 'paging-navigation', $screen_reader_text = '' ) {
     2384        if ( empty( $screen_reader_text ) ) {
     2385                $screen_reader_text = __( 'Posts navigation' );
     2386        }
     2387
     2388        $template = '
     2389        <nav class="navigation %1$s" role="navigation">
     2390                <h1 class="screen-reader-text">%2$s</h1>
     2391                <div class="nav-links">%3$s</div>
     2392        </nav>';
     2393
     2394        return sprintf( $template, sanitize_html_class( $class ), esc_html( $screen_reader_text ), $links );
     2395}
     2396
     2397/**
    21912398 * Retrieve comments page number link.
    21922399 *
    21932400 * @since 2.7.0