2.1 Requirements

• Python >= 2.5
• Django >= 1.0
• jQuery >= 1.3

3.1 Settings

Add the request context processor in your settings.py, e.g.:

from django.conf.global_settings import TEMPLATE_CONTEXT_PROCESSORS
TEMPLATE_CONTEXT_PROCESSORS += (
     'django.core.context_processors.request',
)

Add 'endless_pagination' to the INSTALLED_APPS in your settings.py.

See Customization section in this documentation for other settings options.

3.2 Let's start

As creative example, the developer wants pagination of entries of a blog post.

In views.py we have:

def entry_index(request, template="myapp/entry_index.html"):
    context = {
        'objects': Entry.objects.all(),
    }
    return render_to_response(template, context,
        context_instance=RequestContext(request))

In myapp/entry_index.html:

<h2>Entries:</h2>
{% for object in objects %}
    {# your code to show the entry #}
{% endfor %}

3.3 Split the template

A response to an AJAX request should not return the entire template, but only the portion of the page to update or add. So it is convenient to extrapolate from the template the part containing entries and use the new one to render the context if the request is AJAX. The main template will include the other, so it is convenient to put the page template in the context.

views.py becomes:

def entry_index(request,
    template="myapp/entry_index.html",
    page_template="myapp/entry_index_page.html"):
    context = {
        'objects': Entry.objects.all(),
        'page_template': page_template,
    }
    if request.is_ajax():
        template = page_template
    return render_to_response(template, context,
        context_instance=RequestContext(request))

See below how to obtain the same result just decorating the view (in a way compatible with generic views too).

myapp/entry_index.html becomes:

<h2>Entries:</h2>
{% include page_template %}

myapp/entry_index_page.html becomes:

{% for object in objects %}
    {# your code to show the entry #}
{% endfor %}

3.4 A shortcut for ajaxed views

A good practice in writing views is to allow other developers to inject the template name and extra data to be added to the context. This allows the view to be easily reused. Let's resume the original view with extra context injection:

views.py:

def entry_index(request, template="myapp/entry_index.html",
    extra_context=None):
    context = {
        'objects': Entry.objects.all(),
    }
    if extra_context is not None:
        context.update(extra_context)
    return render_to_response(template, context,
        context_instance=RequestContext(request))

Splitting templates and putting the ajax template name in the context is easily achievable at this point (using a builtin decorator).

views.py becomes:

from endless_pagination.decorators import page_template

@page_template("myapp/entry_index_page.html") # just add this decorator
def entry_index(request, template="myapp/entry_index.html",
    extra_context=None):
    context = {
        'objects': Entry.objects.all(),
    }
    if extra_context is not None:
        context.update(extra_context)
    return render_to_response(template, context,
        context_instance=RequestContext(request))

This way, endless-pagination can be included in generic views too.

3.5 Pagination

Nothing remains but to change the page template, loading endless templatetags, the jQuery library and the javascript file endless.js included in the distribution under /media/js/.

myapp/entry_index.html becomes:

{% block js %}
    {{ block.super }}
    <script src="/path/to/jquery.js" type="text/javascript" charset="utf-8"></script>
    <script src="/path/to/endless.js" type="text/javascript" charset="utf-8"></script>
{% endblock %}

<h2>Entries:</h2>
{% include page_template %}

myapp/entry_index_page.html becomes:

{% load endless %}

{% paginate objects %}
{% for object in objects %}
    {# your code to show the entry #}
{% endfor %}
{% show_more %}

That's all. Read the next section of the documentation to improve the use of included templatetags.

{% load endless %}

{% paginate objects %}
{% for object in objects %}
    {# your code to show the entry #}
{% endfor %}
{% show_pages %}

{% load endless %}

{% paginate objects %}
{% for object in objects %}
    {# your code to show the entry #}
{% endfor %}
{% get_pages %}
{{ pages.previous }} {{ pages.next }}

4.1 Adding ajax

The view is exactly the same as in show_more twitter-style pagination:

from endless_pagination.decorators import page_template

@page_template("myapp/entry_index_page.html") # just add this decorator
def entry_index(request, template="myapp/entry_index.html",
    extra_context=None):
    context = {
        'objects': Entry.objects.all(),
    }
    if extra_context is not None:
        context.update(extra_context)
    return render_to_response(template, context,
        context_instance=RequestContext(request))

Of course you have to split templates, but this time a container for page template is needed too, and must have a class named endless_page_template.

myapp/entry_index.html becomes:

{% block js %}
    {{ block.super }}
    <script src="/path/to/jquery.js" type="text/javascript" charset="utf-8"></script>
    <script src="/path/to/endless.js" type="text/javascript" charset="utf-8"></script>
{% endblock %}

<h2>Entries:</h2>
<div class="endless_page_template">
    {% include page_template %}
</div>

myapp/entry_index_page.html becomes:

{% load endless %}

{% paginate objects %}
{% for object in objects %}
    {# your code to show the entry #}
{% endfor %}
{% show_pages %}

Done.

{% load endless %}

{% paginate objects %}
{% for object in objects %}
    {# your code to show the entry #}
{% endfor %}
{% show_pages %}

{% paginate other_objects using other_objects_page %} {# <-- a new querystring key #}
{% for object in other_objects %}
    {# your code to show the entry #}
{% endfor %}
{% show_pages %}

5.1 Adding ajax for multiple pagination

Obviously each pagination needs a template for the page content. Remember to box each page in a div with a class called endless_page_template.

myapp/entry_index.html:

{% block js %}
    {{ block.super }}
    <script src="/path/to/jquery.js" type="text/javascript" charset="utf-8"></script>
    <script src="/path/to/endless.js" type="text/javascript" charset="utf-8"></script>
{% endblock %}

<h2>Entries:</h2>
<div class="endless_page_template">
    {% include "myapp/entries_page.html" %}
</div>

<h2>Other entries:</h2>
<div class="endless_page_template">
    {% include "myapp/other_entries_page.html" %}
</div>

myapp/entries_page.html:

{% load endless %}

{% paginate objects %}
{% for object in objects %}
    {# your code to show the entry #}
{% endfor %}
{% show_pages %}

myapp/other_entries_page.html:

{% load endless %}

{% paginate other_objects using other_objects_page %}
{% for object in other_objects %}
    {# your code to show the entry #}
{% endfor %}
{% show_pages %}

Again the decorator page_template simplifies the management of ajax requests in views. You must, however, map different paginations to different page templates. You can chain decorator's calls relating a template with the associated querystring key, e.g.:

from endless_pagination.decorators import page_template

@page_template("myapp/entries_page.html")
@page_template("myapp/other_entries_page.html", key="other_objects_page")
def entry_index(request, template="myapp/entry_index.html",
    extra_context=None):
    context = {
        'objects': Entry.objects.all(),
        'other_objects': OtherEntry.objects.all(),
    }
    if extra_context is not None:
        context.update(extra_context)
    return render_to_response(template, context,
        context_instance=RequestContext(request))

As seen in previous examples, if you do not specify the key kwarg in the decorator, then the page template is associated to the querystring key defined in the settings.

You can use the page_templates (note the trailing s) decorator in substitution of a decorator chain when you need multiple ajax pagination. The previous example can be written:

from endless_pagination.decorators import page_templates

@page_templates({
    "myapp/entries_page.html": None,
    "myapp/other_entries_page.html": "other_objects_page",
})
def entry_index() ...

6.1 paginate

Usage:

{% paginate objects %}

After this call, in the template context the objects variable is replaced with only the objects of the current page.

You can also mantain your objects original variable (commonly a queryset) and add to context another name referring to objects of the current page, e.g.:

{% paginate objects as page_objects %}

The number of paginated object is taken from settings, but you can override the default, e.g.:

{% paginate 20 objects %}

Of course you can mix it all:

{% paginate 20 objects as paginated_objects %}

By default, the first page is displayed the first time you load the page, but you can easily change this, e.g.:

{% paginate objects starting from page 3 %}

This can be also achieved using a template variable you passed in the context, e.g.:

{% paginate objects starting from page page_number %}

If the passed page number does not exist then first page is displayed.

If you have multiple paginations in the same page, you can change the querydict key for the single pagination, e.g.:

{% paginate objects using article_page %}

Again, you can mix it all (the order of arguments is important):

{% paginate 20 objects starting from page 3 using page_key as paginated_objects %}

You must use this tag before calling the {% show_more %} one.

6.2 show_more

Show the link to get the next page in a Twitter-like pagination. Usage:

{% show_more %}

Must be called after {% paginate objects %}.

6.3 get_pages

Usage:

{% get_pages %}

This is mostly used for digg-style pagination. This call inserts in the template context a pages variable, as a sequence of page links. You can use pages in different ways:

just print pages and you will get digg-style pagination displayed:

{{ pages }}

display pages count:

{{ pages|length }}

get a specific page:

{# the current selected page #}
{{ pages.current }}

{# the first page #}
{{ pages.first }}

{# the last page #}
{{ pages.last }}

{# the previous page (or nothing if you are on first page) #}
{{ pages.previous }}

{# the next page (or nothing if you are in last page) #}
{{ pages.next }}

{# the third page #}
{{ pages.3 }}
{# this means page.1 is the same as page.first #}

iterate over pages to get all pages:

{% for page in pages %}
    {# display page link #}
    {{ page }}

    {# the page url (beginning with "?") #}
    {{ page.url }}

    {# the page path #}
    {{ page.path }}

    {# the page number #}
    {{ page.number }}

    {# a string representing the page (commonly the page number) #}
    {{ page.label }}

    {# check if the page is the current one #}
    {{ page.is_current }}

    {# check if the page is the first one #}
    {{ page.is_first }}

    {# check if the page is the last one #}
    {{ page.is_last }}
{% endfor %}

You can change the variable name, e.g.:

{% get_pages as page_links %}

Must be called after {% paginate objects %}.

6.4 show_pages

Show page links. Usage:

{% show_pages %}

It is only a shortcut for:

{% get_pages %}
{{ pages }}

You can set ENDLESS_PAGE_LIST_CALLABLE in your settings.py as a callable used to customize the pages that are displayed. The callable takes the current page number and the total number of pages and must return a sequence of page numbers that will be displayed. The sequence can contain other values:

• "previous": will display the previous page in that position
• "next": will display the next page in that position
• None: a separator will be displayed in that position

Here is an example of custom callable that displays previous page, then first page, then a separator, then current page, then next page:

def get_page_numbers(current_page, num_pages):
    return ("previous", 1, "...", current_page, "next")

If ENDLESS_PAGE_LIST_CALLABLE is None an internal callable is used, generating a digg-style pagination.

Must be called after {% paginate objects %}.

6.5 show_current_number

Just show current page number (useful in page titles). Usage:

{% show_current_number %}

If you use multiple paginations in the same page you can get the page number for a specific pagination using the querystring key, e.g.:

{% show_current_number using mykey %}

Default page when no querystring is specified is 1. If you changed in the paginate template tag, you have to call show_current_number according to your choice, e.g.:

{% show_current_number starting from page 3 %}

This can be also achieved using a template variable you passed in the context, e.g.:

{% show_current_number starting from page page_number %}

Of course, you can mix it all (the order of arguments is important):

{% show_current_number starting from page 3 using mykey %}

ENDLESS_PAGINATION_LOADING = """
    <img src="/site_media/img/loader.gif" alt="loading" />
"""

7.1 Template and css

You can override the default template for show_more templatetag following some rules:

• more link is showed only if variable querystring is not False
• the container (most external html element) class is endless_container
• the more link and the loader hidden element live inside the container
• the more link class is endless_more
• the more link rel attribute is {{ querystring_key }}
• the loader hidden element class is endless_loading

Application comes with English and Italian i18n.