mail_form
v1.10.1
Ce joyau a été construit sur ActiveModel pour montrer comment vous pouvez intégrer les validations, les noms et i18n de Rails vers vos modèles sans avoir besoin de tout implémenter vous-même.
Ce README fait référence à la gemme MailForm à utiliser dans Rails 5+. Pour obtenir des instructions sur l'utilisation de MailForm dans les anciennes versions de Rails, veuillez vous référer aux branches disponibles.
MailForm vous permet d'envoyer un e-mail directement à partir d'un formulaire. Par exemple, si vous souhaitez créer un formulaire de contact, seules les lignes suivantes sont nécessaires (y compris l'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 Ensuite, vous démarrez une console avec rails console et tapez :
>> c = ContactForm . new ( name : 'José' , email : '[email protected]' , message : 'Cool!' )
>> c . deliverVérifiez votre boîte de réception et l'e-mail sera là, avec les champs envoyés (en supposant que vous ayez correctement configuré votre méthode de livraison par courrier).
Lorsque vous héritez de MailForm::Base , il extrait un ensemble d'éléments d' ActiveModel , comme ActiveModel::Validation , ActiveModel::Translation et ActiveModel::Naming .
Cela apporte I18n , les messages d'erreur, les validations et la gestion des attributs comme dans ActiveRecord à MailForm , afin que MailForm puisse être utilisé dans vos contrôleurs et générateurs de formulaires sans ajustements supplémentaires. Cela signifie également qu'au lieu de ce qui suit :
attribute :email , validate : / A [^@ s ]+@[^@ s ]+ z /iEn fait, tu pourrais faire ceci :
attribute :email
validates_format_of :email , with : / A [^@ s ]+@[^@ s ]+ z /iChoisissez celui qui vous plaît le plus. Pour plus d’informations sur l’API, veuillez continuer à lire ci-dessous.
MailForm fonctionne également bien avec les ORM. Il vous suffit d'inclure MailForm::Delivery dans votre modèle et de déclarer quels attributs doivent être envoyés :
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 La livraison sera déclenchée dans un hook after_create .
Installer MailForm est très simple. Modifiez simplement votre Gemfile en ajoutant ce qui suit :
gem 'mail_form' Exécutez ensuite bundle install pour installer MailForm .
Vous pouvez exécuter rails generate mail_form pour afficher des informations d'aide sur la façon de générer un formulaire de base pour vous aider à démarrer.
Déclarez vos attributs de formulaire. Tous les attributs déclarés ici seront ajoutés à l'e-mail, sauf ceux :captcha est vrai.
Possibilités :
:validate - Un hook pour validates_*_of . Lorsque true est donné, valide la présence de l'attribut. Lorsqu'une expression rationnelle, valide le format. Lorsque tableau, valide l'inclusion de l'attribut dans le tableau.
Chaque fois que :validate est donné, la présence est automatiquement vérifiée. Donnez allow_blank: true pour remplacer.
Enfin, lorsque :validate est un symbole, la méthode donnée en symbole sera appelée. Ensuite, vous pouvez ajouter des validations comme vous le faites dans Active Record ( errors.add ).
:attachment - Lorsqu'il est indiqué, attend qu'un fichier soit envoyé et le joint à l'e-mail. N'oubliez pas de définir votre formulaire sur multitype. Il accepte également plusieurs fichiers via un seul attribut de pièce jointe et les joindra individuellement à l'e-mail.
:captcha - Lorsque vrai, valide les attributs doivent être vides. C'est un moyen simple d'éviter le spam et l'entrée doit être masquée avec CSS.
Exemples :
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 . deliverMailForm permet également d'ajouter facilement les informations de demande du client au courrier envoyé. Il vous suffit de faire :
class ContactForm < MailForm :: Base
append :remote_ip , :user_agent , :session
# ...
endEt dans ton contrôleur :
@contact_form = ContactForm . new ( params [ :contact_form ] )
@contact_form . request = requestL'adresse IP distante, l'agent utilisateur et la session seront envoyés par e-mail lors d'une session d'informations sur la demande. Vous pouvez donner à ajouter n'importe quelle méthode à laquelle l'objet de requête répond.
I18n dans MailForm fonctionne comme dans ActiveRecord, de sorte que tous les modèles, attributs et messages peuvent être utilisés en version localisée. Vous trouverez ci-dessous un exemple de fichier 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" Pour personnaliser le modèle de courrier électronique utilisé, créez un fichier appelé contact.erb dans app/views/mail_form . Jetez un œil à lib/mail_form/views/mail_form/contact.erb dans ce dépôt pour voir comment fonctionne le modèle par défaut.
Nous avons l'intention de maintenir le support de toutes les versions Ruby / Rails qui n'ont pas atteint la fin de vie.
Pour plus d'informations sur des versions spécifiques, veuillez consulter les politiques de maintenance Ruby et Rails ainsi que notre matrice de test.
Si vous découvrez un bug, veuillez utiliser le suivi des problèmes github.
Licence MIT. Copyright 2020-2024 Rafael França, Carlos Antônio da Silva. Copyright 2009-2019 Plataformatec.
