Metadata-Version: 2.1
Name: django-messages-ui
Version: 2.0.2
Summary: JS client-side messages plugin, with support for Djangocontrib.messages app
Home-page: https://github.com/jgerigmeyer/jquery-django-messages-ui/
Author: Jonny Gerig Meyer
Author-email: jonny@oddbird.net
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.6
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.3
Classifier: Framework :: Django
License-File: LICENSE-MIT
License-File: AUTHORS.rst

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::

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

.. _`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::

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


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


CHANGES
=======

2.0.2 (2015.03.01)
-------------------

* Merge pull request #5 from shinglyu/http204 (handle response with no content-type header)
* Merge pull request #4 from support-lazy-messages (coerve message bodies to text)

2.0.1 (2014.03.20)
-------------------

* Delay instantiating Handlebars to prevent error if not using default.

2.0.0 (2014.03.20)
-------------------

* BACKWARDS INCOMPATIBLE: Accept callable template fn instead of namespace and tplName.

1.1.1 (2014.03.18)
-------------------

* Add bower.json.

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.
