django email signals
v2.0.0
Um aplicativo Django que fornece funcionalidade para criar sinais através do painel de administração, que enviará emails com base em algumas alterações para alguns modelos.
O aplicativo permite definir suas próprias restrições e modelos de email e visa conseguir isso com a configuração mínima.
Administradores são capazes de configurar sinais/e -mails
Se um usuário administrador solicitou que um email fosse enviado quando algo acontecer no banco de dados, o que fazemos? Nós, desenvolvedores, criamos um novo sinal, definem quaisquer restrições, criamos os modelos de email, juntam tudo, criamos testes de unidade e implantam. Relativamente simples, mas ainda demorado, especialmente quando há vários sinais para configurar para várias alterações. Isso rapidamente se torna um processo bastante longo.
Este aplicativo tem como objetivo resolver isso, fornecendo uma maneira de os administradores criarem esses sinais em vez de precisar solicitar o recurso e aguardar a implantação. Essa é uma ótima maneira de aliviar a pressão dos desenvolvedores, dando aos administradores a capacidade de obter resultados rapidamente.
Como um administrador saberia quais campos entrar para os parâmetros? O aplicativo valida o formulário antes de salvar, mas também fornece preenchimento automático para os campos.
Prototipando rapidamente e testando um modelo de e -mail
Criar e testar modelos para algumas equipes maiores pode ser um processo demorado. Isso é particularmente verdadeiro quando a solicitação é de alguém que, por qualquer motivo, não pode visualizar sua tela e depende de você implantar em um ambiente de teste para poder testar o modelo.
O processo pode se tornar um pouco tedioso. Já esteve em um cenário em que você implanta algum código para testar, revisá -lo, tem que ajustar algum código, reimpleê -lo e repetir o processo algumas vezes?
Este aplicativo tem como objetivo resolver isso, fornecendo uma maneira de os administradores criarem o conteúdo HTML usando um editor de texto rico. Isso permite que os administradores prototipem rapidamente e testem o conteúdo do email. Uma vez pronto, tudo o que eles precisam fazer é clicar em "Mostrar código -fonte" e enviar esse código -fonte doce para você.
Vamos imaginar que queremos notificar uma equipe específica sempre que um novo pedido for feito em nosso site.
Começaríamos definindo o seguinte sinal: 
Nesta captura de tela, notamos algumas coisas.
O modelo foi definido como "sample_app | order". Para este exemplo, criamos um modelo de pedido (pode ser encontrado no example/sample_app/models.py ) e definimos o tipo de sinal para postar salvar .
Isso significa que estamos criando um sinal de pós -salvamento no modelo de pedido.
Neste exemplo, inserimos valores para os campos de conteúdo de texto simples e HTML. Você notará que, assim como fazemos com modelos, somos capazes de adicionar espaço reservado para contexto usando os aparelhos encaracolados.
Nós os usamos da seguinte maneira:
Order ID: {{ instance.id }}
Customer Name {{ instance.customer.id }}
Customer Email {{ instance.customer.email }} Como esse sinal se relaciona com o modelo Order , instance representa uma única instância Order .
Quando o email for enviado, os espaços reservados serão substituídos pelos valores reais do contexto.
É importante observar que o único contexto disponível é instance e, portanto, qualquer outro contexto deve estar acessível através do objeto de instance .
Esta é uma maneira de fornecer contexto de modelo. Se você preferir, você poderá fornecer um valor para o campo de modelo , que é um caminho para um arquivo de modelo.
Também podemos ver que definimos a lista de correspondência para new_order_mailing_list . Em nosso modelo de pedido, temos um método new_order_mailing_list correspondente que retorna uma lista de emails. Isso significa que este email específico será enviado aos emails retornados pelo Order.new_order_mailing_list . Ao criar vários métodos contendo diferentes listas de e -mails, efetivamente temos uma maneira de criar diferentes listas de discussão. Como alternativa, podemos apenas usar uma lista de e -mails separados por vírgula para a lista de discussão.
Antes de começarmos a adicionar restrições, precisamos salvar o sinal. Isso facilitará as restrições de sinal de configuração, pois permitirá que o recurso de preenchimento automático nos ajude. Se você estiver preocupado com o tempo entre salvar o sinal e definir as restrições de sinal, sempre poderá definir o sinalizador ativo como false antes. Isso impedirá que qualquer email seja enviado.
Agora podemos definir as restrições para o sinal. Vamos criar duas restrições:
created == True ).customer.id > 10). 
Uma verificação comum ao criar um sinal post_save é verificar é que a instância é uma nova instância. Isso pode ser feito definindo o parâmetro created e a comparação com "é verdadeira".
Nosso modelo de pedido possui um campo customer , que é uma chave estrangeira para o modelo customer . Podemos atravessar o objeto customer para obter o id do cliente. Podemos então verificar se customer.id > 10 .
O aplicativo possui um recurso útil de preenchimento automático que o ajudará a atravessar os campos modelo e quaisquer propriedades em cache. Não se preocupe em cometer erros, pois há validação para rejeitar qualquer parâmetros que não possam ser acessados.
Salvar esse sinal agora garantirá que o sinal seja enviado apenas quando o pedido for uma nova instância e o ID do cliente for maior que 10.
Para instalar o aplicativo, execute o seguinte comando:
pip install django-email-signals
O comando PIP Install será tudo o que é necessário para a maioria das pessoas; no entanto, se você quiser olhar sob o capô e ver o que está acontecendo, poderá clonar o diretório de origem:
git clone https://github.com/Salaah01/django-email-signals.git
1. Adicione a INSTALLED_APPS i. Adicione Adicionar tinymce ao seu INSTALLED_APPS no seu arquivo settings.py .
INSTALLED_APPS = [
' app_1 `,
' app_2 `,
'...' ,
'tinymce' ,
] ii. Adicione email_signals ao seu INSTALLED_APPS no seu arquivo settings.py . Isso deve ser adicionado após qualquer aplicativo que contenha modelos para os quais você deseja criar sinais usando este aplicativo.
INSTALLED_APPS = [
' app_1 `,
' app_2 `,
'...' ,
'tinymce' ,
' email_signals `
]2. Execute migrações e colete estático
python manage.py migrate
python manage.py collectstatic
3. URLs de atualização (opcional) Atualize seu arquivo root urls.py para incluir o seguinte:
from django . urls import include
url_patterns = [
path ( 'email-signals/' , include ( 'email_signals.urls' )),
path ( 'tinymce/' , include ( 'tinymce.urls' )),
]Recomendamos mudar o URL para algo um pouco mais difícil de adivinhar, apenas para tornar a vida mais difícil para aqueles bosques irritantes. Todos os caminhos do aplicativo exigem que o usuário seja um membro da equipe para poder acessar os links.
Embora essa etapa seja opcional, recomendamos fazê -lo, pois facilitará muito a configuração de restrições na área de administrador. Os URLs são necessários para fornecer uma suspensão com opções ao criar suas restrições.
4. Adicione um email padrão (opcional) Adicione EMAIL_SIGNAL_DEFAULT_SENDER às suas configurações. Por exemplo: EMAIL_SIGNAL_DEFAULT_SENDER = '[email protected] Se você não quiser especificar explicitamente um email do remetente para cada sinal que você definir, você pode definir EMAIL_SIGNAL_DEFAULT_SENDER em seu projeto settings.py .
5. Adicione o modelo Mixin nos modelos que você deseja aumentar os sinais, você precisará adicionar o seguinte mixin como uma dependência aos modelos: email_signals.models.EmailSignalMixin .
Exemplo: vamos supor que você tenha o seguinte modelo.
from django . db import models
class Customer ( models . Model ):
name = models . CharField ( max_length = 200 , null = True )
email = models . CharField ( max_length = 200 )Você precisaria alterar este modelo para o seguinte:
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. Adicione os destinatários, dependendo da alteração dos dados, você pode enviar um email para pessoas diferentes. Facilitamos isso configurando as várias listas de discussão possíveis no próprio modelo. Este é mais fácil de mostrar primeiro do que 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]' ] Criamos duas funções chamadas customer_emails e management_mailing_list , que retornam uma coleção de endereços de email. Posteriormente, quando configuramos os sinais, seremos solicitados a definir a lista de discussão para cada sinal. É aqui que inseriríamos nossos nomes de funções `` Customer_Emails or Management_mailing_list`.
Portanto, isso nos permite configurar diferentes listas de discussão em nossos modelos.
Agora que a configuração está concluída, os sinais podem ser adicionados através do administrador (ou atualizando diretamente o banco de dados).
Imaginaremos que estou executando um site no host local e, portanto, o painel de administrador pode ser encontrado navegando para http: // localhost: 8000/admin/. Os sinais podem então ser acessados navegando para http: // localhost: 8000/admin/email_signals/signal/. Começaremos adicionando alguns sinais. Clique em "Adicionar sinal" para começar.
Um homem sábio me ensinou que é melhor parecer bobo por um momento do que não saber algo e me sentir estúpido para sempre . Portanto, nesse sentido, embora possa parecer óbvio, examinaremos as opções no formulário e discutiremos o que cada opção é responsável.
| Etiqueta de campo | Nome do campo | Descrição |
|---|---|---|
| Nome | nome | Um nome para o seu sinal, apenas para facilitar a distinção de outros registros. |
| Descrição | descrição | (Opcional) Descrição do seu sinal. |
| Modelo (tabela) | Content_type | Escolha entre a queda do modelo em que esse sinal se relaciona. |
| Conteúdo de texto simples | Plain_Message | (Opcional) Email de texto simples para enviar. |
| Conteúdo HTML | html_message | (Opcional) email HTML para enviar. |
| Assunto | assunto | Assunto do e -mail |
| Do email | From_Email | (Opcional) O remetente de email. Padrões para settings.EMAIL_SIGNAL_DEFAULT_SENDER . |
| Lista de correspondência | Mailing_List | A lista de destinatários em que o texto inserido corresponde a um método chamado na classe Model com o mesmo nome. Por exemplo: se você inserir customer_mails , precisará haver um método chamado customer_mails que retorne uma coleção de e -mails na classe Model. Como alternativa, isso pode ser uma lista de e -mails separados por uma vírgula. Por exemplo: [email protected],[email protected] enviaria o email para esses dois e -mails. |
| Modelo | modelo | (Opcional) Caminho para um modelo, se você deseja renderizar um email de um modelo. Isso usa o carregador de modelo do Django, portanto, como o valor que você fornece aqui, deve ser relativo às settings.TEMPLATES[i]['DIRS'] . |
| Tipo de sinal | Signal_type | Tipo de sinal para aumentar para este registro. |
| Ativo | ativo | Uma mudança para ligar e desativar esse sinal. |
Restrições de sinal Este modelo embutido é onde você pode definir algumas restrições que determinarão se o sinal deve ser aumentado caso a caso.
| Etiqueta de campo | Nome do campo | Descrição |
|---|---|---|
| Parâmetro 1 | param_1 | O primeiro parâmetro a ser usado ao testar uma restrição. Este parâmetro deve existir nos Kwargs de sinal ou na instância do modelo. |
| Comparação | comparação | Defina como comparar os parâmetros. Por exemplo: o parâmetro 1 é maior que o parâmetro 2. |
| Parâmetro 1 | param_1 | (Opcional) O segundo parâmetro a ser usado ao testar uma restrição. Este parâmetro pode ser deixado vazio quando a restrição é algo sensata. Por exemplo, se a restrição for "for verdadeira", não há necessidade de parâmetro 2. Mas se a restrição for "maior que", o parâmetro 2 será necessário. O parâmetro 2 também pode ser um tipo primitivo, como 'a', '1', '1.1'. O aplicativo tentará converter strings em números, se puder. |
Os parâmetros são profundos , os parâmetros 1 e 2 permitem pesquisar profundamente dentro de um objeto. Suponhamos que tenhamos a seguinte estrutura e sinal recebeu uma instância CustomerOrder .
ClassDiagram
Usuário <| -- Cliente
Cliente <| - CustomerOrder
classe de usuário {
eu ia
primeiro nome
sobrenome
e-mail
}
CLIENTE CLIENTE {
eu ia
usuário
fav_language
}
classe CustomerOrder {
eu ia
cliente
order_id
total
}
Dada uma instância CustomerOrder (chamaremos esse order de variável), podemos definir o seguinte em nossas restrições:
| # | Parâmetro 1 | Comparação | Parâmetro 2 |
|---|---|---|---|
| 1 | 'customer.user.id' | Maior que | '5' |
| 2 | 'customer.user.first_name' | Igual a | 'customer.user.last_name' |
Restrição 1 verificará o seguinte:
order . customer . user . id > 5Da mesma forma, a restrição 2 verificará o seguinte:
order . customer . user . first_name == order . customer . user . last_nameSomente quando todas as restrições estiverem satisfeitas, o email será enviado.
O repositório vem com um projeto de exemplo para você começar. Se você preferir testar este aplicativo, recomendo clonar o repositório.
Navegando para o example e executando o projeto Django dentro.
Se você tiver alguma sugestão ou melhorias, sinta -se à vontade para abrir um problema ou puxar a solicitação.
Se você deseja contribuir com código, siga as seguintes etapas:
npm install para instalar as dependências para o projeto de exemplonpm start a iniciar o servidor Webpack Dev. Isso deve procurar alterações e recompilar os arquivos. Caso contrário, execute npm run build para compilar os arquivos uma vez.Ao contribuir, verifique se você adicionou testes para suas alterações e que todos os seus testes passem (consulte os testes). Certifique -se também que seu código seja formatado corretamente e que seu código passa por linha.
Usamos black e flake8 para formatar e fiar nosso código. Se você make instalar, pode executar o seguinte para formatar e fingir seu código:
make format
make lintComo alternativa, você pode executar os seguintes comandos:
black email_signals
flake8 --exclude=migrations email_signals Este repositório usa tox para executar testes contra várias versões de Python e Django. Se você make instalado, basta executar os testes executando make tox . Caso contrário, você pode executar os testes executando tox -s na raiz do repositório.
Se você deseja executar os testes apenas para sua versão python atual, você pode executar tox -e py ou python3 runtests.py .
