add a filter for the arguments of `the_posts_pagination()`

[pbiron]

It would be really helpful if there were a hook to filter the arguments passed to ​the_posts_pagination() (and/or ​get_the_posts_pagination()).

The most common case I come across where this new filter would be helpful is when creating a child theme, tho there are undoubtedly others. The parent theme has a template that calls the_posts_pagination() where I like everything about the template except for the arguments it passes to the_posts_pagination().

Usually what I do in that case is add a copy of the template to my child theme and change just the arguments passed to the_posts_pagination(). That's certainly not ideal because of the possibility of the parent theme releasing a new version that changes the template in question and then the child theme needs to have multiple "copies" of the template and load the one that is based on the version of the parent theme active on the site :-(

The other option, I guess (it's so complicated, I've never actually done it), is for the child theme to hook into
​paginate_links_output (and maybe ​navigation_markup_template).

It would be much easier if the child theme could simply filter the the_posts_pagination() args and let core (and the parent theme) do all the rest.

For example, suppose the parent theme does:

the_posts_pagination(
    array(
       'prev_text' => parent_theme_get_svg( 'prev' ),
       'next_text' => parent_theme_get_svg( 'next' ),
    )
);

(For a real world example, see twentynineteen's search.php).

Rather than use the SVG's from the parent theme, the child theme just wants to use plain "Next", "Previous" text so that it can style those links like next/previous buttons it uses in other contexts that have nothing to do with post navigation.

A new filter would allow the child theme to simply do:

add_filter( 'the_posts_pagination_args', 'child_theme_the_posts_pagination_args' );

public function child_theme_the_posts_pagination_args( $args ) {
    $args['prev_text'] = __( 'Previous', 'child-theme' );
    $args['next_text'] = __( 'Next', 'child-theme' );

    return $args;
}

and not have to copy the parent theme's template into the child theme just so that it can change the args passed to the_posts_pagination().

[joyously]

Did you intend that your example mixed the_posts_navigation with the_posts_pagination?
They call the same underlying functions, but are very different.

[pbiron]

no, I didn't, thanx for catching that. Let me update the patch.

[pbiron]

corrects the name of the new filter to reflect which args are being filtered.

[joyously]

Ah, I see now. It looks like you missed one. (and the title of the ticket has navigation)

It would be much easier if the child theme could simply filter the the_posts_navigation() args and let core

[pbiron]

Thanx again @joyously :-)

Patch updated to use the correct new filter name and the example in the ticket Description has been updated accordingly.

It might be good to also add new the_posts_navigation and the_post_navigation filters, but for now I'm going to leave the scope of this ticket as originally opened (since that's my only immediate need). Have no objection if others think it'd be good to expand it and would be happy to update the patch accordingly.

[sabernhardt]

Related: #44419

[pbiron]

Thanx @davidbaumwald.

Would you like me to refresh the patch, to update the @since tag in the filter's DocBlock? Or can you do that as part of the commit?

[davidbaumwald]

@pbiron If you're looking for something to do. Otherwise, I can just change it myself ;)

[pbiron]

refresh the patch to update the @since tag in the DocBlock of the new filter

[pbiron]

ask an ye shall receive: 53392.2.diff​ :-)

[audrasjb]

Combines 53392.1.diff and 53392.2.diff :-)

[pbiron]

thanx @audrasjb ... user headspace error on my part when creating the revised patch

[robinwpdeveloper]

Latest patch (53392.3.diff) looks good to me.

[davidbaumwald]

Messed up the ticket number in the commit, but this was fixed in changeset https://core.trac.wordpress.org/changeset/54144.

General: Add a new filter for the_posts_pagination_args.

Props pbiron, joyously, audrasjb, robinwpdeveloper.
Fixes 53392.

Also flagging this for a small call-out on the Misc Dev Note.

[pbiron]

I'll draft some text for #53392 for the Misc Dev Note.

[pbiron]

The DevNote for this is included in ​Miscellaneous Core changes for WordPress 6.1