Customizing django-messages

There are multiple levels at which you can customize django-messages without altering the code directly.


Django-messages comes with a set of built-in templates which you can use. If these templates don’t fit your project you can override any or all of them by putting files with the same filenames in one the directories listes in TEMPLATES_DIRS in your

Django-messages uses the following templates:

  • django_messages/base.html - A base template from which all the following templates inherit. Maybe it’s enough to customize this template for your project.
  • django_messages/compose.html - This template is rendered, when a user composes a new messages.
  • django_messages/inbox.html - This template lists the users inbox.
  • django_messages/new_messages.html - This template is used to construct the notification mail sent to a user, whenever a new message is received.
  • django_messages/outbox.html - This template lists the users outbox aka sent messages.
  • django_messages/trash.html - This template lists the users trash.
  • django_messages/view.html - This template renders a single message with all details.

Additionally django-message provides a set of template for pinax-notifications. These template can be found in django_messages/templates/notification/ and can also be overwritten in one of your project’s TEMPLATE_DIRS.


If you want to further customize how django-messages works it is possible to write your own url-conf instead of including django_messages.urls in your root url-conf. This not only allows changing the url structure but also allows modifying the kwargs passed to the views and therefore modifying some behaviour.

Please note: If you provide your own url-conf, or urlpatterns directly embedded in your root url-conf, you shouldn’t include django_messages.urls.

Three common customizations are described in more detail below.

Modifying template names

If overwriting templates in your project’s TEMPLATE_DIRS does not provide enough freedom, you can change the names of the used templates by providing a template_name keyword argument to the views. Every view which renders a template accepts this keyword-argument.

If you want to change the template the inbox view uses to my_inbox.html instead of the default django_messages/inbox.html you can use this line in your own url-conf:

    {'template_name': 'my_inbox.html',},

Modifying form classes

If you want to use your own form for composing messages, for example to add new features, you can simply pass the form-class to the views via kwargs. Every view which renders a form accepts a form_class keyword argument to specify the form-class.

If you want to use Your own MyComposeForm you can pass it to the view by using a line like the following in your own url-conf:

from somewhere import MyComposeForm
    {'form_class': MyComposeForm,},

Modifying success urls

All views, which will redirect the user after a successfull action accept a success_url keyword argument to specify the destination url. The delete and undelete views will additionally check if a next parameter is provided in the querystring appended to the url.

If you don’t want to append the next target to the url, or want to change the redirecting behaviour of other views, you can pass a success_url parameter in your own url-conf, for example like this:

    {'success_url': '/profile/',},

Adding recipient filter

To restrict allowed recipients a recipient_filter function can be added to the compose view.

The following filter function makes sure messages can only be sent to active users:

lambda u: u.is_active

To use this filter, integrate it into your url-conf:

    {'recipient_filter': lambda u: u.is_active},