Metadata-Version: 2.1
Name: django-channels-notifications
Version: 1.1
Summary: Django Channels Notifications
Home-page: https://github.com/Abdelhadi92/django-channels-notifications
Author: Abdelhadi Abu-Shamleh
Author-email: abushamleh92@gmail.com
License: BSD
Keywords: Django Channels Notifications
Platform: UNKNOWN
Classifier: Environment :: Web Environment
Classifier: Framework :: Django
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Classifier: Development Status :: 5 - Production/Stable
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Description-Content-Type: text/markdown
Requires-Dist: setuptools
Requires-Dist: jsonfield
Requires-Dist: requests

# Django Channels Notifications
Notifying users of various things that happen in your application is super easy to implement. Django Channels notifications allow you to send a message to any user via Email, Datbase, and many other channels.

<br/>

## Installation

1. Run the [pip](https://pip.pypa.io/en/stable/) command to install the latest version:

```bash
 pip install django-channels-notifications
```

2. Add `django_channels_notifications` to your `INSTALLED_APPS` in settings.py:
```bash
 INSTALLED_APPS = (
    ...
    'django_channels_notifications',
 )
```

3. Run the migration command:
```bash
 python manage.py migrate
```

<br/>

## Creating Notifications

In Django Channels Notifications, each notification is represented by a single class, and to create a new notification you can run the following manage.py command:
```bash
 python manage.py createnotification TestNotification
 ```   

And this will place a fresh notification class with the below contents. Each notification class contains a `via` method and a variable number of message building methods (such as `to_mail` or `to_database`) that convert the notification to a message optimized for that particular channel.

```python
from django_channels_notifications.core import Notification  
from django_channels_notifications.core.channels import DatabaseChannel  


class TestNotification(Notification):  

  # Get the notification's delivery channels.  
  def via(self, notifiable):  
        return [DatabaseChannel]  

  # Get the dict representation of the notification.  
  def to_database(self, notifiable):  
        pass
```
<br/>

## Sending  Notifications

###  # Using The Notifiable Mixin
Notifications may be sent in two ways: using the notify method of the Notifiable mixin or using the NotificationSender . First, let's explore using the mixin:

```python
 from django_channels_notifications.core import Notifiable
 from django.db import models

 class Profile(models.Model, Notifiable):  
	phone = models.CharField(max_length=255, verbose_name='Phone')
	address = models.TextField(max_length=512,verbose_name='Address')

```
Adding `Notifiable` mixin in your  `Profile` model will allow you to easily send notifications to profiles using `notify` method. The `notify` method expects to receive a notification instance:
```python
 profile = Profile.objects.get(pk=1)
 profile.notify(TestNotification());
```

**Remember ,** you may use the `django_channels_notifications.core.Notifiable` mixin on any of your models. You are not limited to only including it on your `Profile`model.


###  # Using The NotificationSender:
Alternatively, you may send notifications via the `NotificationSender` . This is useful primarily when you need to send a notification to multiple notifiable entities such as a list of profiles. To send notifications using the NotificationSender, pass all of the notifiable entities and the notification instance to the `send` method:

```python
 from django_channels_notifications.core import NotificationSender

 profiles = Profile.objects.all()
 NotificationSender.send(profiles, TestNotification())

```

###  # Specifying Delivery Channels:
Every notification class has a `via` method that determines on which channels the notification will be delivered. Notifications may be sent on the `database`, `mail`,  `unifonc` channels.

The `via` method receives a `notifiable` instance, which will be an instance of the class to which the notification is being sent. You may use `notifiable` to determine which channels the notification should be delivered on:

```python

 #Get the notification's delivery channels.
 def via(self, notifiable):
	 if notifiable.prefers_sms:
		return [UnifonicChannel]
	 return	[DatabaseChannel]

```
Let's quickly go through the different notification channels supported by Django Channels Notifications.

-   **Database:** This option allows you to store notifications in a database should you wish to build a custom UI to display it.
-  **Mail:** The notifications will be sent in the form of email to users.
-  **Unifonic:** As the name suggests, users will receive SMS notifications on their phone.
<br/>

## Database Channel
The `DatabaseChannel` notification stores the notification information in a database table. This table will contain information such as the notification type as well as custom JSON data that describes the notification.

###  # Formatting Database Notifications:
If a notification supports being stored in a database table, you should define a `to_database`  method on the notification class. This method will receive a `notifiable` entity and should return a plain Python dict. The returned dict will be encoded as JSON and stored in the `data` column of your `notifications` table. Let's take a look at an example `to_database` method:

```python

 # Get the dict representation of the notification. 
 def to_database(self, notifiable): 
    return {
        'invoice_id': 12,
        'amount': 200,
    } 

```

###  # Accessing The Notifications
Once notifications are stored in the database, you need a convenient way to access them from your notifiable entities. To fetch notifications, you may use the `notifications` method. By default, notifications will be sorted by the `created_at` timestamp:
```python

 profile = Profile.objects.get(pk=1)

 for notification in profile.notifications():
     print(notification.type)

```

If you want to retrieve only the "unread" notifications, you may use the  `unread_notifications`  method and If you want to retrieve only the "read" notifications, you may use the  `read_notifications`  method. Again, these notifications will be sorted by the  `created_at`  timestamp:

```python

 profile = Profile.objects.get(pk=1)

 for notification in profile.unread_notifications():
     print(notification.type)

 for notification in profile.read_notifications():
     print(notification.type)
```

###  # Marking Notifications As Read , Unread: 
Typically, you will want to mark a notification as "read" when a user views it. The `django_channels_notifications.core.notifiable` mixin provides  `mark_as_read` and `mark_as_unread` methods, which updates the `read_at` column on the notification's database record:

```python

profile = Profile.objects.get(pk=1)

# Marking notifications as read
for notification in profile.unread_notifications():
    notification.mark_as_read()

# Marking notifications as unread   
for notification in profile.read_notifications():
    notification.mark_as_unread()    

```
<br/>

## Mail Channel  
If a notification supports being sent as an email, you should define a `to_mail` method on the notification class. This method will receive a `notifiable` entity and should return a [`django.core.mail.EmailMessage`](https://docs.djangoproject.com/en/2.2/topics/email/#the-emailmessage-class)  or  [`django.core.mail.EmailMultiAlternatives`](https://docs.djangoproject.com/en/2.2/topics/email/#sending-alternative-content-types) instance. Let's take a look at an example `to_mail` method:   
```python
from django.core.mail import EmailMessage

 # Get the mail representation of the notification.
 def to_mail(self, notifiable):  
    return EmailMessage(
        'Hello',
        'Body goes here',
        'from@example.com',
        ['to1@example.com', 'to2@example.com'],
        ['bcc@example.com'],
        reply_to=['another@example.com'],
        headers={'Message-ID': 'foo'},
    )    

```

###  # Sending through "Mailgun" :
To use the Mailgun provider,  you need to add the following parameters to your `settings.py`:

```bash
 EMAIL_HOST = 'smtp.mailgun.org'  
 EMAIL_PORT = 587  
 EMAIL_HOST_USER = 'postmaster@msg.com' #please change this with your username  
 EMAIL_HOST_PASSWORD = '112233445566778899' #please change this with your password  
 EMAIL_USE_TLS  =  True
```

###  # Sending through "SES" :
To use the SES provider, you'll need [Boto](http://boto.cloudhackers.com/) 2.1.0 or higher. [Boto](http://boto.cloudhackers.com/) is a Python library that wraps the AWS API. 

You can do the following to install boto 2.1.0 (we're using --upgrade here to make sure you get 2.1.0):
```bash
pip install --upgrade boto
```

Install django-ses:
```bash
pip install django-ses
```

Add the following to your settings.py:

```python
EMAIL_BACKEND = 'django_ses.SESBackend'

# These are optional -- if they're set as environment variables they won't
# need to be set here as well
AWS_ACCESS_KEY_ID = 'YOUR-ACCESS-KEY-ID'
AWS_SECRET_ACCESS_KEY = 'YOUR-SECRET-ACCESS-KEY'

# Additionally, if you are not using the default AWS region of us-east-1,
# you need to specify a region, like so:
AWS_SES_REGION_NAME = 'us-west-2'
AWS_SES_REGION_ENDPOINT = 'email.us-west-2.amazonaws.com'
```

<br/>

## Unifonic Channel
The `UnifonicChannel` notification allow you to sent the notification as SMS via Unifonic.

You need to add `UNIFONIC_APPSID`  in settings.py:
```bash
 UNIFONIC_APPSID = "Your Unifonic APPSID" 
```


###  # Formatting Unifonic Notifications:
If a notification supports being sent as an SMS, you should define a `to_unifonic` method on the notification class. This method will receive a `notifiable` entity and should return a `django_channels_notifications.core.channels.unifonic_channel.UnifonicMessage` instance:
```python
 from django_channels_notifications.core.channels.unifonic_channel import UnifonicMessage

 # Get the Unifonic representation of the notification.
 def to_unifonic(self, notifiable):  
    return UnifonicMessage().set_body('Your SMS message content').set_recipient(notifiable.phone)

```
### # Customizing The "SenderID":
If you would like to send some notifications from a SenderID that is different from the default SenderID in your  Unifonic account, you may use the  `set_sender_id` method on a  `UnifonicMessage`  instance:
```python
 from django_channels_notifications.core.channels.unifonic_channel import UnifonicMessage

 # Get the Unifonic representation of the notification.
 def to_unifonic(self, notifiable):  
    return UnifonicMessage().set_body('Your SMS message content').set_recipient(notifiable.phone).set_sender_id('Your SenderID')

```
<br/>

## Custom Channels
Django Channels Notifications ships with a handful of notification channels, but you may want to write your own channel to deliver notifications via other channels. Django Channels Notifications makes it simple. To get started, define a class that extended from `django_channels_notifications.core.BaseChannel` and contains a `send` method. The method should receive two arguments: a `notifiable` and a `notification`. or by run the following manage.py command:

```bash
 python manage.py createchannel TestChannel
```

```python
 from django_channels_notifications.core import BaseChannel  


 class TestChannel(BaseChannel):  
	# Send the given notification.  
	def send(self, notifiable, notification):  
        pass

```
Once your notification channel class has been defined, you may return the class name from the `via` method of any of your notifications:

```python
class TestNotification(Notification):  

  # Get the notification's delivery channels.  
  def via(self, notifiable):  
        return [DatabaseChannel, TestChannel]  

  # Get the dict representation of the notification.  
  def to_database(self, notifiable):  
        pass

  # Get the dict representation of the notification.  
  def to_test(self, notifiable):  
        pass
```


