django email signals
v2.0.0
Une application Django qui fournit des fonctionnalités pour créer des signaux via le panneau d'administration qui enverra des e-mails en fonction de certaines modifications à certains modèles.
L'application vous permet de définir vos propres contraintes et modèles de messagerie et vise à y parvenir avec une configuration minimale.
Les administrateurs peuvent configurer eux-mêmes des signaux / e-mails
Si un utilisateur d'administration a demandé qu'un e-mail soit envoyé lorsque quelque chose se produit dans la base de données, que faisons-nous? Nous, les développeurs, créons un nouveau signal, définissons toutes les contraintes, créons les modèles d'e-mail, éperons tout ensemble, créent des tests unitaires puis déploient. Relativement simple, mais toujours chronophage, surtout lorsqu'il existe plusieurs signaux à configurer pour divers changements. Cela devient rapidement un processus assez long.
Cette application vise à résoudre ce problème en fournissant aux administrateurs un moyen de créer eux-mêmes ces signaux plutôt que d'avoir à demander la fonctionnalité et à attendre le déploiement. C'est un excellent moyen de faciliter la pression des développeurs tout en donnant aux administrateurs la possibilité d'obtenir des résultats rapidement.
Comment un administrateur savait-il quels champs entrer pour les paramètres? L'application valide le formulaire avant l'enregistrement mais fournit également une saisie semi-automatique pour les champs.
Prototypage et tester rapidement un modèle de messagerie
La création et le test de modèles pour certaines équipes plus grandes peuvent être un processus long. Cela est particulièrement vrai lorsque la demande provient de quelqu'un qui, pour une raison quelconque, ne peut pas afficher votre écran et s'appuie sur votre déploiement dans un environnement de test pour pouvoir tester le modèle.
Le processus peut alors devenir un peu fastidieux. Avez-vous déjà été dans un scénario où vous déployez un code pour tester, l'avoir examiné, devoir modifier un code, le redéployer et faire répéter le processus plusieurs fois?
Cette application vise à résoudre ce problème en fournissant aux administrateurs un moyen de créer le contenu HTML eux-mêmes en utilisant un éditeur de texte riche. Cela permet aux administrateurs de prototyper rapidement et de tester le contenu e-mail eux-mêmes. Une fois prêt, tout ce qu'ils ont à faire est de cliquer sur "Afficher le code source" et vous envoyer ce doux code source.
Imaginons que nous voulons informer une équipe particulière chaque fois qu'une nouvelle commande est passée sur notre site Web.
Nous commencerions par définir le signal suivant: 
Dans cette capture d'écran, nous remarquons quelques choses.
Le modèle a été défini sur "Sample_App | Order". Pour cet exemple, nous avons créé un modèle de commande (peut être trouvé dans example/sample_app/models.py ) et nous avons défini le type de signal pour publier une sauvegarde .
Cela signifie que nous créons un signal postal sur le modèle de commande.
Dans cet exemple, nous avons entré des valeurs pour les champs de contenu en texte brut et HTML. Vous remarquerez que, tout comme nous le faisons avec les modèles, nous pouvons ajouter des espaces réservés pour le contexte à l'aide des accolades bouclées.
Nous les avons utilisés de la manière suivante:
Order ID: {{ instance.id }}
Customer Name {{ instance.customer.id }}
Customer Email {{ instance.customer.email }} Comme ce signal se rapporte au modèle Order , instance représente une instance Order unique.
Lorsque l'e-mail est envoyé, les espaces réservés seront remplacés par les valeurs de contexte réelles.
Il est important de noter que le seul contexte disponible est instance , et donc tout autre contexte doit être accessible via l'objet instance .
C'est une façon de fournir un contexte de modèle. Si vous préférez, vous pouvez plutôt fournir une valeur pour le champ de modèle qui est un chemin d'accès à un fichier de modèle.
Nous pouvons également voir que nous avons défini la liste de diffusion sur new_order_mailing_list . Dans notre modèle de commande, nous avons une méthode new_order_mailing_list correspondante qui renvoie une liste des e-mails. Cela signifie que cet e-mail particulier sera envoyé aux e-mails renvoyés par Order.new_order_mailing_list . En créant différentes méthodes contenant différentes listes de courriels, nous avons efficacement un moyen de créer différentes listes de diffusion. Alternativement, nous pouvons simplement utiliser une liste d'e-mails séparés par des virgules pour la liste de diffusion.
Avant de commencer à ajouter des contraintes, nous n'avons pas pour enregistrer le signal. Cela facilitera les contraintes de signal de réglage car cela permettra à la fonction d'assomption automatique de nous aider. Si vous vous inquiétez du temps entre la sauvegarde du signal et la définition des contraintes de signal, vous pouvez toujours définir l'indicateur actif sur False au préalable. Cela empêchera l'envoi de tout e-mail.
Nous pouvons maintenant définir les contraintes du signal. Nous créerons deux contraintes:
created == True ).customer.id > 10). 
Une vérification courante lors de la création d'un signal post_save est que l'instance est une nouvelle instance. Cela peut être fait en définissant le paramètre à created et la comparaison avec "est vrai".
Notre modèle de commande a un champ customer qui est une clé étrangère du modèle customer . Nous pouvons traverser l'objet customer pour obtenir l' id du client. Nous pouvons ensuite vérifier si customer.id > 10 .
L'application dispose d'une fonctionnalité d'assiette pratique qui vous aidera à traverser les champs de modèle et toutes les propriétés mises en cache. Ne vous inquiétez pas de faire des erreurs car la validation est en place pour rejeter les paramètres qui ne sont pas accessibles.
L'enregistrement de ce signal garantira désormais que le signal ne sera envoyé que lorsque la commande est une nouvelle instance et que l'ID client est supérieur à 10.
Pour installer l'application, exécutez la commande suivante:
pip install django-email-signals
La commande PIP d'installation sera tout ce qui est nécessaire pour la plupart des gens, mais si vous voulez regarder sous le capot et voir ce qui se passe, vous pouvez cloner le répertoire source:
git clone https://github.com/Salaah01/django-email-signals.git
1. Ajouter à INSTALLED_APPS i. Ajoutez Ajouter tinymce à votre fichier INSTALLED_APPS dans votre fichier settings.py .
INSTALLED_APPS = [
' app_1 `,
' app_2 `,
'...' ,
'tinymce' ,
] ii Ajoutez email_signals à votre fichier INSTALLED_APPS dans votre fichier settings.py . Cela devrait être ajouté après toutes les applications contenant des modèles pour lesquels vous souhaitez créer des signaux à l'aide de cette application.
INSTALLED_APPS = [
' app_1 `,
' app_2 `,
'...' ,
'tinymce' ,
' email_signals `
]2. Exécuter les migrations et collecter des
python manage.py migrate
python manage.py collectstatic
3. Mettre à jour les URL (facultatif) Mettez à jour votre fichier racine urls.py pour inclure les éléments suivants:
from django . urls import include
url_patterns = [
path ( 'email-signals/' , include ( 'email_signals.urls' )),
path ( 'tinymce/' , include ( 'tinymce.urls' )),
]Nous vous recommandons de changer l'URL en quelque chose d'un peu plus difficile à deviner, juste pour rendre la vie plus difficile pour ces snoopers embêtants. Les chemins d'application nécessitent tous que l'utilisateur soit un membre du personnel pour pouvoir accéder aux liens.
Bien que cette étape soit facultative, nous vous recommandons de le faire car elle facilitera les contraintes de réglage dans la zone d'administration. Les URL sont nécessaires pour fournir une liste déroulante avec des options lors de la construction de vos contraintes.
4. Ajouter un e-mail par défaut (facultatif) Ajouter EMAIL_SIGNAL_DEFAULT_SENDER à vos paramètres. Par exemple: EMAIL_SIGNAL_DEFAULT_SENDER = '[email protected] Si vous ne souhaitez pas spécifier explicitement un e-mail de l'expéditeur pour chaque signal que vous définissez, vous pouvez définir EMAIL_SIGNAL_DEFAULT_SENDER dans votre projet settings.py .
5. Ajouter le mixin de modèle sur les modèles que vous souhaitez soulever des signaux, vous devrez ajouter le mixin suivant comme dépendance aux modèles: email_signals.models.EmailSignalMixin .
Exemple: Supposons que vous ayez le modèle suivant.
from django . db import models
class Customer ( models . Model ):
name = models . CharField ( max_length = 200 , null = True )
email = models . CharField ( max_length = 200 )Vous auriez besoin de changer ce modèle à ce qui suit:
from email_signals . models import EmailSignalMixin
class Customer ( models . Model , EmailSignalMixin ):
name = models . CharField ( max_length = 200 , null = True )
email = models . CharField ( max_length = 200 )6. Ajouter les destinataires en fonction de la modification des données, vous pouvez envoyer un e-mail à différentes personnes. Nous facilitons cela en configurant les différentes listes de diffusion possibles dans le modèle lui-même. Celui-ci est plus facile à montrer d'abord, puis à expliquer:
from email_signals . models import EmailSignalMixin
class Customer ( models . Model , EmailSignalMixin ):
name = models . CharField ( max_length = 200 , null = True )
email = models . CharField ( max_length = 200 )
def customer_emails ( self ):
"""Recipient is the customer."""
return [ self . email ]
def management_mailing_list ( self ):
"""Recipient list includes management."""
return [ '[email protected]' , '[email protected]' ] Nous avons créé deux fonctions appelées customer_emails et management_mailing_list qui renvoient chacune une collection d'adresses e-mail. Plus tard, lorsque nous avons configuré les signaux, nous serons invités à définir la liste de diffusion à utiliser pour chaque signal. C'est là que nous entrions nos noms de fonction `` Customer_Emails or Management_Mailing_List`.
Ceci nous permet donc de configurer différentes listes de diffusion au sein de nos modèles.
Maintenant que la configuration est terminée, des signaux peuvent être ajoutés via l'administrateur (ou en mettant directement la base de données directement).
Nous imaginons que je gère un site sur localhost et le panneau d'administration peut donc être trouvé en naviguant vers http: // localhost: 8000 / admin /. Les signaux sont ensuite accessibles en naviguant vers http: // localhost: 8000 / admin / email_signals / signal /. Nous allons commencer par ajouter des signaux. Cliquez sur "Ajouter un signal" pour commencer.
Un homme sage m'a appris qu'il vaut mieux sembler idiot un instant que de ne pas savoir quelque chose et de me sentir stupide pour toujours . Donc, dans cette veine, bien que cela puisse sembler évident, nous allons passer par les options sous la forme et discuter de ce dont chaque option est responsable.
| Étiquette de terrain | Nom de champ | Description |
|---|---|---|
| Nom | nom | Un nom pour votre signal, juste pour faciliter la distinction des autres enregistrements. |
| Description | description | (Facultatif) Description de votre signal. |
| Modèle (tableau) | contenu_type | Choisissez parmi la liste déroulante le modèle auquel ce signal se rapporte. |
| Contenu en texte brut | plain_message | (Facultatif) Email de texte brut à envoyer. |
| Contenu HTML | HTML_MESSAGE | (Facultatif) Email HTML à envoyer. |
| Sujet | sujet | Sujet par e-mail |
| De l'e-mail | de_email | (Facultatif) l'expéditeur de messagerie. Par défaut à settings.EMAIL_SIGNAL_DEFAULT_SENDER . |
| Liste de diffusion | Mailing_list | La liste des destinataires où le texte que vous entrez correspond à une méthode appelée dans la classe de modèle avec le même nom. EG: Si vous entrez customer_mails , il devra y avoir une méthode appelée customer_mails qui renvoie une collection d'e-mails dans la classe de modèle. Alternativement, cela peut être une liste d'e-mails séparés par une virgule. Par exemple: [email protected],[email protected] enverrait l'e-mail à ces deux e-mails. |
| Modèle | modèle | (Facultatif) Chemin vers un modèle, si vous souhaitez rendre un e-mail à partir d'un modèle. Cela utilise le chargeur de modèle de Django, de sorte que la valeur que vous fournissez ici doit être relative aux settings.TEMPLATES[i]['DIRS'] |
| Type de signal | signal_type | Type de signal à augmenter pour cet enregistrement. |
| Actif | actif | Un interrupteur pour activer et désactiver ce signal. |
Contraintes de signal Ce modèle en ligne est l'endroit où vous pouvez définir certaines contraintes qui détermineront si le signal doit être soulevé au cas par cas.
| Étiquette de terrain | Nom de champ | Description |
|---|---|---|
| Paramètre 1 | param_1 | Le premier paramètre à utiliser lors du test d'une contrainte. Ce paramètre doit exister dans le signal KWARGS ou l'instance de modèle. |
| Comparaison | comparaison | Définissez comment comparer les paramètres. Par exemple: le paramètre 1 est supérieur au paramètre 2. |
| Paramètre 1 | param_1 | (Facultatif) Le deuxième paramètre à utiliser lors du test d'une contrainte. Ce paramètre peut être laissé vide lorsque la contrainte est quelque chose de sensible. Par exemple, si la contrainte est "est vraie", il n'y a pas besoin du paramètre 2. Mais si la contrainte est "supérieure à", alors le paramètre 2 est nécessaire. Le paramètre 2 peut également être un type primitif tel que «A», «1», «1.1». L'application tentera de convertir les chaînes en nombres si elle le peut. |
Les paramètres sont profonds, les deux paramètres 1 et 2 vous permettent de rechercher profondément à l'intérieur d'un objet. Supposons que nous ayons la structure et le signal suivant ont reçu une instance CustomerOrder .
diagramme de classe
Utilisateur <| -- Client
Client <| - Ordre de clientèle
classe utilisateur {
identifiant
prénom
nom de famille
e-mail
}
classe Client {
identifiant
utilisateur
fav_language
}
Class CustomerOrder {
identifiant
client
order_id
total
}
Compte tenu d'une instance CustomerOrder (nous appellerons cette order variable), nous pouvons définir ce qui suit dans nos contraintes:
| # | Paramètre 1 | Comparaison | Paramètre 2 |
|---|---|---|---|
| 1 | 'customer.user.id' | Supérieur à | '5' |
| 2 | 'customer.user.first_name' | Égal à | 'customer.user.last_name' |
La contrainte 1 vérifiera ce qui suit:
order . customer . user . id > 5De même, la contrainte 2 vérifiera ce qui suit:
order . customer . user . first_name == order . customer . user . last_nameCe n'est que lorsque toutes les contraintes seront satisfaites que l'e-mail sera envoyé.
Le référentiel est livré avec un exemple de projet pour vous aider à démarrer. Si vous préférez tester cette application vous-même, je recommande de cloner le référentiel.
Naviguer à l' example et exécuter le projet Django à l'intérieur.
Si vous avez des suggestions ou des améliorations, n'hésitez pas à ouvrir une demande de problème ou de traction.
Si vous souhaitez contribuer du code, veuillez suivre les étapes suivantes:
npm install pour installer les dépendances pour l'exemple de projetnpm start pour démarrer le serveur de développement WebPack. Cela surveillera les modifications et recompilera les fichiers. Sinon, exécutez npm run build pour compiler les fichiers une fois.Lorsque vous contribuez, veuillez vous assurer que vous avez ajouté des tests pour vos modifications et que tous vos tests passent (voir les tests). Veuillez également vous assurer que votre code est formaté correctement et que votre code passe libellé.
Nous utilisons black et flake8 pour formater et peindre notre code. Si vous avez make , vous pouvez exécuter ce qui suit pour formater et peluchez votre code:
make format
make lintAlternativement, vous pouvez exécuter les commandes suivantes:
black email_signals
flake8 --exclude=migrations email_signals Ce référentiel utilise tox pour exécuter des tests contre plusieurs versions de Python et Django. Si vous avez make , vous pouvez simplement exécuter les tests en exécutant make tox . Sinon, vous pouvez exécuter les tests en exécutant tox -s à la racine du référentiel.
Si vous souhaitez exécuter les tests pour votre version Python actuelle uniquement, vous pouvez exécuter tox -e py ou python3 runtests.py .
