Coverage for superdjango/contrib/notifications/__init__.py : 100%
Hot-keys on this page
r m x p toggle line displays
j k next/prev highlighted chunk
0 (zero) top of page
1 (one) first highlighted chunk
1"""
2Abstract
3--------
5The notifications app is primarily meant to provide in-app (e.g. in-project) notifications, but may also be used to send
6email and SMS when supported.
8Install
9-------
11Add ``superdjango.contrib.notifications.apps.DefaultConfig`` to ``INSTALLED_APPS``.
13Run ``./manage.py migrate``.
15Sending Email
16.............
18If you will be sending notifications via email:
201. Define the email address from which the message is sent using ``SUPERDJANGO_NOTIFICATIONS_FROM_EMAIL``.
212. Define the from name of the email address using ``SUPERDJANGO_NOTIFICATIONS_FROM_NAME``.
23Sending SMS/Text
24................
26If you will be sending notifications via SMS, you'll need to create a callback which integrates with a text messaging
27service such as Twilio.
29The callback must accept a body, mobile number, and optionally a from number. For example:
31.. code-block:: python
33 def send_sms(body, number, from_number=None):
34 # ...
36Set ``SUPERDJANGO_NOTIFICATIONS_SMS_CALLBACK`` to the dotted path of the callback. Optionally set the
37``SUPERDJANGO_NOTIFICATIONS_FROM_NUMBER``.
39Usage
40-----
42The notifications system allows developers to queue up notifications for users. It is also possible for administrators
43or authorized users to create notifications using the provided UI (see below).
45Creating a Notification Programmatically
46........................................
48To create a notification for a user:
50.. code-block:: python
52 from django.contrib.auth import get_user_model
53 from superdjango.contrib.notifications.models import Notification
55 UserModel = get_user_model()
57 body = "This is a test notification."
58 subject = "Testing 123"
59 users = [
60 UserModel.objects.get(pk=1),
61 UserModel.objects.get(pk=2),
62 UserModel.objects.get(pk=3),
63 ]
64 notification = Notification.create_for(body, subject, users)
66You can of course pass in a list of users with only one user instance.
68Sending Notifications
69.....................
71The notifications app makes use of a queue pattern where the actual links to a user (and optional email/SMS) must be
72executed on a regular schedule. This is the purpose of the ``send_notifications`` management command.
74Create a shell script which loads the Python environment and executes the command:
76.. code-block:: bash
78 #! /usr/bin/env bash
80 cd /path/to/project;
81 source python/bin/activate;
82 cd source;
83 ./manage.py send_notifications;
85Then add the script to a cron job:
87.. code-block:: text
89 # send notifications every 15 minutes
90 */15 * * * * root /path/to/project/cron/send_notifications.sh
92Displaying Notifications
93........................
95Various template tags are provided for displaying a user's notifications in your templates. All require the current user
96as a parameter.
98``has_notifications``: Indicates whether a user has unread notifications.
100.. code-block:: html
102 {% if has_notifications request.user %}
103 <div class="alert alter-info">You have some notifications.</div>
104 {% endif %}
106``notification_bar``: Utilizes the ``notifications/tags/notification_bar.html`` template to display a promoted
107notification at the top of a page.
109.. code-block:: html
111 <head>
112 ...
113 <link rel="stylesheet" href="{% static "superdjango/contrib/notifications/css/notification-bar.css" %}">
114 </head>
115 <body>
116 {% notification_bar request.user %}
117 ...
119 <script src="{% static "superdjango/contrib/notifications/js/notification-bar.js" %}"></script>
120 </body>
122If the AJAX views are set up using the automatic method (below), you may replace ``notification-bar.js`` with
123``notification-bar-ajax.js``. Otherwise, additional work is required to override ``notification-bar-ajax.js`` so that
124it refers to the correct URL.
126``unread_notification_count``: Returns the number of unread notifications.
128.. code-block:: html
130 <div class="notifications">
131 <i class="fas fa-bell"></i> Notifications
132 <span class="badge badge-danger">{% unread_notification_count request.user %}</span>
133 </div>
135``unread_notifications``: Utilizes the ``notifications/tags/notification_items.html`` template to display a list of
136notifications.
138.. code-block:: html
140 <div class="notifications">
141 {% unread_notifications request.user %}
142 </div>
144Finally, the included ``notify_web_api.html`` template may be used to display in-browser messages for promoted
145notifications.
147.. code-block:: html
149 <body>
150 ...
151 {% include "notifications/includes/notify_web_api.html" %}
152 </body>
154Utilizing the Standard Views
155............................
157Detail and list views are provided for displaying notifications to users.
159.. code-block:: python
161 # main/urls.py
162 from superdjango.contrib.notifications.views import NotificationsViewSet
164 urlpatterns = [
165 path("notifications/", include(NotificationsViewSet().get_urls())),
166 ]
168Utilizing the AJAX Views
169........................
171The notification apps provides two (2) AJAX views; one for obtaining unread notifications, and the other for marking a
172notification as read.
174To automatically include these views, simply add ``superdjango.interfaces.ajax.apps.AutoConfig`` to your
175``INSTALLED_APPS`` and include the AJAX URLs in your main ``urls.py`` file. See :ref:`interfaces-interfaces-ajax`.
177You may also manually include the views:
179.. code-block:: python
181 # main/urls.py
182 from superdjango.contrib.notifications.views import AjaxNotificationsViewSet
184 urlpatterns = [
185 # ...
186 path("ajax/notify/", include(AjaxNotificationsViewSet().get_urls())),
187 # ...
188 ]
190Setting up the UI
191.................
193The notification apps comes with pre-defined configuration for SuperDjango UI. You may use it as is by registering the
194``NotificationsMenu`` with the UI, or customize as desired.
196.. code-block:: python
198 # glue/ui.py
199 from superdjango import ui
200 from superdjango.contrib.notifications.ui import NotificationsMenu
202 ui.site.register(NotificationsMenu)
204"""
205__author__ = "Shawn Davis <shawn@superdjango.com>"
206__maintainer__ = "Shawn Davis <shawn@superdjango.com>"
207__version__ = "0.4.0-x"
209# https://www.w3schools.com/howto/howto_css_notification_button.asp
210# https://www.html5rocks.com/en/tutorials/notifications/quick/
211# https://github.com/alexgibson/notify.js