WordPress.org

Make WordPress Core

Opened 6 weeks ago

Last modified 6 weeks ago

#53392 new enhancement

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

Reported by: pbiron Owned by:
Milestone: Awaiting Review Priority: normal
Severity: normal Version:
Component: General Keywords: has-patch
Focuses: 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:

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

Attachments (2)

53392.diff (1.4 KB) - added by pbiron 6 weeks ago.
53392.1.diff (1.4 KB) - added by pbiron 6 weeks ago.
corrects the name of the new filter to reflect which args are being filtered.

Download all attachments as: .zip

Change History (10)

@pbiron
6 weeks ago

#1 @pbiron
6 weeks ago

  • Keywords has-patch added

#2 @joyously
6 weeks 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
6 weeks ago

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

@pbiron
6 weeks ago

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

#4 @pbiron
6 weeks ago

  • Description modified (diff)

#5 @joyously
6 weeks 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
6 weeks 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
6 weeks 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.

Note: See TracTickets for help on using tickets.