get_the_post_navigation

Retrieves the navigation to next/previous post, when applicable.

Description

(string) get_the_post_navigation( (array) $args = array() ); 

Returns (string)

Markup for post links.

Parameters (1)

0. $args — Optional. (array) => array()
Default post navigation arguments. Default empty array.

Options

  • prev_text (string) => '%title'

    Anchor text to display in the previous post link.

  • next_text (string) => '%title'

    Anchor text to display in the next post link.

  • in_same_term (bool) => false

    Whether link should be in a same taxonomy term.

  • excluded_terms (array|string) => ''

    Array or comma-separated list of excluded term IDs.

  • taxonomy (string) => 'category'

    Taxonomy, if $in_same_term is true.

array(

    /**
     * Anchor text to display in the previous post link.
     *
     * @type string
     * @default '%title'
     */
    'prev_text' => '%title',

    /**
     * Anchor text to display in the next post link.
     *
     * @type string
     * @default '%title'
     */
    'next_text' => '%title',

    /**
     * Whether link should be in a same taxonomy term.
     *
     * @type bool
     * @default false
     */
    'in_same_term' => false,

    /**
     * Array or comma-separated list of excluded term IDs.
     *
     * @type array|string
     * @default ''
     */
    'excluded_terms' => '',

    /**
     * Taxonomy, if `$in_same_term` is true.
     *
     * @type string
     * @default 'category'
     */
    'taxonomy' => 'category'
);        


Usage

  1. if ( !function_exists( 'get_the_post_navigation' ) ) { 
  2. require_once ABSPATH . WPINC . '/link-template.php'; 
  3.  
  4. // Optional. Default post navigation arguments. Default empty array. 
  5. $args = array( 
  6. 'prev_text' => '%title', 
  7. 'next_text' => '%title', 
  8. 'in_same_term' => false, 
  9. 'excluded_terms' => '', 
  10. 'taxonomy' => 'category' 
  11. ); 
  12.  
  13. // NOTICE! Understand what this does before running. 
  14. $result = get_the_post_navigation($args); 
  15.  

Defined (1)

The function is defined in the following location(s).

/wp-includes/link-template.php  
  1. function get_the_post_navigation( $args = array() ) { 
  2. $args = wp_parse_args( $args, array( 
  3. 'prev_text' => '%title',  
  4. 'next_text' => '%title',  
  5. 'in_same_term' => false,  
  6. 'excluded_terms' => '',  
  7. 'taxonomy' => 'category',  
  8. 'screen_reader_text' => __( 'Post navigation' ),  
  9. ) ); 
  10.  
  11. $navigation = ''; 
  12.  
  13. $previous = get_previous_post_link
  14. '<div class="nav-previous">%link</div>',  
  15. $args['prev_text'],  
  16. $args['in_same_term'],  
  17. $args['excluded_terms'],  
  18. $args['taxonomy'] 
  19. ); 
  20.  
  21. $next = get_next_post_link
  22. '<div class="nav-next">%link</div>',  
  23. $args['next_text'],  
  24. $args['in_same_term'],  
  25. $args['excluded_terms'],  
  26. $args['taxonomy'] 
  27. ); 
  28.  
  29. // Only add markup if there's somewhere to navigate to. 
  30. if ( $previous || $next ) { 
  31. $navigation = _navigation_markup( $previous . $next, 'post-navigation', $args['screen_reader_text'] ); 
  32.  
  33. return $navigation;