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_ library
• jQuery 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 }
  );