get_adjacent_post_link compliment to adjacent_post_link (or the_adjacent_post_link)

[jimisaacs]

I think I understand what paulschreiber meant.

adjacent_post_link is one of the only functions in link-template without a return equivalent.

I have ran into this problem in dozens of sites and themes I have developed. Most of the time I need to wrap the next and prev navigation in an overall element to be able to style it more appropriately. In order to do this correctly, I need to see if there are actually links that can and will print. Whether it iss one, the other, or both.

If so, print the navigation, if not, don't print the navigation.

All this would be solved by adding get_adjacent_post_link(). Then calling that from adjacent_post_link.

Without this function I have to write a duplicate function over and over and over, changing one thing in one line.

'echo' to 'return'

for instance this is an example of my most recent fix in a theme. Please pay no attention to the actual return value HTML, that is specific to the theme. What I am showing is what I as a developer am reduced to, if I don't want to rewrite the functions altogether. This would be a lot easier if there were just some returns.

/**
 * Gets the formatted post navigation for next and previous posts *
 * @return string HTML
 */
function mytheme_get_post_navigation( $format = '%link', $previous_text = '← prev', $next_text = 'next →', $in_same_cat = false, $excluded_categories = '' ) {
	// Sorry, no other way to do this without completely duplicating WordPress function
	ob_start(); previous_post_link( $format, $previous_text, $in_same_cat, $excluded_categories ); $prev = ob_get_clean();
	ob_start(); next_post_link( $format, $next_text, $in_same_cat, $excluded_categories ); $next = ob_get_clean();
	// only set html if there are actually links available
	return apply_filters( 'mytheme_post_navigation', ( $prev || $next ) ? '<nav class="post_navigation"><span class="alignleft previous">'.$prev.'</span> <span class="alignright next">'.$next.'</span></nav>' : '' );
}

[nacin]

Started in #2834

[GaryJ]

Adds get_adjacent_posts_link() as a copy of current adjacent_post_link() but as a return. Makes adjacent_post_link() into an echo of get_adjacent_post_link().

[GaryJ]

Came across this same issue with exactly the same scenario - knowing whether to echo out wrapper markup if one or both links are present.

Also, it seems odd that with the majority of existing functions offering return and echo versions, that the inconsistency for this function still exists.

[ocean90]

This is also handled in #17302