django-notify 1.1.2

A Django application which provides temporary notifications.

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.