django-lazy-tags 0.1.0

Installation

1. Install via pip

pip install django-lazy-tags

2. Add to installed apps

INSTALLED_APPS = (
    # ...
    'lazy_tags',
)

3. Add the lazy tags urls to your root urlconf.

urlpatterns = patterns('',
    # ...
    url(r'^lazy_tags/', include('lazy_tags.urls')),
)

Usage

First, load the lazy_tags library in your templates.

{% load lazy_tags %}

Then, call the lazy_tag template tag passing your tag name as the first parameter. The format is tag_library.tag_name where tag_library is what you would load at the top of the page (e.g. my_tags) and tag_name is the name of your template tag (e.g. my_template_tag). After the first argument to lazy_tag simply pass the rest of the args and kwargs just as you would pass them to your own tag.

This:

{% load my_tags %}

{% my_template_tag arg1 arg2 kw1='hello' kw2='world' %}

Becomes this:

{% load lazy_tags %}

{% lazy_tag 'my_tags.my_template_tag' arg1 arg2 kw1='hello' kw2='world' %}

After placing your template tags in the template you still need to specify where you would like the AJAX JavaScript to output to the page. That is what the lazy_tags_js tag is for:

{% block js-additional %}
  {% lazy_tags_js%}
{% endblock %}

This will spit out the JavaScript:

<script type="text/javascript">
    $.ajax({
        type: "GET",
        url: "{{ tag_url }}",
        data: {
            tag: "{{ tag }}",
            args: JSON.stringify({{ args }}),
            kwargs: JSON.stringify({{ kwargs }}),
        },
        success: function(data) {
            $('#{{ tag_id }}-spinner').hide();
            $('#{{ tag_id }}').replaceWith(data);
        },
        error: function(data) {
            $('#{{ tag_id }}-spinner').hide();
            $('#{{ tag_id }}').replaceWith('{{ error_message }}');
        }
    });
</script>

Settings

LAZY_TAGS_ERROR_MESSAGE

The error message to display if the AJAX request fails. Defaults to 'An error occurred.'

LAZY_TAGS_FORCE_LOGIN

True if you would like to require a user be logged in for django-lazy-tags to work. Defaults to False.

Customizing the Loading Animation

This is the default HTML on the page before the AJAX request completes:

<div id="{id}" class="lazy-tag-replace">
    <div class="lazy-tag-spinner-container"
         style="width: 100%; text-align: center;">
        <img id="{id}-spinner" class="lazy-tag-spinner"
             style="width: 15px; height: 15px;"
             src="{static_url}img/lazy_tags/spinner.gif" />
    </div>
</div>

To customize the loading animation, override the lazy-tag-replace, lazy-tag-spinner-container, or lazy-tag-spinner classes in your CSS.

Current Limitations

• jQuery is required for the the AJAX calls. You must have jQuery loaded on the page before calling lazy_tags_js.

• Does not work with tags that take context

• Template tag arguments must be serializable

• Template tag arguments are always passed in as strings. If your tag requires an argument to be an int then be sure to cast it to an int before usage.