README
jQuery Django Messages UI
.. image:: https://travis-ci.org/jgerigmeyer/jquery-django-messages-ui.svg?branch=master :target: https://travis-ci.org/jgerigmeyer/jquery-django-messages-ui .. image:: https://cdn.gruntjs.com/builtwith.png :target: http://gruntjs.com/
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.
.. _Handlebars.js
: http://handlebarsjs.com/
Dependencies
jQuery
_ libraryjQuery doTimeout
_ plugin- (optionally)
handlebars.runtime.js
_ 1.0.0 - (optionally)
ICanHaz.js
_ - (optionally)
django-icanhaz
_ 0.2.0+
.. _jQuery
: http://jquery.com/
.. _jQuery doTimeout
: http://benalman.com/projects/jquery-dotimeout-plugin/
.. _handlebars.runtime.js
: http://handlebarsjs.com/
.. _ICanHaz.js
: http://icanhazjs.com/
.. _django-icanhaz
: https://github.com/carljm/django-icanhaz
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
_.
.. _production version
: https://raw.github.com/jgerigmeyer/jquery-django-messages-ui/master/dist/django-messages-ui.min.js
.. _development version
: https://raw.github.com/jgerigmeyer/jquery-django-messages-ui/master/dist/django-messages-ui.js
.. _Handlebars.js precompiled template
: https://raw.github.com/jgerigmeyer/jquery-django-messages-ui/master/messages_ui/static/messages_ui/message.js
.. _ICanHaz.js template
: https://raw.github.com/jgerigmeyer/jquery-django-messages-ui/master/messages_ui/jstemplates/message.html
Linking the JS::
If desired, also include the precompiled JS template
_::
.. _precompiled JS template
: https://raw.github.com/jgerigmeyer/jquery-django-messages-ui/master/messages_ui/static/messages_ui/message.js
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
.
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.
.. _PyPI
: https://pypi.python.org/pypi/django-messages-ui
Linking the JS::
If desired, also include the precompiled JS template::
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
.
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
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 }
);