WordPress at a glance

get_the_post_navigation() WP 4.1.0

Gets the navigation links (HTML) to the next and previous posts. Uses on a single post page: is_singular().

You can use it for example, for navigation between attachments (attached images).

Up to version 4.1. to output links to the previous/next post, you had to use the get_next_post_link() and get_previous_post_link() functions. This function is a wrapper for these functions.

To immediately display the result on the screen, use the_post_navigation().

  • Since 4.4.0 Introduced the in_same_term, excluded_terms, and taxonomy arguments.
Is the basis for: the_post_navigation()

No Hooks.

Return

String. HTML Markup for post links.

Usage

get_the_post_navigation( $args );
$args(array)

Default empty array.

  • $prev_text (string)
    Anchor text to display in the previous post link.
    Default: '%title'

  • $next_text (string)
    Anchor text to display in the next post link.
    Default: '%title'

  • $in_same_term (true/false)
    Whether link should be in a same taxonomy term.
    Default: false

  • $excluded_terms (array/string)
    Array or comma-separated list of excluded term IDs.
    Default: ''

  • $taxonomy (string)
    Taxonomy, if $in_same_term is true.
    Default: 'category'

  • $screen_reader_text (string)
    Screen reader text for nav element.
    Default: 'Post navigation'

Default: post navigation arguments

Examples

#1 Navigation links between posts

Let's output links to the next and previous entries (posts) on a separate page of is_single() type.

<?php
// next/prev. post
$post_nav = get_the_post_navigation( array(
	'prev_text' => '<span class="meta-nav" aria-hidden="true">Backward</span> ' .
		'<span class="screen-reader-text">Previous entry</span> ' .
		'<span class="post-title">%title</span>',
	'next_text' => '<span class="meta-nav" aria-hidden="true">Further</span> ' .
		'<span class="screen-reader-text">Next entry</span> ' .
		'<span class="post-title">%title</span>',
) );

echo $post_nav;
?>

As a result, we get such HTML code:

<nav class="navigation post-navigation" role="navigation">
	<h2 class="screen-reader-text">Posts navigation</h2>
	<div class="nav-links">
		<div class="nav-previous">
			<a href="//wptest.ru/post8/" rel="prev">
				<span class="meta-nav" aria-hidden="true">Backward</span>
				<span class="screen-reader-text">Previous entry</span>
				<span class="post-title">Some Post Title</span>
			</a>
		</div>
		<div class="nav-next">
			<a href="//wptest.ru/post10/" rel="next">
				<span class="meta-nav" aria-hidden="true">Further</span>
				<span class="screen-reader-text">Next entry</span>
				<span class="post-title">Hello World!</span>
			</a>
		</div>
	</div>
</nav>

Code of get_the_post_navigation: wp-includes/link-template.php VER 4.9.8

<?php
function get_the_post_navigation( $args = array() ) {
	$args = wp_parse_args( $args, array(
		'prev_text'          => '%title',
		'next_text'          => '%title',
		'in_same_term'       => false,
		'excluded_terms'     => '',
		'taxonomy'           => 'category',
		'screen_reader_text' => __( 'Post navigation' ),
	) );

	$navigation = '';

	$previous = get_previous_post_link(
		'<div class="nav-previous">%link</div>',
		$args['prev_text'],
		$args['in_same_term'],
		$args['excluded_terms'],
		$args['taxonomy']
	);

	$next = get_next_post_link(
		'<div class="nav-next">%link</div>',
		$args['next_text'],
		$args['in_same_term'],
		$args['excluded_terms'],
		$args['taxonomy']
	);

	// Only add markup if there's somewhere to navigate to.
	if ( $previous || $next ) {
		$navigation = _navigation_markup( $previous . $next, 'post-navigation', $args['screen_reader_text'] );
	}

	return $navigation;
}

Related Functions

From tag: adjacent links (related links)

More from tag: Navigation pagination

More from category: Navigation

No comments
    Hello, !     Log In . Register