skip to navigation
skip to content

django-messages-ui 1.0.3

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

Latest Version: 2.0.2

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 or ICanHaz.js, and if used as a Django plugin there’s a Python middleware to automatically add messages from the request into Ajax JSON responses.


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 using Handlebars.js, also include the precompiled JS template:

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

To override the default JS template using Handlebars.js, 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 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 using Handlebars.js, 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 using Handlebars.js, 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.


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.


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


Calling the plugin:


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

    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 () {
    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
    templating: 'handlebars',     // JS templating engine
                                  //  ...set to ``ich`` to use ICanHaz.js
    tplNamespace: 'Handlebars',   // Global namespace where precompiled
                                  //  ...Handlebars template is stored
    escapeHTML: true              // Set ``false`` to display unescaped
                                  //  ...HTML in message content


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});


1.0.3 (2013.10.29)

  • Add option for Handlebars templates global namespace.

1.0.2 (2013.10.27)

  • Add missing

1.0.1 (2013.10.27)

  • Fix 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.
File Type Py Version Uploaded on Size
django-messages-ui-1.0.3.tar.gz (md5) Source 2013-10-29 12KB
  • Downloads (All Versions):
  • 30 downloads in the last day
  • 359 downloads in the last week
  • 1990 downloads in the last month