django-ajax-utilities 1.2.7

Pagination, xhr and tabbing utilities for the Django framework.

A few utilities for making pagination and tabbing easier. Everything should work with and without javascript. If javascript is enabled, several features like preloading can be obtained.

Currently, we have:

1. pagination

2. tabbing

3. xhr: for loading a part of the page delayed through AJAX, when it is heavy

   to render.

DEPENDENCIES:

• JQuery Javascript Library

• {% macro %} and {% call %} template tags:

  https://github.com/citylive/Django-Template-Tags/tree/master/templatetags

1. Pagination

In settings.py, add this application:

> INSTALLED_APPS += (‘django_ajax’,)

The default styling just renders previous and next buttons. If you want links to more pages rendered, add this setting:

> PAGINATION_STYLE = ‘verbose’

In views.py

> from django_ajax.pagination import paginate > > # … read objects (Query list or other iterable object) > objects = range(0, 100) > > # Paginate > paginated_objects = paginate(request, objects, 25, > query_string_parameters= {‘order_by’: order_by, ‘by’: by }, > use_get_parameters=False, > page_variable=’page1’) > > context = { ‘paginated_objects’: paginated_objects }

25 tells the paginator to show no more than 25 objects per page. use_get_parameters is optional, when set True, it will add all the parameters of the current query string (request.METAQUERY_STRING) automatically to the paginator links. query_string_parameters is also optional, this are other parameters to add to the query string of the links. page_variable is optional too. It’s only required when several paginators are combined at the same page. The variable should be unique for each paginator.

In the template:

> {% load ajax_utilities %} > {% paginate paginated_objects %} > … > {% for object in paginated_objects.object_list %} > … > {% endfor %} > … > {% endpaginate %}

In the base template, add this script:

> <script type=”text/javascript” src=”{{ STATIC_URL }}js/ajax-utilities/pagination.js”></script>

This javascript code will look for the previous and next link, and it will preload these two pages. When one of these links is clicked, the paginator body of the preloaded page shall be put into the body of the currently visible page.

If you have additional navigation links inside the paginator body, like ordering column headers. Place the links in a container, classnamed “pagination-helper”. This will make them use ajax too.

> <div class=”pagination-helper”> > <a href=”{{ request.path }}?order_by_name”>…</a> > </div>

The search results of a GET form can be retreived through AJAX, similar to loading any other page. The form should have action=”?” and method=”get” parameters. When enter has been pressed in this form, only the body of the paginator will be reloaded, leaving the rest of the web page intact.

> <form method=”get” action=”?” class=”pagination-form”> > <label><input type=”text” name=”q” value=”{{ q }}” /></label> > </form>

In Javascript:

If you ever need to execute custom JS code when the paginator has replaced its body; use the following javascript code:

> function handler(e, containers) > { > // code to be excuted when the paginator switches from page … > // containers is an Array of elements (jquery items) where content may have been changed. > } > $(document).bind(‘paginatorPageReplaced’, handler);

If you want to delay the rendering of the paginator, because it contains some heavy queries, nest the paginator in an {% xhr %} template tag as follows: (Nesting the other way around is not yet possible, and probably never will be.)

> {% load ajax_utilities %} > {% xhr %} > {% paginate paginator %} > … > {% endpaginate %} > {% endxhr %}

Additional note: To allow bookmarking of pages, the currently visible page is appended to window.location.hash

1. Tabbing

In the template:

> {% load ajax_utilities %} > {% tabpage %} > {% tabs %} > <ul> > <li class=”selected”><a href=”…”>…</a></li> > <li class=””><a href=”…”>…</a></li> > <li class=””><a href=”…”>…</a></li> > </ul> > {% endtabs %} > {% tabcontent %} > {% block tab_content %} > inherit this template and fill in the tab content by creating a block named ‘tab_content’. > {% enblock %} > {% endtabcontent %} > {% endtabpage %} > > <script type=”text/javascript” src=”{{ STATIC_URL }}js/ajax-utilities/tabbing.js”></script>

This is usually the base template. Every tab matches a separate view, which renders a template, derived from this base template. It will fill in the block tab_content, and mark the tab as “selected”.

If you want a link inside a tab page to be opened inside the same tab, use the tabbing-helper-class:

> <a class=”tabbing-helper” href=”…”> (something which opens in this tab) </a>

In Javascript:

> function handler(e, containers) > { > // code to be excuted when the paginator switches from page … > // containers is an Array of elements (jquery items) where content may have been changed. > } > $(document).bind(‘tabLoaded’, handler);

1. xhr

This is an AJAX optimazation for heavy web pages. The {% xhr %} template tags marks a section of the template to be rendered during a later XML HTTP Request (AJAX).

So, actually, every view which template contains {% xhr %} is rendered twice. First without the slow, heavy content, where a placeholder <div> is inserted, and later on, rendering everything.

Insert the following scripts to your HTML:

> <script type=”text/javascript” src=”{{ STATIC_URL }}/js/ajax-utilities/xhr.js”></script>

Mark the slow parts with {% xhr %}:

> {% load xhr %} > … some content … > > {% xhr %} > Very slow content > {% else %} > Loading, … (insert loading message or images, … here) > {% endxhr %} > > … some content …

The {% else %} part can be omitted, or it can contain a loading message.

If the slow content depends on calculations in the view, which are not necessary for the other content. Make sure to not execute them during the first run in the view:

> def view(request): > if ‘xhr’ in request.REQUEST: > do_slow_calculations() > > return …

In Javascript:

> function handler() > { > … (code to be excuted when the xhr content has been loaded) … > $(‘.xhr_container’).each(function () { … } ); > } > $(document).bind(‘xhrLoaded’, handler);