Refactor the admin paginator customizations to make them reuseable

[Vlada Macek]

For large page counts I miss a standard way to display only interesting blocks of page links in the paginator. I guess Django should include one.

What do you think about integrating my implementation to django.core.paginator.Page drafted below?
Template example at the bottom.

from django.core.paginator import Paginator, Page

class EllipsisPaginator(Paginator):
    def __init__(self, *args, **kwargs):
        # number of page links to always display after the first page
        self.start_wing = kwargs.pop('start_wing', 1)
        # number of page links to always display around the current page
        self.island_wings = kwargs.pop('island_wings', 2)
        # number of page links to always display before the last page
        self.end_wing = kwargs.pop('end_wing', 1)

        super(EllipsisPaginator, self).__init__(*args, **kwargs)

    def _get_page(self, *args, **kwargs):
        return EllipsisPage(*args, **kwargs)


class EllipsisPage(Page):
    def pages_with_ellipsis(self):
        """
        Generates the list of page numbers for large page counts.
        Yields '...' where the range of links should be omitted.

        >>> pp = EllipsisPaginator(object_list=range(38), per_page=3)
        >>> list(pp.page(1).pages_with_ellipsis())
        [1, 2, 3, '...', 12, 13]
        >>> list(pp.page(2).pages_with_ellipsis())
        [1, 2, 3, 4, '...', 12, 13]
        >>> list(pp.page(3).pages_with_ellipsis())
        [1, 2, 3, 4, 5, '...', 12, 13]
        >>> list(pp.page(4).pages_with_ellipsis())
        [1, 2, 3, 4, 5, 6, '...', 12, 13]
        >>> list(pp.page(5).pages_with_ellipsis())
        [1, 2, 3, 4, 5, 6, 7, '...', 12, 13]
        >>> list(pp.page(6).pages_with_ellipsis())
        [1, 2, 3, 4, 5, 6, 7, 8, '...', 12, 13]
        >>> list(pp.page(7).pages_with_ellipsis())
        [1, 2, '...', 5, 6, 7, 8, 9, '...', 12, 13]
        >>> list(pp.page(8).pages_with_ellipsis())
        [1, 2, '...', 6, 7, 8, 9, 10, 11, 12, 13]
        >>> list(pp.page(9).pages_with_ellipsis())
        [1, 2, '...', 7, 8, 9, 10, 11, 12, 13]
        >>> list(pp.page(10).pages_with_ellipsis())
        [1, 2, '...', 8, 9, 10, 11, 12, 13]
        >>> list(pp.page(11).pages_with_ellipsis())
        [1, 2, '...', 9, 10, 11, 12, 13]
        >>> list(pp.page(12).pages_with_ellipsis())
        [1, 2, '...', 10, 11, 12, 13]
        >>> list(pp.page(13).pages_with_ellipsis())
        [1, 2, '...', 11, 12, 13]
        """
        num = 1

        end_of_start_wing = min(self.paginator.num_pages, self.paginator.start_wing+1)

        for num in xrange(1, end_of_start_wing+1):
            yield num

        island_start = self.number - self.paginator.island_wings

        if num < island_start-2:
            yield '...'
            num = island_start
        else:
            num += 1

        island_end = min(self.paginator.num_pages, self.number + self.paginator.island_wings)

        for num in xrange(num, island_end+1):
            yield num

        start_of_end_wing = self.paginator.num_pages - self.paginator.end_wing

        if num < start_of_end_wing-2:
            yield '...'
            num = start_of_end_wing
        else:
            num += 1

        for num in xrange(num, self.paginator.num_pages+1):
            yield num

Usage in the template:

<ul class="pagination">
    <li rel="prev">
        <a {% if page.has_previous %}href="?page={{ page.previous_page_number }}"{% endif %}>
            Previous
        </a>
    </li>

    {% for pg in page.pages_with_ellipsis %}

	{% if pg != '...' %}
	    <li {% if pg == page.number %}class="active"{% endif %}>
		<a {% if pg != page.number %}href="?page={{ pg }}"{% endif %}>
		    {{ pg }}
		</a>
	    </li>
	{% else %}
	    <li><span>&hellip;</span></li>
	{% endif %}

    {% endfor %}

    <li rel="next" {% if page.has_next %}class="highlight"{% endif %}>
	<a {% if page.has_next %}href="?page={{ page.next_page_number }}"{% endif %}>
	    Next
	</a>
    </li>
</ul>

[Vlada Macek]

A screenshot of the paginator.

[Vlada Macek]

Attached is the screenshot of how it can look.

The method is a simple and effetcive Python generator jumping over iteresting blocks of pages.

[Tim Graham]

The admin ​contains a similar paginator in the form of a template tag. Maybe it would be worth trying to refactoring that into django.core.paginator so it's more easily reuseable. I'm not sure how well the code will generalize.

[Sasha Gaevsky]

​PR

[Tim Graham]

Looks like it's on the right track, but the new class should be documented too.

[Tim Graham]

​PR

[Nick Pope]

Updated with a new ​PR.

[Carlton Gibson <carlton@…>]

In b203ec70:

Refs #25513 -- Adjusted admin pagination to be 1-indexed.

[Carlton Gibson <carlton@…>]

In f35840c1:

Refs #25513 -- Fixed admin pagination elision bounds.

It doesn't make sense to elide a single page number which could be a
clickable link to that page. We only want to elide two or more pages.

[Carlton Gibson <carlton@…>]

In 0a306f7:

Fixed #25513 -- Extracted admin pagination to Paginator.get_elided_page_range().