django-user-messages - Offline addon for django.contrib.messages¶
django-user-messages adds offline messaging support to Django’s
messaging framework. It achieves this by allowing to save messages in
the database. The user_messages.api.get_messages
utility and the
user_messages.context_processors.messages
context processor
transparently concatenate Django’s messages and our own messages in a single
list, therefore existing code works without any changes and without
causing database writes. django-user-messages’ functions have to be
used explicitly. I consider this a feature, not a bug.
Installation¶
Install
django-user-messages
using pip into your virtualenv.Add
user_messages
toINSTALLED_APPS
and runmigrate
.Add the
user_messages.context_processors.messages
message processor somewhere after the default messages processor. Django’s admin app checks for the presence of the latter so you cannot simply remove it (except if you want to silence the"admin.E404"
system check).Use
user_messages.api
as you would usedjango.contrib.messages
except that you pass the user model or ID as first parameter, not the current request.
Usage¶
Pretty much the same as Django’s messaging framework:
from user_messages import api
api.info(user, 'Hey there')
api.warning(user, 'Stop this')
api.error(user, 'Not nice!')
# Passing the ID is also possible; the user instance does not
# have to be instantiated at all:
api.success(user.id, 'Yay!')
django-user-messages’ messages supports two additional features not available in Django’s messages framework:
Messages can be delivered more than once by passing
deliver_once=False
. These messages have to be acknowledged explicitly. django-user-messages does not contain any code to do this.It is possible to attach additional data by passing a dictionary as
meta
:api.debug(user, 'Oww', meta={ 'url': 'http://example.com', })
For convenience, our messages have the same tags
and level_tag
properties as Django’s messages. Meta properties are also accessible in
templates:
{% if messages %}
<ul class="messages">
{% for message in messages %}
<li class="{{ message.tags }}".>
{% if message.meta.url %}<a href="{{ message.meta.url }}">{% endif %}
{{ message }}
{% if message.meta.url %}</a>{% endif %}
</li>
{% endfor %}
</ul>
{% endif %}
django-user-messages’ messages are also evaluated lazily.
Change log¶
Next version¶
1.1 (2024-09-11)¶
Added Django 5.0, 5.1 compatibility.
Squashed migrations to remove uses of
index_together
which wasn’t liked by newer versions of Django.
1.0 (2022-09-25)¶
Added pre-commit.
Raised the version requirements to Python >= 3.8, Django >= 3.2.
Replaced the system check with a version which only cares about adding our context processor after the default messages context processor and about nothing else.
0.8 (2022-02-03)¶
Switched to a declarative setup.
Switched from Travis CI to GitHub actions.
Added a composite index to reduce database load when fetching messages. Thanks @tpatterson!
0.7 (2020-01-22)¶
Fixed a crash because of unicode strings being returned from
Message.__str__
in Python 2.Order messages upon retrieval.
Added Django 3.0 to the Travis CI matrix.
Replaced
ugettext*
withgettext*
to avoid deprecation warnings.
0.6 (2018-09-26)¶
Reformatted the code using black.
Added a hint about silencing the messages context processor system check under Django 2.2.
0.5 (2018-03-04)¶
Added german translations and a nice app name.
Changed the implementation of keyword-only arguments to be compatible with Python 2.
0.4 (2017-07-19)¶
Backwards incompatible Rebuilt the model to not use Django’s
JSONField
at all. This design decision unnecessarily restricted the areas where django-user-messages was usable.Fixed properties to be more forgiving with missing data.
Added tox configuration for running tests and coding style checks and for building the docs.
Improved documentation and test coverage.
0.3 (2017-05-18)¶
Added usage instructions.
Merge the
message
andmeta
JSON fields into a singledata
field and imitate theMessage
object interface more closely.
0.2 (2017-05-18)¶
Added the possibility to associate additional data with a message py passing a dictionary as the
meta
keyword-only argument to the API.Changed the module to import the
Message
model as late as possible so that the API can easily be imported for example in aAppConfig
module.
0.1 (2017-05-17)¶
Initial public release.