django-notifications-hq 1.7.0

Extra data

You can attach arbitrary data to your notifications by doing the following:

• Add to your settings.py: DJANGO_NOTIFICATIONS_CONFIG = { 'USE_JSONFIELD': True}

Then, any extra arguments you pass to notify.send(...) will be attached to the .data attribute of the notification object. These will be serialised using the JSONField’s serialiser, so you may need to take that into account: using only objects that will be serialised is a good idea.

Soft delete

By default, delete/(?P<slug>\d+)/ deletes specified notification record from DB. You can change this behaviour to “mark Notification.deleted field as True” by:

• Add to your settings.py: DJANGO_NOTIFICATIONS_CONFIG = { 'SOFT_DELETE': True}

With this option, QuerySet methods unread and read contain one more filter: deleted=False. Meanwhile, QuerySet methods deleted, active, mark_all_as_deleted, mark_all_as_active are turned on. See more details in QuerySet methods section.

QuerySet methods

Using django-model-utils, we get the ability to add queryset methods to not only the manager, but to all querysets that will be used, including related objects. This enables us to do things like:

Notification.objects.unread()

which returns all unread notifications. To do this for a single user, we can do:

user = User.objects.get(pk=pk)
user.notifications.unread()

There are some other QuerySet methods, too.

Model methods

Template tags

Put {% load notifications_tags %} in the template before you actually use notification tags.

{% notifications_unread %}

{% notifications_unread as unread_count %}
...
{% if unread_count %}
    You have <strong>{{ unread_count }}</strong> unread notifications.
{% endif %}

How to use:

1. Put {% load notifications_tags %} in the template before you actually use notification tags.

2. In the area where you are loading javascript resources add the following tags in the order below:

   <script src="{% static 'notifications/notify.js' %}" type="text/javascript"></script>
   {% register_notify_callbacks callbacks='fill_notification_list,fill_notification_badge' %}

   register_notify_callbacks takes the following arguments:

   1. badge_class (default live_notify_badge) - The identifier class of the element to show the unread count, that will be periodically updated.

   2. menu_class (default live_notify_list) - The identifier class of the element to insert a list of unread items, that will be periodically updated.

   3. refresh_period (default 15) - How often to fetch unread items from the server (integer in seconds).

   4. fetch (default 5) - How many notifications to fetch each time.

   5. callbacks (default <empty string>) - A comma-separated list of javascript functions to call each period.

   6. api_name (default list) - The name of the API to call (this can be either list or count).

3. To insert a live-updating unread count, use the following template:

   {% live_notify_badge %}

   live_notify_badge takes the following arguments:

   1. badge_class (default live_notify_badge) - The identifier class for the <span> element that will be created to show the unread count.

4. To insert a live-updating unread list, use the following template:

   {% live_notify_list %}

   live_notify_list takes the following arguments:

   1. list_class (default live_notify_list) - The identifier class for the <ul> element that will be created to insert the list of notifications into.

Using the live-updater with bootstrap

The Live-updater can be incorporated into bootstrap with minimal code.

To create a live-updating bootstrap badge containing the unread count, simply use the template tag:

{% live_notify_badge badge_class="badge" %}

To create a live-updating bootstrap dropdown menu containing a selection of recent unread notifications, simply use the template tag:

{% live_notify_list list_class="dropdown-menu" %}

Customising the display of notifications using javascript callbacks

While the live notifier for unread counts should suit most use cases, users may wish to alter how unread notifications are shown.

The callbacks argument of the register_notify_callbacks dictates which javascript functions are called when the unread api call is made.

To add a custom javascript callback, simply add this to the list, like so:

{% register_notify_callbacks callbacks='fill_notification_badge,my_special_notification_callback' %}

The above would cause the callback to update the unread count badge, and would call the custom function my_special_notification_callback. All callback functions are passed a single argument by convention called data, which contains the entire result from the API.

For example, the below function would get the recent list of unread messages and log them to the console:

function my_special_notification_callback(data) {
    for (var i=0; i < data.unread_list.length; i++) {
        msg = data.unread_list[i];
        console.log(msg);
    }
}

Testing the live-updater

1. Clone the repo

2. Run ./manage.py runserver

3. Browse to yourserverip/test/

4. Click ‘Make a notification’ and a new notification should appear in the list in 5-10 seconds.

AbstractNotification model

In case you need to customize the notification model in order to add field or customised features that depend on your application, you can inherit and extend the AbstractNotification model, example:

#In your_app/models.py

from django.db import models
from notifications.base.models import AbstractNotification


class Notification(AbstractNotification):
    # custom field example
    category = models.ForeignKey('myapp.Category',
                                 on_delete=models.CASCADE)

    class Meta(AbstractNotification.Meta):
        abstract = False

You will require to define NOTIFICATIONS_NOTIFICATION_MODEL setting in setting.py as follows:

# In your_project/settings.py

NOTIFICATIONS_NOTIFICATION_MODEL = 'your_app.Notification'

Email Notification

Sending email to users has not been integrated into this library. So for now you need to implement it if needed. There is a reserved field Notification.emailed to make it easier.

Sample App

A sample app has been implemented in notifications/tests/sample_notifications that extends django-notifications with the sole purpose of testing its extensibility. You can run the SAMPLE APP by setting the environment variable SAMPLE_APP as follows

export SAMPLE_APP=1
# Run the Django development server with sample_notifications app installed
python manage.py runserver
# Unset SAMPLE_APP to remove sample_notifications app from list of INSTALLED_APPS
unset SAMPLE_APP