Update documentation

Author: jefcolbi

README.md

@@ -20,10 +20,11 @@ Sending notifications in Django has always been a complex subject. Django Magic
 - Support files
 - Support multiple gateways
 - Extensible
+- Support MJML
 
 
 ### Installation
-> $pip install --upgrade django-magic-notifier
+> pip install --upgrade django-magic-notifier
 
 ### Usage
 ##### 1. Configure settings
@@ -48,38 +49,31 @@ NOTIFIER = {
 ```
 
 ##### 2. Create templates
-Create a folder named **notifier** in one of app's templates dir. In this folder create another folder named **base** then created your base templates in this folder. Example  
+Create a folder named **notifier** in one of app's templates dir. In this folder create another folder named **my_template** 
+then create your base templates in this folder. Example:  
 
-*app_name/templates/notifier/base/email.html*
+*app_name/templates/notifier/my_template/email.html*
 ```
-    {% extends "base_notifier/email.html" %}
+{% extends "base_notifier/email.html" %}
+{% block content %}
+<tr>
+    <td><p>Hello {{ user.email }}
+    </td>
+</tr>
+{% endblock %}
 ```  
 
-*app_name/templates/notifier/base/email.txt*
+*app_name/templates/notifier/my_template/email.txt*
 ```
-    {% extends "base_notifier/email.txt" %}
+{% extends "base_notifier/email.txt" %}
+{% block content %}
+Hello {{ user.email }}
+{% endblock %}
 ```  
 
-*app_name/templates/notifier/hello/email.html*
-```
-    {% extends "notifier/base/email.html" %}
-    {% block content %}
-    <tr>
-        <td><p>Hello {{ user.email }}
-        </td>
-    </tr>
-    {% endblock %}
-```  
-
-*app_name/templates/notifier/hello/email.txt*
-```
-    {% extends "notifier/hello/email.txt" %}
-    {% block content %}
-    >Hello {{ user.email }}
-    {% endblock %}
-```  
-
-As you can see, the user to whom the notification goes is automatically added in the template's context. To avoid any clash to don't send the key `'user'` in the context of the  **notifiy()** function presented below.
+As you can see, the user to whom the notification goes is automatically added 
+in the template's context. To avoid any clash don't send the key `'user'` 
+in the context of the  **notifiy()** function presented below.
 
 Note that it is DMN (Django Magic Notifier) that has the base_notifier template.
 

docs/source/conf.py

@@ -29,7 +29,7 @@
 author = 'MATTON Jef'
 
 # The full version, including alpha/beta/rc tags
-release = '0.1.2'
+release = '0.2.2'
 
 
 # -- General configuration ---------------------------------------------------

docs/source/index.rst

@@ -16,8 +16,6 @@ Welcome to Django Magic Notifier's documentation!
    usage
    autoapi/index
 
-
-
 Indices and tables
 ==================
 

docs/source/installation.rst

@@ -13,3 +13,19 @@ Git::
     > cd django-magic-notifier
     > python setup.py install
 
+
+If you intend to use Push notifications, then you need to include DMN
+consumers in your django channels routing
+
+Python::
+
+    application = ProtocolTypeRouter({
+        # Django's ASGI application to handle traditional HTTP requests
+        "http": django_asgi_app,
+
+        # WebSocket chat handler
+        "websocket": URLRouter([
+                    path("ws/notifications/<str:token>/", PushNotifConsumer.as_asgi()),
+                ])
+        }
+    )

docs/source/settings.rst

@@ -137,3 +137,7 @@ DMN needs a way to get a phone number from a User object. GET USER NUMBER must b
 one parameter of type User. Default **`'magic_notifer.utils.get_user_number'`**::
 
     'GET_USER_NUMBER': 'path.to.function'
+
+NOTIFIER PUSH SETTINGS
+======================
+

docs/source/templates.rst

@@ -13,8 +13,10 @@ folder created another folder like that **app_name/templates/notifier/hello**
 
 Now in this folder you have to create some files depending on how you will send your
 notifications. If you will send your notification via email then you must create
-two files within the hello folder named **email.html** and **email.txt**.
+two files within the hello folder named **email.html** and **email.txt** or **email.mjml**
+and **email**. Because DMN supports also mjml via 3rd party package.
 If you will send notifications via sms then you must create a file named **sms.txt**.
+If you want to send push notification then you must create a file **push.json**
 
 It is a common behavior to have a base template, you can do the same by creating a
 folder named **base** in the notifier folder and creating the files **email.html**,
@@ -35,6 +37,10 @@ at this example:
 
     {% extends "base_notifier/sms.txt" %}
 
+*app_name/templates/notifier/base/push.json*::
+
+    {% extends "base_notifier/push.json" %}
+
 
 Now in the hello template folder, you do:
 
@@ -50,15 +56,54 @@ Now in the hello template folder, you do:
 
 *app_name/templates/notifier/hello/email.txt*::
 
-    {% extends "notifier/hello/email.txt" %}
+    {% extends "notifier/base/email.txt" %}
     {% block content %}
     >Hello {{ user.email }}
     {% endblock %}
 
+*app_name/templates/notifier/hello/email.mjml*::
+
+    <mjml>
+      <mj-head>
+        <mj-attributes>
+          <mj-text align="center" color="#555" />
+        </mj-attributes>
+      </mj-head>
+      <mj-body background-color="#eee">
+        <mj-section>
+          <mj-column>
+            My Logo
+          </mj-column>
+        </mj-section>
+        <mj-section background-color="#fff">
+          <mj-column>
+            <mj-text align="center">
+              <h2>Welcome</h2>
+            </mj-text>
+            <mj-text>
+              Welcome to our company
+            </mj-text>
+          </mj-column>
+
+        </mj-section>
+        <mj-section>
+          <mj-column>
+            <mj-text> My Company </mj-text>
+            </mj-column>
+        </mj-section>
+      </mj-body>
+    </mjml>
+
+
 *app_name/templates/notifier/hello/sms.txt*::
 
-    {% extends "notifier/hello/sms.txt" %}
+    {% extends "notifier/base/sms.txt" %}
     {% block content %}
     >Hello {{ user.email }}
     {% endblock %}
 
+*app_name/templates/notifier/hello/push.json*::
+
+    {% extends "notifier/base/push.json" %}
+    {% block subject %}Hello {{ user.username }}{% endblock %}
+

docs/source/usage.rst

@@ -9,7 +9,7 @@ Send an email with a direct final string (no template) to a user instance::
     notify(["email"], subject, [user], final_message="Nice if you get this")
 
 
-Send an email with a template to a user instance::
+Send an email with a template (hello) to a user instance::
 
     user = User(email="testuser@localhost", username="testuser")
     subject = "Test magic notifier"
@@ -71,3 +71,9 @@ Send an email and sms with a template to all users excluding staff::
     user = User(email="testuser@localhost", username="testuser")
     subject = "Test magic notifier"
     notify(["email", 'sms'], subject, "all-staff", template='hello')
+
+Send an email, a sms and a push notification with a template to all users excluding staff::
+
+    user = User(email="testuser@localhost", username="testuser")
+    subject = "Test magic notifier"
+    notify(["email", 'sms', 'push'], subject, "all-staff", template='hello')

magic_notifier/pusher.py

@@ -7,7 +7,7 @@
 try:
     from asgiref.sync import async_to_sync
     from channels.layers import get_channel_layer
-except:
+except Exception:
     pass
 import json
 
@@ -22,6 +22,14 @@ class Pusher:
     def __init__(
         self, subject, receivers: list, template: str, context: dict, **kwargs
     ):
+        """
+
+        :param subject:The subject of the notification
+        :param receivers: The user list of receivers
+        :param template: The template to use
+        :param context:The context to pass to the template
+        :param kwargs:
+        """
         self.receivers: list = receivers
         self.template: str = template
         self.context: dict = context
@@ -74,7 +82,7 @@ def _send(self):
                 )
 
                 return res
-        except:
+        except Exception as e:
             logger.error(traceback.format_exc())