SwampDragon notifications
Project description
# SwampDragon notifications
[ ![Codeship Status for jonashagstedt/swampdragon-notifications](https://codeship.com/projects/fc0d69b0-9763-0132-b800-6a66c6b56914/status?branch=master)](https://codeship.com/projects/63149)
Notify your users in real time.
**Note** Since notifications isn't always an essential part of a system, only signed in users receive notifications.
# Prerequisites
* Redis 2.8+
# Installation
pip install swampdragon-notifications
Add the following to `INSTALLED_APPS`:
INSTALLED_APPS = [
...
'swampdragon',
'swampdragon_auth',
'swampdragon_notifications',
]
Set the SwampDragon connection to:
SWAMP_DRAGON_CONNECTION = ('swampdragon_notifications.notification_connection.Connection', '/data')
# Setup
{% load swampdragon_tags static %}
...
<!-- Swamp dragon -->
{% swampdragon_settings %}
<script type="text/javascript" src="{% static 'swampdragon/js/dist/swampdragon.min.js' %}"></script>
<!-- Swamp dragon notifications -->
<script type="text/javascript" src="{% static 'js/dist/swampdragon-notifications.js' %}"></script>
# JavaScript API
## Get number of users online:
notifications.onlineCount(function (count) {
console.log(count);
});
## User count onChange event:
Triggered when a new user comes online or someone goes offline
notifications.onlineCountChange(function (count) {
setUserCount(count);
});
## Desktop notifications
To enable desktop notifications: `notifications.enableDesktopNotifications();`.
To disable desktop notifications: `notifications.disableDesktopNotifications();`.
To trigger a desktop notifications:
var payload = {
body:notification.some_value,
icon: notification.icon // assuming an icon url is available,
tag: 'foo'
}
notifications.desktopNotification('New foo', payload);
# Example setup (settings.py)
The following example setup will send both email notifications and realtime notifications.
To disable the email notifications: remove `'swampdragon_notifications.backends.email_notifications.EmailNotification'` from `SWAMP_DRAGON_NOTIFICATION_BACKENDS`.
SWAMP_DRAGON_NOTIFICATION_BACKENDS = [
('realtime', 'swampdragon_notifications.backends.realtime_notifications.RealtimeNotification'),
('email', 'swampdragon_notifications.backends.email_notifications.EmailNotification'),
]
SWAMP_DRAGON_NOTIFICATIONS = {
'foo': {
'processor': 'app.subject_renderer.foo_to_dict',
'icon': 'http://placekitten.com/g/64/64',
'subject': 'A new foo',
'template': 'new_foo_notification',
}
}
SWAMP_DRAGON_HEARTBEAT_ENABLED = True
SWAMP_DRAGON_HEARTBEAT_FREQUENCY = 1000 * 60 * 5 # Five minutes
Create a file called subject_renderer.py in your project, and add a new function:
def foo_to_dict(notification, **kwargs):
return {
...
}
The function `foo_to_dict` should return a dictionary with any data you want to pass on to the client.
## Subject processors
A subject processor belongs to a notification type (defined in `SWAMP_DRAGON_NOTIFICATIONS`).
The processor is a function, and takes a `notification` and `**kwargs` as arguments, and returns a dictionary.
Example processor:
def foo_processor(notification, **kwargs):
return {
'foo_id': notification.subject.pk,
'timestamp': now(),
'extra_value': kwargs.get('extra_value')
}
## Settings
Enable heart beat if you are using realtime notifications.
This helps keep track on who is online.
SWAMP_DRAGON_HEARTBEAT_ENABLED = True
SWAMP_DRAGON_HEARTBEAT_FREQUENCY = 1000 * 60 * 5 # Five minutes
### `SWAMP_DRAGON_NOTIFICATIONS`
To customise notification, add `SWAMP_DRAGON_NOTIFICATIONS` to settings.
This is a dictionary:
SWAMP_DRAGON_NOTIFICATIONS = {
'foo': {
'processor': 'app.subject_renderer.foo_to_dict'
'template': 'standard_email', # Only used by email backend,
'subject': 'Dear {}, you have a new notification', # Only used by email backend
'title': 'Notification',
'icon': 'http://placekitten.com/g/64/64'
}
}
`template` and `subject` only concern the default email backend.
### Notification backends
There are two notification backends: email and realtime.
Set notification backends:
SWAMP_DRAGON_NOTIFICATION_BACKENDS = [
('realtime', 'swampdragon_notifications.backends.realtime_notifications.RealtimeNotification'),
('email', 'swampdragon_notifications.backends.email_notifications.EmailNotification'),
]
`'swampdragon_notifications.backends.realtime_notifications.RealtimeNotification'` is enabled by default.
### Email notification backend
The emails will, by default, be sent from `settings.SERVER_EMAIL`.
To change the sender email address specify `NOTIFICATION_SENDER` in settings.
#### Creating a custom notification backend
Add a new file to your project `foo_notification_backend.py`.
Add a class `FooNotificationBackend`
implement the function `def notify(notification):` in your custom notification backend
from swampdragon_notifications.backends.base_backend import BaseBackend
class FooNotificationBackend(BaseBackend):
def notify(self, notification):
pass
3. Add the new backend to your settings
SWAMP_DRAGON_NOTIFICATION_BACKENDS = [
...
('foo', 'myproj.foo_notification_backend.FooNotificationBackend'),
]
[ ![Codeship Status for jonashagstedt/swampdragon-notifications](https://codeship.com/projects/fc0d69b0-9763-0132-b800-6a66c6b56914/status?branch=master)](https://codeship.com/projects/63149)
Notify your users in real time.
**Note** Since notifications isn't always an essential part of a system, only signed in users receive notifications.
# Prerequisites
* Redis 2.8+
# Installation
pip install swampdragon-notifications
Add the following to `INSTALLED_APPS`:
INSTALLED_APPS = [
...
'swampdragon',
'swampdragon_auth',
'swampdragon_notifications',
]
Set the SwampDragon connection to:
SWAMP_DRAGON_CONNECTION = ('swampdragon_notifications.notification_connection.Connection', '/data')
# Setup
{% load swampdragon_tags static %}
...
<!-- Swamp dragon -->
{% swampdragon_settings %}
<script type="text/javascript" src="{% static 'swampdragon/js/dist/swampdragon.min.js' %}"></script>
<!-- Swamp dragon notifications -->
<script type="text/javascript" src="{% static 'js/dist/swampdragon-notifications.js' %}"></script>
# JavaScript API
## Get number of users online:
notifications.onlineCount(function (count) {
console.log(count);
});
## User count onChange event:
Triggered when a new user comes online or someone goes offline
notifications.onlineCountChange(function (count) {
setUserCount(count);
});
## Desktop notifications
To enable desktop notifications: `notifications.enableDesktopNotifications();`.
To disable desktop notifications: `notifications.disableDesktopNotifications();`.
To trigger a desktop notifications:
var payload = {
body:notification.some_value,
icon: notification.icon // assuming an icon url is available,
tag: 'foo'
}
notifications.desktopNotification('New foo', payload);
# Example setup (settings.py)
The following example setup will send both email notifications and realtime notifications.
To disable the email notifications: remove `'swampdragon_notifications.backends.email_notifications.EmailNotification'` from `SWAMP_DRAGON_NOTIFICATION_BACKENDS`.
SWAMP_DRAGON_NOTIFICATION_BACKENDS = [
('realtime', 'swampdragon_notifications.backends.realtime_notifications.RealtimeNotification'),
('email', 'swampdragon_notifications.backends.email_notifications.EmailNotification'),
]
SWAMP_DRAGON_NOTIFICATIONS = {
'foo': {
'processor': 'app.subject_renderer.foo_to_dict',
'icon': 'http://placekitten.com/g/64/64',
'subject': 'A new foo',
'template': 'new_foo_notification',
}
}
SWAMP_DRAGON_HEARTBEAT_ENABLED = True
SWAMP_DRAGON_HEARTBEAT_FREQUENCY = 1000 * 60 * 5 # Five minutes
Create a file called subject_renderer.py in your project, and add a new function:
def foo_to_dict(notification, **kwargs):
return {
...
}
The function `foo_to_dict` should return a dictionary with any data you want to pass on to the client.
## Subject processors
A subject processor belongs to a notification type (defined in `SWAMP_DRAGON_NOTIFICATIONS`).
The processor is a function, and takes a `notification` and `**kwargs` as arguments, and returns a dictionary.
Example processor:
def foo_processor(notification, **kwargs):
return {
'foo_id': notification.subject.pk,
'timestamp': now(),
'extra_value': kwargs.get('extra_value')
}
## Settings
Enable heart beat if you are using realtime notifications.
This helps keep track on who is online.
SWAMP_DRAGON_HEARTBEAT_ENABLED = True
SWAMP_DRAGON_HEARTBEAT_FREQUENCY = 1000 * 60 * 5 # Five minutes
### `SWAMP_DRAGON_NOTIFICATIONS`
To customise notification, add `SWAMP_DRAGON_NOTIFICATIONS` to settings.
This is a dictionary:
SWAMP_DRAGON_NOTIFICATIONS = {
'foo': {
'processor': 'app.subject_renderer.foo_to_dict'
'template': 'standard_email', # Only used by email backend,
'subject': 'Dear {}, you have a new notification', # Only used by email backend
'title': 'Notification',
'icon': 'http://placekitten.com/g/64/64'
}
}
`template` and `subject` only concern the default email backend.
### Notification backends
There are two notification backends: email and realtime.
Set notification backends:
SWAMP_DRAGON_NOTIFICATION_BACKENDS = [
('realtime', 'swampdragon_notifications.backends.realtime_notifications.RealtimeNotification'),
('email', 'swampdragon_notifications.backends.email_notifications.EmailNotification'),
]
`'swampdragon_notifications.backends.realtime_notifications.RealtimeNotification'` is enabled by default.
### Email notification backend
The emails will, by default, be sent from `settings.SERVER_EMAIL`.
To change the sender email address specify `NOTIFICATION_SENDER` in settings.
#### Creating a custom notification backend
Add a new file to your project `foo_notification_backend.py`.
Add a class `FooNotificationBackend`
implement the function `def notify(notification):` in your custom notification backend
from swampdragon_notifications.backends.base_backend import BaseBackend
class FooNotificationBackend(BaseBackend):
def notify(self, notification):
pass
3. Add the new backend to your settings
SWAMP_DRAGON_NOTIFICATION_BACKENDS = [
...
('foo', 'myproj.foo_notification_backend.FooNotificationBackend'),
]
Project details
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distributions
Close
Hashes for swampdragon-notifications-0.1.3.2.zip
Algorithm | Hash digest | |
---|---|---|
SHA256 | 7b71910bd863a60f0bdf3b8f15b9f334fa08379a25c0555879933a7aa42fb0aa |
|
MD5 | 71d5ba0aa2b8f6ea7f4e0c8c62b894db |
|
BLAKE2b-256 | 49205fb98c04093fc537ca6a4464bc59c5a586c893dbf083962e5964812ac50c |
Close
Hashes for swampdragon-notifications-0.1.3.2.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | 9cfe208b1950be53837356e3db4ebefce676f2f771fb4aa1618715d5b84718be |
|
MD5 | 25bb47380253637e7e87e225ff8d7d57 |
|
BLAKE2b-256 | e1bd11f0616312ac11a0428fc17f9424c423ec08a0d54fc2f59eec9b498d4e24 |