download mail_form - download do código-fonte mail

mail_form

Outro código-fonte

v1.10.1

Baixar

Formulário de correio

Trilhos 5

Esta joia foi construída sobre o ActiveModel para mostrar como você pode extrair validações, nomenclatura e i18n do Rails para seus modelos sem a necessidade de implementar tudo sozinho.

Este README refere-se à gem MailForm a ser usada no Rails 5+. Para obter instruções sobre como usar MailForm em versões mais antigas do Rails, consulte os ramos disponíveis.

Descrição

MailForm permite enviar um e-mail diretamente de um formulário. Por exemplo, se você quiser fazer um formulário de contato bastam as seguintes linhas (incluindo o e-mail):

 class ContactForm < MailForm :: Base
  attribute :name , validate : true
  attribute :email , validate : / A [^@ s ]+@[^@ s ]+ z /i
  attribute :file , attachment : true

  attribute :message
  attribute :nickname , captcha : true

  # Declare the e-mail headers. It accepts anything the mail method
  # in ActionMailer accepts.
  def headers
    {
      subject : "My Contact Form" ,
      to : "[email protected]" ,
      from : %(" #{ name } " < #{ email } >)
    }
  end
end

Então você inicia um console com rails console e digita:

>> c = ContactForm . new ( name : 'José' , email : '[email protected]' , message : 'Cool!' )
>> c . deliver

Verifique sua caixa de entrada e o e-mail estará lá, com os campos de envio (supondo que você configurou corretamente o método de entrega do mailer).

MailForm::Base

Quando você herda de MailForm::Base , ele extrai um conjunto de coisas de ActiveModel , como ActiveModel::Validation , ActiveModel::Translation e ActiveModel::Naming .

Isso traz I18n , mensagens de erro, validações e manipulação de atributos como no ActiveRecord para MailForm , para que MailForm possa ser usado em seus controladores e construtores de formulários sem ajustes extras. Isso também significa que, em vez do seguinte:

 attribute :email , validate : / A [^@ s ]+@[^@ s ]+ z /i

Você poderia realmente fazer isso:

 attribute :email
validates_format_of :email , with : / A [^@ s ]+@[^@ s ]+ z /i

Escolha aquele que mais lhe agrada. Para obter mais informações sobre a API, continue lendo abaixo.

Jogando juntos ORMs

MailForm também funciona bem com ORMs. Basta incluir MailForm::Delivery no seu model e declarar quais atributos devem ser enviados:

 class User < ActiveRecord :: Base
  include MailForm :: Delivery

  append :remote_ip , :user_agent , :session
  attributes :name , :email , :created_at

  def headers
    {
      to : "[email protected]" ,
      subject : "User created an account"
    }
  end
end

A entrega será acionada em um gancho after_create .

Instalação

Instalar MailForm é muito fácil. Basta editar seu Gemfile adicionando o seguinte:

 gem 'mail_form'

Em seguida, execute bundle install para instalar MailForm .

Você pode executar rails generate mail_form para visualizar informações de ajuda sobre como gerar um formulário básico para começar.

Visão geral da API

atributos(*atributos)

Declare os atributos do seu formulário. Todos os atributos declarados aqui serão anexados ao e-mail, exceto aqueles :captcha é verdadeiro.

Opções:

:validate - Um gancho para validates_*_of . Quando true é fornecido, valida a presença do atributo. Quando um regexp, valida o formato. Quando array, valida a inclusão do atributo no array.
Sempre que :validate é fornecido, a presença é verificada automaticamente. Dê allow_blank: true para substituir.
Finalmente, quando :validate for um símbolo, o método dado como símbolo será chamado. Em seguida, você pode adicionar validações como faz no Active Record ( errors.add ).
:attachment - Quando fornecido, espera que um arquivo seja enviado e o anexa ao e-mail. Não se esqueça de definir seu formulário como multitipo. Ele também aceita vários arquivos por meio de um único atributo de anexo e os anexará individualmente ao e-mail.
:captcha - Quando verdadeiro, valida que os atributos devem estar em branco. Esta é uma maneira simples de evitar spam e a entrada deve ser ocultada com CSS.

Exemplos:

 class ContactForm < MailForm :: Base
  attributes :name , validate : true
  attributes :email , validate : / A [^@ s ]+@[^@ s ]+ z /i
  attributes :type , validate : [ "General" , "Interface bug" ]
  attributes :message
  attributes :screenshot , attachment : true , validate : :interface_bug?
  attributes :nickname , captcha : true

  def interface_bug?
    if type == 'Interface bug' && screenshot . nil?
      self . errors . add ( :screenshot , "can't be blank on interface bugs" )
    end
  end
end

c = ContactForm . new ( nickname : 'not_blank' , email : '[email protected]' , name : 'José' )
c . valid?   #=> true
c . spam?    #=> true  (raises an error in development, to remember you to hide it)
c . deliver  #=> false (just delivers if is not a spam and is valid, raises an error in development)

c = ContactForm . new ( email : 'invalid' )
c . valid?               #=> false
c . errors . inspect       #=> { name: :blank, email: :invalid }
c . errors . full_messages #=> [ "Name can't be blank", "Email is invalid" ]

c = ContactForm . new ( name : 'José' , email : '[email protected]' )
c . deliver

acrescentar(*métodos)

MailForm também facilita anexar informações de solicitação do cliente ao e-mail enviado. Você só precisa fazer:

 class ContactForm < MailForm :: Base
  append :remote_ip , :user_agent , :session
  # ...
end

E no seu controlador:

 @contact_form = ContactForm . new ( params [ :contact_form ] )
@contact_form . request = request

O ip remoto, agente do usuário e sessão serão enviados no e-mail em uma sessão de solicitação de informações. Você pode anexar qualquer método ao qual o objeto de solicitação responda.

I18n

I18n no MailForm funciona como no ActiveRecord, então todos os modelos, atributos e mensagens podem ser usados com localização. Abaixo está um arquivo de exemplo de arquivo I18n:

 mail_form :
  models :
    contact_form : "Your site contact form"
  attributes :
    contact_form :
      email : "E-mail"
      telephone : "Telephone number"
      message : "Sent message"
  request :
    title : "Technical information about the user"
    remote_ip : "IP Address"
    user_agent : "Browser"

Modelo de e-mail personalizado

Para personalizar o modelo de e-mail usado, crie um arquivo chamado contact.erb em app/views/mail_form . Dê uma olhada em lib/mail_form/views/mail_form/contact.erb neste repositório para ver como o modelo padrão funciona.