Source

django-endless-pagination-de / doc / usage.wiki

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
= Endless Pagination =

|| Author: || Francesco Banconi <[mailto:francesco.banconi@gmail.com francesco.banconi@gmail.com]> ||


= 1 Introduction =

This app can be used to provide ajaxed Twitter-style or Digg-style pagination.

The initial idea, which has guided the development of this application, is to allow ajax pagination of web contents in very few steps, as done by the excellent tool _django-pagination_ (see http://github.com/ericflo/django-pagination/tree/master).

= 2 Installation =

The `endless_pagination` package, included in the distribution, should be placed on the _Python path_.

Or just `easy_install django-endless-pagination`.

== 2.1 Requirements ==

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

= 3 Usage =

== 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.

= 4 Digg-style pagination =

Digg-style pagination of queryset objects is really easy to implement. If AJAX pagination is not needed, all you have to do is modify the template, e.g.:

{{{

{% load endless %}

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

}}}

That's it! If you want to display only previous and next links (in a page-by-page pagination) you need to use the lower level _get_pages_ templatetag (see reference below), e.g.:

{{{

{% load endless %}

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

}}}

See the paragraph _Customization_ that explains how to customize arrows of previous and next pages.

== 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.

= 5 Templatetags reference =

== 5.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 %}

}}}

You must use this tag before calling `{% show_more %}` or `{% show_pages %}`.

== 5.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 %}`.

== 5.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 %}`.

== 5.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 Customization =

You can customize the application using `settings.py`.

  * _ENDLESS_PAGINATION_PER_PAGE_ (default=10): How many objects are normally displayed in a page (overwriteable by templatetag).
  * _ENDLESS_PAGINATION_PAGE_LABEL_ (default="page"): The querystring key of the page number (e.g. `http://example.com?page=2`)
  * _ENDLESS_PAGINATION_ORPHANS_ (default=0): See django _Paginator_ definition of orphans.
  * _ENDLESS_PAGINATION_LOADING_ (default="loading"): If you use the default _show_more_ template, here you can customize the content of the loader hidden element Html is safe here, e.g. you can show your pretty animated gif

{{{

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

}}}

  * _ENDLESS_PAGINATION_PREVIOUS_LABEL_ (default=u"&lt;&lt;") and _NEXT_LABEL_ (default=u"&gt;&gt;"): Labels for previous and next page links.
  * _ENDLESS_PAGINATION_PAGE_LIST_CALLABLE_ (default=None): Callable that returns pages to be displayed. If None a default callable is used (that produces digg-style pagination).Default callable returns pages for digg-style pagination, and depends on the settings below:
  * _ENDLESS_PAGINATION_DEFAULT_CALLABLE_EXTREMES_ (default=3)
  * _ENDLESS_PAGINATION_DEFAULT_CALLABLE_AROUNDS_ (default=2)

== 6.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 loader hidden element class is _endless_loading_

Application comes with English and Italian i18n.

= 7 Related projects =

Try out http://code.google.com/p/django-yafinder/ if you need to add filter and sort capabilities to your index page.