django email signals
v2.0.0
Una aplicación Django que proporciona funcionalidad para crear señales a través del panel de administración que enviará correos electrónicos basados en algunos cambios a algunos modelos.
La aplicación le permite establecer sus propias restricciones y plantillas de correo electrónico y tiene como objetivo lograr esto con una configuración mínima.
Los administradores pueden configurar señales/correos electrónicos.
Si un usuario administrador ha solicitado que se envíe un correo electrónico cuando algo sucede en la base de datos, ¿qué hacemos? Los desarrolladores creamos una nueva señal, establecemos cualquier restricción, creamos las plantillas de correo electrónico, reunimos todo, creamos pruebas unitarias y luego implementan. Relativamente simple, pero aún más tiempo, especialmente cuando hay varias señales para configurar varios cambios. Esto rápidamente se convierte en un proceso bastante largo.
Esta aplicación tiene como objetivo resolver esto proporcionando una forma para que los administradores creen estas señales ellos mismos en lugar de tener que solicitar la función y esperar la implementación. Esta es una excelente manera de aliviar la presión de los desarrolladores al tiempo que da a los administradores la capacidad de obtener resultados rápidamente.
¿Cómo sabría un administrador en qué campos ingresar para los parámetros? La aplicación valida el formulario antes de guardar, pero también proporciona autocompletar para los campos.
Prototipos y pruebas rápidamente de una plantilla de correo electrónico
La creación y prueba de plantillas para algunos equipos más grandes puede ser un proceso que requiere mucho tiempo. Esto es particularmente cierto cuando la solicitud es de alguien que, por cualquier razón, no puede ver su pantalla y se basa en que se implementa en un entorno de prueba para poder probar la plantilla.
El proceso puede volverse un poco tedioso. ¿Alguna vez ha estado en un escenario en el que implementa algún código para probar, que lo revise, tenga que ajustar algún código, volver a desplegarlo y repetir el proceso algunas veces?
Esta aplicación tiene como objetivo resolver esto proporcionando una forma para que los administradores creen el contenido HTML ellos mismos utilizando un editor de texto rico. Esto permite a los administradores prototipos y probar rápidamente el contenido de correo electrónico ellos mismos. Una vez listos, todo lo que necesitan hacer es hacer clic en "Mostrar código fuente" y enviarle ese dulce código fuente.
Imaginemos que queremos notificar a un equipo en particular cada vez que se realice un nuevo pedido en nuestro sitio web.
Comenzaríamos estableciendo la siguiente señal: 
En esta captura de pantalla notamos un par de cosas.
El modelo se ha establecido en "sample_app | orden". Para este ejemplo, hemos creado un modelo de pedido (se puede encontrar en example/sample_app/models.py ) y hemos establecido el tipo de señal para publicar guardar .
Esto significa que estamos creando una señal de guardado posterior en el modelo de pedido.
En este ejemplo, hemos ingresado valores para el texto sin formato y los campos de contenido HTML. Notará que al igual que lo hacemos con las plantillas, podemos agregar marcadores de posición para el contexto utilizando los aparatos ortopédicos.
Los hemos usado de la siguiente manera:
Order ID: {{ instance.id }}
Customer Name {{ instance.customer.id }}
Customer Email {{ instance.customer.email }} Como esta señal se relaciona con el modelo Order , instance representa una instancia Order único.
Cuando se envía el correo electrónico, los marcadores de posición serán reemplazados por los valores de contexto reales.
Es importante tener en cuenta que el único contexto disponible es instance , por lo que cualquier otro contexto debe ser accesible a través del objeto instance .
Esta es una forma de proporcionar contexto de plantilla. Si lo prefiere, puede proporcionar un valor para el campo de plantilla que es una ruta a un archivo de plantilla.
También podemos ver que hemos establecido una lista de correo en new_order_mailing_list . En nuestro modelo de pedido, tenemos un método referente new_order_mailing_list que devuelve una lista de correos electrónicos. Esto significa que este correo electrónico en particular se enviará a los correos electrónicos devueltos por Order.new_order_mailing_list . Al crear varios métodos que contienen diferentes listas de correos electrónicos, efectivamente tenemos una forma de crear diferentes listas de correo. Alternativamente, podemos usar una lista de correos electrónicos separados por comas para la lista de correo.
Antes de comenzar a agregar cualquier restricción, nose para guardar la señal. Esto facilitará la configuración de las restricciones de señal, ya que permitirá que la función de autocompletar nos ayude. Si está preocupado por el tiempo entre guardar la señal y configurar las restricciones de la señal, siempre puede configurar el indicador activo en falso de antemano. Esto evitará que se envíe cualquier correo electrónico.
Ahora podemos establecer las restricciones para la señal. Crearemos dos restricciones:
created == True ).customer.id > 10). 
Una verificación común al crear una señal post_save es verificar si la instancia es una nueva instancia. Esto se puede hacer configurando el parámetro en created y la comparación con "es verdadera".
Nuestro modelo de pedido tiene un campo customer que es una clave externa para el modelo customer . Podemos atravesar el objeto customer para obtener la id del cliente. Luego podemos verificar si customer.id > 10 .
La aplicación tiene una práctica característica de autocompletar que lo ayudará a atravesar los campos de modelos y cualquier propiedad en caché. No se preocupe por cometer errores, ya que existe una validación para rechazar los parámetros a los que no se puede acceder.
Guardar esta señal ahora asegurará que la señal solo se enviará cuando el pedido sea una nueva instancia y la ID del cliente sea mayor de 10.
Para instalar la aplicación, ejecute el siguiente comando:
pip install django-email-signals
El comando de instalación de PIP será todo lo que se requiere para la mayoría de las personas, sin embargo, si desea mirar debajo del capó y ver lo que está sucediendo, puede clonar el directorio de origen:
git clone https://github.com/Salaah01/django-email-signals.git
1. Agregue a INSTALLED_APPS i. Agregue Agregar tinymce a su INSTALLED_APPS en su archivo settings.py .
INSTALLED_APPS = [
' app_1 `,
' app_2 `,
'...' ,
'tinymce' ,
] II. Agregue email_signals a su INSTALLED_APPS en su archivo settings.py . Esto debe agregarse después de cualquier aplicación que contenga modelos para los cuales desea crear señales utilizando esta aplicación.
INSTALLED_APPS = [
' app_1 `,
' app_2 `,
'...' ,
'tinymce' ,
' email_signals `
]2. Ejecutar migraciones y recolectar estática
python manage.py migrate
python manage.py collectstatic
3. Actualizar URL (opcional) Actualice su archivo root urls.py para incluir lo siguiente:
from django . urls import include
url_patterns = [
path ( 'email-signals/' , include ( 'email_signals.urls' )),
path ( 'tinymce/' , include ( 'tinymce.urls' )),
]Recomendamos cambiar la URL a algo un poco más difícil de adivinar, solo para hacer la vida más difícil para esos molestos fisgones. Todas las rutas de aplicación requieren que el usuario sea un miembro del personal para poder acceder a los enlaces.
Aunque este paso es opcional, recomendamos hacerlo, ya que facilitará la configuración de las limitaciones en el área de administración. Las URL son necesarias para proporcionar un menú desplegable con opciones al construir sus restricciones.
4. Agregue un correo electrónico predeterminado (Opcional) Agregue EMAIL_SIGNAL_DEFAULT_SENDER a su configuración. por ejemplo: EMAIL_SIGNAL_DEFAULT_SENDER = '[email protected] Si no desea especificar explícitamente un correo electrónico de remitente para cada señal que define, puede configurar EMAIL_SIGNAL_DEFAULT_SENDER en su proyecto settings.py .
5. Agregue la mezcla del modelo en los modelos que desea elevar las señales, deberá agregar la siguiente mezcla como dependencia a los modelos: email_signals.models.EmailSignalMixin .
Ejemplo: supongamos que tiene el siguiente modelo.
from django . db import models
class Customer ( models . Model ):
name = models . CharField ( max_length = 200 , null = True )
email = models . CharField ( max_length = 200 )Debería cambiar este modelo a lo siguiente:
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. Agregue destinatarios dependiendo del cambio a los datos, es posible que desee enviar un correo electrónico a diferentes personas. Facilitamos esto configurando las diversas posibles listas de correo en el modelo en sí. Este es más fácil de mostrar primero y luego explicar:
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]' ] Hemos creado dos funciones llamadas customer_emails y management_mailing_list que devuelven una colección de direcciones de correo electrónico. Más adelante, cuando configuramos las señales, se nos pedirá que establezcamos la lista de correo para usar para cada señal. Aquí es donde ingresaríamos a nuestros nombres de funciones `` Customer_Emails or Management_Mailing_List`.
Por lo tanto, esto nos permite configurar diferentes listas de correo dentro de nuestros modelos.
Ahora que la configuración está completa, se pueden agregar señales a través del administrador (o actualizando la base de datos directamente).
Me imaginaremos que estoy ejecutando un sitio en localhost y, por lo tanto, el panel de administración se puede encontrar navegando a http: // localhost: 8000/admin/. Luego se puede acceder a las señales navegando a http: // localhost: 8000/admin/correo electrónico_signals/señal/. Comenzaremos agregando algunas señales. Haga clic en "Agregar señal" para comenzar.
Un hombre sabio me enseñó que es mejor sonar tonto por un momento que no saber algo y sentirse estúpido para siempre . Entonces, en ese sentido, aunque puede parecer obvio, pasaremos por las opciones en el formulario y discutiremos de qué es responsable cada opción.
| Etiqueta de campo | Nombre de campo | Descripción |
|---|---|---|
| Nombre | nombre | Un nombre para su señal, solo para facilitar la distinción de otros registros. |
| Descripción | descripción | (Opcional) Descripción para su señal. |
| Modelo (tabla) | content_type | Elija entre el modelo con el modelo con el que se relaciona esta señal. |
| Contenido de texto sin formato | Plain_message | (Opcional) Correo electrónico de texto sin formato para enviar. |
| Contenido HTML | html_message | (Opcional) Correo electrónico HTML para enviar. |
| Sujeto | sujeto | Asunto de correo electrónico |
| Desde el correo electrónico | from_email | (Opcional) El remitente de correo electrónico. Predeterminado a settings.EMAIL_SIGNAL_DEFAULT_SENDER . |
| Lista de correo | mailing_list | La lista de destinatarios donde ingresa, corresponde a un método llamado en la clase de modelo con el mismo nombre. Por ejemplo: si ingresa customer_mails , deberá haber un método llamado customer_mails que devuelva una colección de correos electrónicos en la clase de modelo. Alternativamente, esto puede ser una lista de correos electrónicos separados por una coma. EG: [email protected],[email protected] enviaría el correo electrónico a ambos correos electrónicos. |
| Plantilla | plantilla | (Opcional) Ruta a una plantilla, si desea realizar un correo electrónico de una plantilla. Esto utiliza el cargador de plantilla de Django, por lo que el valor que proporciona aquí debe ser relativo a settings.TEMPLATES[i]['DIRS'] . |
| Tipo de señal | Signal_Type | Tipo de señal para elevar para este registro. |
| Activo | activo | Un interruptor para encender y apagar esta señal. |
Restricciones de señal Este modelo en línea es donde puede establecer algunas restricciones que determinarán si la señal debe plantearse caso por caso.
| Etiqueta de campo | Nombre de campo | Descripción |
|---|---|---|
| Parámetro 1 | Param_1 | El primer parámetro a usar al probar una restricción. Este parámetro debe existir en la señal KWARGS o en la instancia del modelo. |
| Comparación | comparación | Defina cómo comparar los parámetros. Por ejemplo: el parámetro 1 es mayor que el parámetro 2. |
| Parámetro 1 | Param_1 | (Opcional) El segundo parámetro a usar al probar una restricción. Este parámetro se puede dejar vacío cuando la restricción es algo sensible. Por ejemplo, si la restricción es "verdadera", entonces no hay necesidad de parámetro 2. Pero si la restricción es "mayor que", entonces se necesita el parámetro 2. El parámetro 2 también puede ser un tipo primitivo como 'A', '1', '1.1'. La aplicación intentará convertir las cadenas en números si puede. |
Los parámetros son profundos , los parámetros 1 y 2 le permiten buscar en el fondo de un objeto. Supongamos que tenemos la siguiente estructura y señal que ha recibido una instancia CustomerOrder .
classdiagram
Usuario <| -- Cliente
Cliente <| - ClustOrder
Usuario de clase {
identificación
nombre de pila
apellido
correo electrónico
}
Cliente de clase {
identificación
usuario
fav_language
}
Clase CustomerOrder {
identificación
cliente
orden_id
total
}
Dada una instancia CustomerOrder (llamaremos a este order variable), podemos establecer lo siguiente en nuestras restricciones:
| # | Parámetro 1 | Comparación | Parámetro 2 |
|---|---|---|---|
| 1 | 'customer.user.id' | Más que | '5' |
| 2 | 'customer.user.first_name' | Igual a | 'customer.user.last_name' |
La restricción 1 verificará lo siguiente:
order . customer . user . id > 5Del mismo modo, la restricción 2 verificará lo siguiente:
order . customer . user . first_name == order . customer . user . last_nameSolo cuando todas las restricciones estén satisfechas se enviará el correo electrónico.
El repositorio viene con un proyecto de ejemplo para comenzar. Si prefiere probar esta aplicación usted mismo, le recomiendo clonar el repositorio.
Navegar al example y ejecutar el proyecto Django adentro.
Si tiene alguna sugerencia o mejoras, no dude en abrir un problema o extraer una solicitud.
Si desea contribuir con código, siga los siguientes pasos:
npm install para instalar las dependencias para el proyecto de ejemplonpm start para iniciar el servidor Webpack Dev. Esto vigilará los cambios y recompilará los archivos. De lo contrario, ejecute npm run build para compilar los archivos una vez.Al contribuir, asegúrese de haber agregado pruebas para sus cambios y que todas sus pruebas pasen (consulte las pruebas). También asegúrese de que su código esté formateado correctamente y que su código pase la pelusa.
Usamos black y flake8 para formatear y pelear nuestro código. Si ha make , puede ejecutar lo siguiente para formatear y vincular su código:
make format
make lintAlternativamente, puede ejecutar los siguientes comandos:
black email_signals
flake8 --exclude=migrations email_signals Este repositorio usa tox para ejecutar pruebas en múltiples versiones de Python y Django. Si ha make , simplemente puede ejecutar las pruebas ejecutando make tox . De lo contrario, puede ejecutar las pruebas ejecutando tox -s en la raíz del repositorio.
Si desea ejecutar las pruebas solo para su versión actual de Python, puede ejecutar tox -e py o python3 runtests.py .
