Configuration

In order to plug Django-Flash to your project, open your project’s settings.py file and do the following changes:

TEMPLATE_CONTEXT_PROCESSORS = (
    'djangoflash.context_processors.flash',
)

MIDDLEWARE_CLASSES = (
    'django.contrib.sessions.middleware.SessionMiddleware',
    'djangoflash.middleware.FlashMiddleware',
)

That’s all the required configuration.

Warning

The djangoflash.middleware.FlashMiddleware class must be declared after the SessionMiddleware class.

Django-Flash and requests to media files

Django itself doesn’t serve static (media) files, such as images, style sheets, or video. It leaves that job to whichever web server you choose. But, during development, you can use the django.views.static.serve() view to serve media files.

The problem with it is that, as a regular view, requests to django.views.static.serve() trigger the installed middlewares. And since the flash gets updated by a middleware, messages might be removed from the flash by accident if the response causes the web browser to issue requests to fetch static files.

To make Django-Flash work well with the django.views.static.serve() view, you can add the setting FLASH_IGNORE_MEDIA to your project’s settings.py file:

FLASH_IGNORE_MEDIA = True # Optional. Default: DEBUG

Set the FLASH_IGNORE_MEDIA setting to True, and Django-Flash won’t remove any message from the flash if the request URL resolves to django.views.static.serve(). Otherwise, every request will trigger the djangoflash.middleware.FlashMiddleware as usual.

Note

This setting is optional; its default value is DEBUG. So, if you adjust the DEBUG setting according to the environment in which the application runs (as you should), you don’t have to worry about this setting at all, things will just work.

Flash storage backends

Since version 1.5, Django-Flash supports custom flash storage backends.

By default, Django-Flash provides two built-in storage backends:

• djangoflash.storage.session – Session-based storage (default);
• djangoflash.storage.cookie – Cookie-based storage;

See also

Creating a custom flash storage backend

Using the session-based storage

Django-Flash uses the session-based storage by default, so you don’t need to do anything else to use it.

Although you are not required to do so, you can add the following setting to your project’s settings.py file to make it clear about what flash storage backend is being used:

FLASH_STORAGE = 'session' # Optional

This storage backend doesn’t rely on codecs to serialize and de-serialize the flash data; it lets Django handle this.

Using the cookie-based storage

If you want to use the cookie-based storage instead the default one, then add the following setting to the settings.py file:

FLASH_STORAGE = 'cookie'

Since cookies will be used to store the contents of the flash scope, Django-Flash doesn’t require you to add the SessionMiddleware class to the MIDDLEWARE_CLASSES section of your project’s settings anymore.

This storage backend relies on codecs to serialize and de-serialize the flash data.

Flash serialization codecs

Since version 1.7, Django-Flash supports custom flash serialization codecs.

By default, Django-Flash provides three built-in codecs:

• djangoflash.codec.json_impl – JSON-based codec (default);
• djangoflash.codec.json_zlib_impl – JSON/zlib-based codec;
• djangoflash.codec.pickle_impl – Pickle-based codec;

See also

Creating a custom serialization codec

Using the JSON-based codec implementation

For security reasons, Django-flash uses the JSON-based codec implementation by default, so you don’t need to do anything else to use it.

Although you are not required to do so, you can add the following setting to your project’s settings.py file to make it clear about what codec implementation is being used:

FLASH_CODEC = 'json' # Optional

There’s also an alternative version of this codec that uses the zlib module to reduce the encoded flash footprint. This is particularly useful when the flash storage backend in use (such as the cookie-based storage) cannot handle the amount of data in the flash:

FLASH_CODEC = 'json_zlib'

Using the Pickle-based codec implementation

If you want to use the Pickle-based codec implementation instead the default one, then add the following setting to the settings.py file:

FLASH_CODEC = 'pickle'

Warning

The use of this codec is not recommended since the Pickle documentation itself clearly states that it’s not intended to be secure against erroneous or maliciously constructed data.