Make WordPress Core

Changeset 30065


Ignore:
Timestamp:
10/28/2014 07:38:41 PM (9 years ago)
Author:
johnbillion
Message:

Introduce some new template functions for navigation:

  • get_the_post_navigation() and the_post_navigation() for navigation to the next and previous post.
  • get_the_posts_navigation() and the_posts_navigation()` for navigation to the next and previous page of posts.
  • get_the_pagination() and the_pagination() for paginated navigation between pages of posts. Uses paginate_links().

This reduces the need for themes to define their own sets of navigation functions.

Fixes #29808.
Props obenland.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/src/wp-includes/link-template.php

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