Customise link text in paginate_links() and paginate_comments_links() for accessibility

[grahamarmfield]

paginate_links() produces a list of numbered pagination links in archive, search, etc. paginate_comments_links() does the same for paged comments.

Currently there appears to be no way of tailoring the link text to include context as well as the page number. A plain list of numbered links may not mean much for screen reader users who are using the screen reader's 'List Links' facility.

For example, I would like to add <span class="visuallyhidden">Page </span> before the page number to provide context for the links for users of screen readers. My stylesheet will hide the extra text from sighted users, but it will still be available to AT (assistive technology).

I suggest the addition of two new parameters: before_link and after_link for this purpose. The defaults for each parameter would be none.

[pauldewouters]

@grahamarmfield

This is a first attempt at adding the before_page_link and after_page_link arguments to paginate_links()
I'll add a separate patch for paginate_comments_links()

[grahamarmfield]

Replying to pauldewouters:

@grahamarmfield

This is a first attempt at adding the before_page_link and after_page_link arguments to paginate_links()
I'll add a separate patch for paginate_comments_links()

I have now tested the first patch on paginate_links() and unfortunately the patch doesn't quite do what I wanted it to do.

The before and after text is added, but outside the actual link. For example I've set the before text to 'before ' and the after text to ' after' and the end result for each link is:

before <a class='page-numbers' href='http://url/?page_id=18&#038;paged=3'>3</a> after

In order to add the extra context text for screen readers the extra text needs to be inside the link - like this:

<a class='page-numbers' href='http://url/?page_id=18&#038;paged=3'>before 3 after</a>

Looking at the patch I think that should be fairly easy to rectify. I currently don't have the knowledge to create new patches (still learning) but it would be great if someone could just modify that first patch so I could give it another try.

So far I haven't done any testing on the comments pagination patch. I'll have to work out how to test that one.

[grahamarmfield]

OK, patch created which incorporates some of the changes made in the first patch but then changes the output to how it needs to be.

I have incorporated both the previous patches into this one patch - ie the comments pagination as well as the posts pagination.

These have been tested in my local dev area using a custom theme of my own with no plugins activated. DEBUG is set to true in the config file and there are no resultant PHP errors.

Hope this can be progressed as it can improve the accessibility of the pagination functionality.

[grahamarmfield]

Patch to combine the previous two patches and get the output into the desired format.

[grahamarmfield]

I have tested this and it seems to work. I can successfully add screen reader only text into the link which is the enhancement I originally wanted.

Screen reader users now get better feedback on the meaning of the links.

[pauldewouters]

cool, wasn't sure if it needed 2 different patches or not. would be nice to get some feedback

[grahamarmfield]

Replying to pauldewouters:

cool, wasn't sure if it needed 2 different patches or not. would be nice to get some feedback

Thought to combine them together so that both situations were in step - but happy to split if required.

Keen to get it committed as I want to start using it within a theme.

[GrahamArmfield]

Update of patch to remove # from name. Revised patch tested OK.

[johnbillion]

I don't see any issues with 24709.1.patch​. I contemplated a filter applied to the page number instead but that would complicate implementation within a theme.

Two small things:

• The arguments should be named before_page_number and after_page_number.
• The arguments need some inline docs.

[GrahamArmfield]

Revised patch to incorporate argument name changes and inline documentation changes asked for by @johnbillion

[GrahamArmfield]

Replying to johnbillion:

I don't see any issues with 24709.1.patch​. I contemplated a filter applied to the page number instead but that would complicate implementation within a theme.

Good point

Two small things:

• The arguments should be named before_page_number and after_page_number.
• The arguments need some inline docs.

Revised patch submitted to address both of those issues.

[johnbillion]

In 27600:

Introduce before_page_number and after_page_number arguments for paginate_links(). Fixes #24709. Props grahamarmfield.

[johnbillion]

Decided to make a call on this and put it in. Any objections, please re-open.

[GregLone]

Hello.

Just a thought: for better i18n, shouldn't $before_page_number . number_format_i18n( $n ) . $after_page_number become something like sprintf( $page_number_text, number_format_i18n( $n ) )?
$page_number_text should always contain %s of course.

I think it will help in many cases (with rtl for example).

[GrahamArmfield]

#30174 was marked as a duplicate.