Best Practice: How to create Form

This guide covers the configuration setup and create process of a regular contact form:

  • Setup Alchemy mailer
  • …..

1 Mailer Settings

This is the default mailer configuration.


mailer:
  page_layout_name: contact
  forward_to_page: false
  mail_success_page: thanks
  mail_from: your.mail@your-domain.com
  mail_to: your.mail@your-domain.com
  fields: [salutation, firstname, lastname, address, zip, city, phone, email, message]
  validate_fields: [lastname, email]
  • page_layout_nameString
    (Optional) A Alchemy::PageLayout name. Used for rendering the contact form.
  • forward_to_pageBoolean
    (Optional) If set to true the mailer redirects to the page defined with mail_success_page option.
  • mail_success_pageString
    (Optional) A page urlname that should be displayed after succesfully sending the mail.
  • mail_fromString
    (Optional) The email address the mail is send from.
  • mail_toString
    (Optional) The email address the mail is send to.
  • fieldsArray
    Field names of your contact form. These fields become attributes on the Message Model
  • validate_fieldsArray
    Field names of your contact form that should be validated for presence.

All optional setting should be managable through the content management user. So creating an element that set these values is highly recommended.

2 Creating a contact form element

Describe a new Element with this options inside your elements.yml file:


- name: contactform
   contents:
   - name: mail_from
     type: EssenceText
     validate:
     - presence
     - format: email
   - name: mail_to
     type: EssenceText
     validate:
     - presence
     - format: email
   - name: subject
     type: EssenceText
     validate:
     - presence
   - name: success_page
     type: EssenceSelect
     validate:
     - presence

The fields mail_to, mail_from, subject and success_page are recommended. The Alchemy::MessagesController uses them to send your mails. That way your customer has full control over these values inside his contact form element.

The validations are optional, but highly recommended.

Create a page layout for your contact page in the page_layouts.yml file:


- name: contact
  unique: true
  cache: false
  elements: [pageheading, heading, contactform]
  autogenerate: [contactform]

Disabling the page caching is highly recommended!

2.1 Example contact form

Use the rails g alchemy:elements --skip generator to create the view files.

2.1.1 The contact form view

Open app/views/alchemy/elements/_contactform_view.html.erb in your text editor.

We are using the great simple_form gem in this example. If this gem is not already installed, you have to add


  gem 'simple_form'

to your Gemfile and afterwards use

bundle 
command to install simple_form.

<%= simple_form_for(@message ||= Alchemy::Message.new) do |form| %>
  <%= form.input :firstname %>
  <%= form.input :lastname %>
  <%= form.input :email %>
  <%= form.input :message, :as => :text %>
  <%= form.hidden_field :contact_form_id, :value => element.id %>
  <%= form.button :submit %>
<% end %>

See the hidden field? This is important, or the messages mailer can’t do all the magic for you.

If you use different or additional input symbols like ‘company’ , ‘age’ etc. make sure to adapt the fields in the mailer configuration (config/alchemy/config.yml).

Please have a look at the simple form documentation for further infos about the various config options.

2.1.2 The contact form editor

The app/views/alchemy/elements/_contactform_editor.html.erb file should have this layout:


<%= element_editor_for(element) do |el| -%>
  <%= el.edit :mail_from %>
  <%= el.edit :mail_to %>
  <%= el.edit :subject %>
  <%= el.edit :success_page, :select_values => pages_for_select(nil, element.ingredient(:success_page), "Choose page", :urlname) %>
<%- end -%>

The page_selector helper is pretty handy for setting the success page. Note that the :page_attribute option is important. Leaving it the default :id value breaks the message controller.

3 Translating validation messages

All validation messages are passed through ::I18n.t so you can translate it in your language yml file.

3.1 Example Translation


de:
  activemodel:
    attributes:
      alchemy/message:
        firstname: Vorname
        lastname: Nachname

If you like to use same vocabulary in different context:

e.g in the app/views/alchemy/elements/_contactform_view.html.erb


  <%= form.input ... %>
  <%= form.input :firstname , label: t(:sender, scope: 'my_forms.contactform') %>
  <%= form.input ...  %>

Your language yml should look like this: (config/locales/de.yml)


my_forms:
  contactform:
    sender: Sender

Now you can reuse the label by using the t function while defining label.