django-messages-ui 1.1.0

JS client-side messages plugin, with support for Django contrib.messages app

jQuery Django Messages UI

JS client-side messages plugin, with support for Django contrib.messages app

Getting Started

django-messages-ui can be used as a standalone jQuery plugin for adding and removing client-side messages, or as a Django add-on to additionally support the Django contrib.messages app. It should be called on the message list element, and accepts options for message selectors, transient messages (that disappear on click or key-press), and close-links. The messages themselves should be styled with CSS.

Messages can be dynamically added via Handlebars.js, ICanHaz.js, or any other templating engine which creates precompiled callable template fns. If used as a Django plugin there’s a Python middleware to automatically add messages from the request into Ajax JSON responses.

Dependencies

• jQuery library

• jQuery doTimeout plugin

• (optionally) handlebars.runtime.js 1.0.0

• (optionally) ICanHaz.js

• (optionally) django-icanhaz 0.2.0+

Installation as a Standalone jQuery Plugin

If using as a standalone jQuery plugin, download the production version or the development version, along with either the Handlebars.js precompiled template or the ICanHaz.js template.

Linking the JS:

<script src="dist/django-messages-ui.min.js"></script>

If desired, also include the precompiled JS template:

<script src="messages_ui/static/messages_ui/message.js"></script>

To override the default JS template, link to your own precompiled JS file with a message template.

If using ICanHaz.js, wrap the ICanHaz.js template (or your own custom template, if you don’t want to use the default template) in a <script id="message" type="text/html"> tag and include it in your HTML, or import it in JS using ich.addTemplate('message', YOUR_TEMPLATE_STRING).

Installation with Django

If using with Django, just pip install django-messages-ui to install (or download the tarball from PyPI, unpack it, and run python setup.py install). In your Django project settings, add "messages_ui" to your INSTALLED_APPS setting.

Linking the JS:

<script src="{% static 'messages_ui/django-messages-ui.js' %}"></script>

If desired, also include the precompiled JS template:

<script src="{% static 'messages_ui/message.js' %}"></script>

Including the default HTML template:

{% include "messages_ui/_messages.html" %}

If using ICanHaz.js to insert messages on the client side, use this template instead:

{% include "messages_ui/_messages_ich.html" %}

To override the default JS template, link to your own precompiled JS file with a message template.

To override the default JS template using ICanHaz.js and django-icanhaz, add a message.html file to a directory listed in your ICANHAZ_DIRS setting.

Ajax

To enable automatic handling of messages from Ajax requests, add "messages_ui.middleware.AjaxMessagesMiddleware" to your MIDDLEWARE_CLASSES setting (directly after django.contrib.messages.middleware.MessageMiddleware), and pass handleAjax: true to the plugin initialization.

Warning

AjaxMessagesMiddleware converts all HTML AJAX responses into JSON responses with a messages key, and the HTML embedded in an html key. If your site uses HTML AJAX responses, this will likely require updates to other Ajax-handling code in your site. To avoid this for a particular response, set the attribute no_messages on that response to True before it passes through AjaxMessagesMiddleware.

Similarly, handleAjax: true globally sets the default expected dataType for AJAX requests to "json".

Usage

Calling the plugin:

$('#messages').messages();

Calling the plugin with a variety of options explicitly configured to their default values:

$('#messages').messages({
  message: '.message',          // Selector for individual messages
  closeLink: '.close',          // Selector for link to close message
                                //  ...set to ``false`` to disable
  closeCallback:                // Fn called when closeLink is clicked
    function (el) {
      el.stop().fadeOut('fast', function () {
        el.remove();
      });
    },
  transientMessage: '.success', // Selector for transient messages
  transientDelay: 500,          // Transient message callback delay (ms)
  transientCallback:            // Fn called after transientDelay
    function (el) {
      el.fadeOut(2000, function () { el.remove(); });
    },
  handleAjax: false,            // Enable automatic AJAX handling
  tplNamespace: 'Handlebars.templates',
                                // Global namespace where precompiled
                                // ...callable template is stored
  tplName: 'message',           // Template name (must be precompiled
                                // ...and callable as a fn, accepting
                                // ...data as first argument)
  escapeHTML: true              // Set ``false`` to display unescaped
                                //  ...HTML in message content
});

Note

After the plugin is called once, subsequent calls on the same element will default to the options passed the first time, unless new options are explicitly provided.

Adding a message in JS:

$('#messages').messages('add', {message: "Sample Message", tags: "info"});

Adding a message with unescaped HTML in JS:

$('#messages').messages(
  'add',
  { message: "<a href='/'>Sample Message</a>", tags: "info" },
  { escapeHTML: false }
);

CHANGES

1.1.0 (2014.02.14)

• Add option for template name.

• Make agnostic regarding templating engine, as long as template is precompiled and callable fn.

1.0.3 (2013.10.29)

• Add option for Handlebars templates global namespace.

1.0.2 (2013.10.27)

• Add missing __init__.py.

1.0.1 (2013.10.27)

• Fix manifest.in to include package json file.

1.0.0 (2013.10.27)

• Publish as a standalone jQuery plugin. Add JS unit tests.

• BACKWARDS INCOMPATIBLE: js filename changed from jquery.messages-ui.js to django-messages-ui.js

0.2.7 (2013.09.25)

• Remove transient messages on scroll (also mousedown, keydown, mouseover).

0.2.6 (2013.06.05)

• Fix AjaxMessagesMiddleware encoding issue with Python 3 and JSON response.

• Precompile Handlebars template with 1.0.0.

0.2.5 (2013.05.23)

• Precompile Handlebars template with 1.0.0-rc.4.

• Make AjaxMessagesMiddleware Py3-compatible.

0.2.4 (2013.01.28)

• Add option for function called after closeLink is clicked.

0.2.3 (2013.01.24)

• Add option for function called on transient messages after transientDelay.

0.2.2 (2013.01.21)

• Add response.no_messages option for disabling middleware.

0.2.1 (2013.01.14)

• Rewrite using method plugin architecture; simpler ‘add’ method to add msg.

• Add option to display unescaped HTML in message content.

0.2.0 (2013.01.11)

• Add option to use Handlebars.js (new default) instead of ICanHaz.js.

0.1.8 (2013.01.03)

• Make close-link selector specific to within a message; use preventDefault.

0.1.7 (2012.11.06)

• JS stop transient-message fade on close-link click.

0.1.6 (2012.10.05)

• JS don’t parse non-json.

0.1.5 (2012.07.23)

• Don’t touch non-200 responses.

0.1.4 (2011.07.14)

• JS cleanup; added JSLint options.

0.1.3 (2011.06.28)

• Added closeLink: false plugin option.

• Subsequent plugin calls on the same element default to previous options unless explicitly overridden.

0.1.2 (2011.06.27)

• Added AjaxMessagesMiddleware and handleAjax plugin option.

0.1.1 (2011.06.27)

• Updated HTML template (removed <aside> and moved #messages to <ul>).

0.1.0 (2011.06.25)

• Initial release.