[wp-trac] [WordPress Trac] #53392: add a filter for the arguments of `the_posts_navigation()`

[WordPress Trac]

#53392: add a filter for the arguments of `the_posts_navigation()`
-------------------------+------------------------------
 Reporter:  pbiron       |       Owner:  (none)
     Type:  enhancement  |      Status:  new
 Priority:  normal       |   Milestone:  Awaiting Review
Component:  General      |     Version:
 Severity:  normal       |  Resolution:
 Keywords:  has-patch    |     Focuses:
-------------------------+------------------------------
Description changed by pbiron:

Old description:

> It would be really helpful if there were a hook to filter the arguments
> passed to
> [https://developer.wordpress.org/reference/functions/the_posts_pagination/
> the_posts_pagination()] (and/or
> [https://developer.wordpress.org/reference/functions/get_the_posts_pagination/
> 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
> [https://developer.wordpress.org/reference/hooks/paginate_links_output/
> paginate_links_output] (and maybe
> [https://developer.wordpress.org/reference/hooks/navigation_markup_template/
> navigation_markup_template]).
>
> It would be **much** easier if the child theme could simply filter the
> `the_posts_navigation()` args and let core (and the parent theme) do all
> the rest.
>
> For example, suppose the parent theme does:
>
> {{{#!php
> 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
> [https://core.trac.wordpress.org/browser/trunk/src/wp-
> content/themes/twentyseventeen/search.php#L48 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:
>
> {{{#!php
> add_filter( 'the_posts_navigation_args',
> 'child_theme_the_posts_navigation_args' );
>
> public function child_theme_the_posts_navigation_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_navigation()`.

New description:

 It would be really helpful if there were a hook to filter the arguments
 passed to
 [https://developer.wordpress.org/reference/functions/the_posts_pagination/
 the_posts_pagination()] (and/or
 [https://developer.wordpress.org/reference/functions/get_the_posts_pagination/
 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
 [https://developer.wordpress.org/reference/hooks/paginate_links_output/
 paginate_links_output] (and maybe
 [https://developer.wordpress.org/reference/hooks/navigation_markup_template/
 navigation_markup_template]).

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

 For example, suppose the parent theme does:

 {{{#!php
 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
 [https://core.trac.wordpress.org/browser/trunk/src/wp-
 content/themes/twentyseventeen/search.php#L48 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:

 {{{#!php
 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()`.

--

-- 
Ticket URL: <https://core.trac.wordpress.org/ticket/53392#comment:4>
WordPress Trac <https://core.trac.wordpress.org/>
WordPress publishing platform