From f08525846acca6e78ab8b266c577a400dc4f3ebf Mon Sep 17 00:00:00 2001 From: John Blackbourn Date: Tue, 28 Oct 2014 19:38:41 +0000 Subject: [PATCH] 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. git-svn-id: https://develop.svn.wordpress.org/trunk@30065 602fd350-edb4-49c9-b593-d223f7449a82 --- src/wp-includes/link-template.php | 194 ++++++++++++++++++++++++++++++ 1 file changed, 194 insertions(+) diff --git a/src/wp-includes/link-template.php b/src/wp-includes/link-template.php index 13a74aa92a..4fe36d10a9 100644 --- a/src/wp-includes/link-template.php +++ b/src/wp-includes/link-template.php @@ -2187,6 +2187,200 @@ function posts_nav_link( $sep = '', $prelabel = '', $nxtlabel = '' ) { echo get_posts_nav_link($args); } +/** + * Return navigation to next/previous post when applicable. + * + * @since 4.1.0 + * + * @param array $args { + * Optional. Default post navigation arguments. + * + * @type string $prev_text Anchor text to display in the previous post link. + * Default: ` %title`. + * @type string $next_text Anchor text to display in the next post link. + * Default: `%title `. + * } + * @return string Markup for post links. + */ +function get_the_post_navigation( $args = array() ) { + $args = wp_parse_args( $args, array( + 'prev_text' => _x( ' %title', 'Previous post link' ), + 'next_text' => _x( '%title ', 'Next post link' ), + ) ); + + $navigation = ''; + $previous = get_previous_post_link( '', $args['prev_text'] ); + $next = get_next_post_link( '', $args['next_text'] ); + + // Only add markup if there's somewhere to navigate to. + if ( $next || $previous ) { + $navigation = _navigation_markup( $next . $previous, 'post-navigation', __( 'Post navigation' ) ); + } + + return $navigation; +} + +/** + * Display navigation to next/previous post when applicable. + * + * @since 4.1.0 + * + * @param array $args See {@see get_the_post_navigation()} for available arguments. + */ +function the_post_navigation( $args = array() ) { + echo get_the_post_navigation( $args ); +} + +/** + * Return navigation to next/previous set of posts when applicable. + * + * @since 4.1.0 + * + * @global WP_Query $wp_query WordPress Query object. + * + * @param array $args { + * Optional. Default paging navigation arguments. + * + * @type string $prev_text Anchor text to display in the previous posts link. + * Default: ` Older posts`. + * @type string $next_text Anchor text to display in the next posts link. + * Default: `Newer posts `. + * } + * @return string Markup for paging links. + */ +function get_the_posts_navigation( $args = array() ) { + $navigation = ''; + + // Don't print empty markup if there's only one page. + if ( $GLOBALS['wp_query']->max_num_pages > 1 ) { + $args = wp_parse_args( $args, array( + 'prev_text' => __( ' Older posts' ), + 'next_text' => __( 'Newer posts ' ), + ) ); + + $next_link = get_next_posts_link( $args['prev_text'] ); + $prev_link = get_previous_posts_link( $args['next_text'] ); + + if ( $next_link ) { + $navigation .= ''; + } + + if ( $prev_link ) { + $navigation .= ''; + } + + $navigation = _navigation_markup( $navigation ); + } + + return $navigation; +} + +/** + * Display navigation to next/previous set of posts when applicable. + * + * @since 4.1.0 + * + * @param array $args See {@see get_the_posts_navigation()} for available arguments. + */ +function the_posts_navigation( $args = array() ) { + echo get_the_posts_navigation( $args ); +} + +/** + * Return a paginated navigation to next/previous set of posts, + * when applicable. + * + * @since 4.1.0 + * + * @param array $args { + * Optional. Default pagination arguments. + * + * @type string $base URL to be used to create the paginated links. + * Example: `http://example.com/all_posts.php%_%` + * The `%_%` is required and will be replaced by the contents of the + * 'format' argument. + * Default: Current page number link with appended `%_%`. + * @type string $format Used to replace the page number. Example: `?page=%#%` + * The `%#%` is required and will be replaced with the page number. + * Default: Current permalink format with appended `%#%`. + * @type int $total The total amount of pages. Default: Value of 'max_num_pages' of current query. + * @type int $current The current page number. Default: Value of 'paged' query var. + * @type bool $prev_next Whether to include previous and next links. Default: true. + * @type string $prev_text Anchor text to display in the previous posts link. Default: `← Previous`. + * @type string $next_text Anchor text to display in the next posts link. Default: `Next →`. + * @type bool $show_all Whether to show all pages. + * Default: false, shows short list of the pages near the current page. + * @type int $end_size Amount of numbers on either the start and the end list edges. Default: 1. + * @type int $mid_size Amount of numbers to either side of current page but not including current page. + * Default: 1. + * @type array $add_args Query vars to be added to the links. Accepts an associative array of arguments. + * Default: Empty array. + * @type string $before_page_number Text to prepend to the anchor text. Default: Empty string. + * @type string $after_page_number Text to append to the anchor text. Default: Empty string. + * } + * @return string Markup for pagination links. + */ +function get_the_pagination( $args = array() ) { + $navigation = ''; + + // Don't print empty markup if there's only one page. + if ( $GLOBALS['wp_query']->max_num_pages > 1 ) { + $args = wp_parse_args( $args, array( + 'mid_size' => 1, + 'prev_text' => __( '← Previous' ), + 'next_text' => __( 'Next →' ), + ) ); + // Make sure we get plain links, so we can work with it. + $args['type'] = 'plain'; + + // Set up paginated links. + $links = paginate_links( $args ); + + if ( $links ) { + $navigation = _navigation_markup( $links, 'pagination' ); + } + } + + return $navigation; +} + +/** + * Display a paginated navigation to next/previous set of posts, + * when applicable. + * + * @since 4.1.0 + * + * @param array $args See {@see get_the_pagination()} for available arguments. + */ +function the_pagination( $args = array() ) { + echo get_the_pagination( $args ); +} + +/** + * Wraps passed links in navigational markup. + * + * @since 4.1.0 + * @access private + * + * @param string $links Navigational links. + * @param string $class Optional. Custom class for nav element. Default: 'paging-navigation'. + * @param string $screen_reader_text Optional. Screen reader text for nav element. Default: 'Posts navigation'. + * @return string Navigation template tag. + */ +function _navigation_markup( $links, $class = 'paging-navigation', $screen_reader_text = '' ) { + if ( empty( $screen_reader_text ) ) { + $screen_reader_text = __( 'Posts navigation' ); + } + + $template = ' + '; + + return sprintf( $template, sanitize_html_class( $class ), esc_html( $screen_reader_text ), $links ); +} + /** * Retrieve comments page number link. *