Make WordPress Core

Opened 3 years ago

Closed 21 months ago

Last modified 20 months ago

#53392 closed enhancement (fixed)

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

Reported by: pbiron's profile pbiron Owned by: davidbaumwald's profile davidbaumwald
Milestone: 6.1 Priority: normal
Severity: normal Version:
Component: General Keywords: has-patch commit has-dev-note
Focuses: docs Cc:

Description (last modified by 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:

       '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().

Attachments (4)

53392.diff (1.4 KB) - added by pbiron 3 years ago.
53392.1.diff (1.4 KB) - added by pbiron 3 years ago.
corrects the name of the new filter to reflect which args are being filtered.
53392.2.diff (869 bytes) - added by pbiron 22 months ago.
refresh the patch to update the @since tag in the DocBlock of the new filter
53392.3.diff (1.1 KB) - added by audrasjb 22 months ago.
Combines 53392.1.diff and 53392.2.diff :-)

Download all attachments as: .zip

Change History (22)

3 years ago

#1 @pbiron
3 years ago

  • Keywords has-patch added

#2 @joyously
3 years ago

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

#3 @pbiron
3 years ago

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

3 years ago

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

#4 @pbiron
3 years ago

  • Description modified (diff)

#5 @joyously
3 years ago

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

#6 @pbiron
3 years ago

  • Description modified (diff)
  • Summary changed from add a filter for the arguments of `the_posts_navigation()` to add a filter for the arguments of `the_posts_pagination()`

#7 @pbiron
3 years ago

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.

This ticket was mentioned in Slack in #core by pbiron. View the logs.

22 months ago

#10 @davidbaumwald
22 months ago

  • Focuses docs added
  • Keywords commit added
  • Milestone changed from Awaiting Review to 6.1
  • Owner set to davidbaumwald
  • Status changed from new to reviewing

#11 @pbiron
22 months ago

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?

Last edited 22 months ago by pbiron (previous) (diff)

#12 @davidbaumwald
22 months ago

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

22 months ago

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

#13 @pbiron
22 months ago

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

22 months ago

Combines 53392.1.diff and 53392.2.diff :-)

#14 @pbiron
22 months ago

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

#15 @robinwpdeveloper
21 months ago

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

#16 @davidbaumwald
21 months ago

  • Keywords needs-dev-note added
  • Resolution set to fixed
  • Status changed from reviewing to closed

Messed up the ticket number in the commit, but this was fixed in changeset

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.

#17 @pbiron
20 months ago

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

#18 @pbiron
20 months ago

  • Keywords has-dev-note added; needs-dev-note removed

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

Note: See TracTickets for help on using tickets.