JS client-side messages plugin, with support for Django contrib.messages app
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.
- jQuery library
- jQuery doTimeout plugin
- (optionally) handlebars.runtime.js 1.0.0
- (optionally) ICanHaz.js
- (optionally) django-icanhaz 0.2.0+
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, pass your own precompiled template function
as option 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)
. Then pass in
the precompiled template: template: ich.message
.
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>
If using ICanHaz.js to insert messages on the client side, use this template
instead, and pass in the precompiled template: template: ich.message
:
{% include "messages_ui/_messages_ich.html" %}
To override the default JS template, pass your own precompiled template function
as option template
.
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"
.
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 template: Handlebars.templates.message, // Callable precompiled template fn. 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 } );