Skip to main content

A Django application which provides temporary notifications.

Project description

=============
Django Notify
=============

A Django application which provides temporary notifications.

Notification messages persist until a request retrieves them.


Installation
============

Add the middleware to your ``MIDDLEWARE_CLASSES`` setting (the default
temporary storage relies on Django's ``contrib.sessions`` application, so place
this after ``SessionMiddleware``)::

'django_notify.middleware.NotificationsMiddleware',

To make it easy to access notifications in templates, add the context processor
into your ``TEMPLATE_CONTEXT_PROCESSORS`` setting::

'django_notify.context_processors.notifications',


Usage
=====

Adding a notification message
-----------------------------

The middleware attaches an instance of a temporary storage class called
``notifications`` to your ``request``. To add a notification, call::

request.notifications.add('Hello world.')

Some other methods provide a standard way to add notifications with commonly
used tags (which are usually represented as HTML classes for the message)::

request.notifications.debug('%s SQL statements were executed.' % count)
request.notifications.success('Profile details updated.')
request.notifications.warning('Your account expires in three days.')
request.notifications.error('Document deleted.')


Displaying notification messages
--------------------------------

In your template, use something like::

{% if notifications %}
<ul class="messages">
{% for message in notifications %}
<li{% if message.tags %} class="{{ message.tags }}"{% endif %}>{{ message }}</li>
{% endfor %}
</ul>
{% endif %}

If you're using the context processor, your template should be rendered with a
``RequestContext``. Otherwise, ensure ``request.notifications`` is available to
the template context.


Expiration of notification messages
-----------------------------------

The notifications are marked to be cleared when the storage instance is
iterated (and cleared when the response is processed).

To avoid the notifications being cleared, you can set
``request.notifications.used = False`` after iterating.


Notification Levels
-------------------

The ``NOTIFICATIONS_LEVEL`` setting can be used to change the minimum recorded
level. Attempts to add notifications of a level less than this will be ignored.

The built-in levels (which can be imported from ``django_notify`` directly)
are::

======== ===== ===========
Constant Level Default Tag
======== ===== ===========
DEBUG 10 'debug'
INFO 20 ''
SUCCESS 25 'success'
WARNING 30 'warning'
ERROR 40 'error'
======== ===== ===========

``INFO`` is the default minimum recorded level. It is also the
default level of the ``add`` method.

The minimum recorded level can also be set per request by changing the
``level`` attribute of the notifications storage instance::

import django_notify

# Change the notifications level to ensure the debug message is added.
request.notifications.level = django_notify.DEBUG
request.notifications.debug('Test notification...')

# Set the notifications level back to default.
request.notifications.level = None


Custom Tags
-----------

To provide custom tags for notification levels (either built in levels or
custom ones), set the ``NOTIFICATIONS_TAGS`` setting to a dictionary
containing the levels you wish to change. As this extends the default tags,
you only need to provide tags for the levels you wish to override::

import django_notify
NOTIFICATIONS_TAGS = {
django_notify.INFO: 'info',
50: 'critical',
}

For more direct control over message tags, you can optionally provide a string
containing extra tags to any of the add methods::

request.notifications.add('Over 9000!', extra_tags='dragonball')
request.notifications.error('Email box full', extra_tags='email')

Extra tags are added before any default tag for that level (space separated).


Temporary Storage Backends
==========================

Django notify can use different backends to store temporary messages. To change
which backend is being used, add a ``NOTIFICATIONS_STORAGE`` to your settings,
referencing to the module and class of the storage class. For example::

NOTIFICATIONS_STORAGE = 'cookie.CookieStorage'

Django Notify first looks for the module inside of ``django_notify.storage``,
and if not found, tries to import the full given module directly.

Three temporary storage classes are included in Django Notify:

``'session.SessionStorage'``
This class stores all messages inside of the request's session. It
requires Django's ``contrib.session`` application.

``'cookie.CookieStorage'``
This class stores the notification data in a cookie (signed with a secret
hash to prevent manipulation) to persist notifications across requests.
Old messages are dropped if the cookie data size would exceed 4096 bytes.

``'fallback.FallbackStorage'``
This is the default temporary storage class.

This class uses CookieStorage for all notification messages, falling back
to using SessionStorage for the messages which could not fit in a single
cookie.

Since it is uses SessionStorage, it also requires Django's
``contrib.session`` application.

To write your own, subclass the ``BaseStorage`` class in
``django_notify.storage.base`` and write ``_get`` and ``_store`` methods.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for django-notify, version 1.1.0
Filename, size File type Python version Upload date Hashes
Filename, size django-notify-1.1.0.tar.gz (11.4 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring DigiCert DigiCert EV certificate Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page