How to create and customize a Contact Form

From Spiffy Stores Knowledge Base

Revision as of 19:09, 17 September 2013 by Admin (talk | contribs) (→‎Displaying Error Messages)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)

Using the Default Contact Forms

All Spiffy Stores themes come with a Contact Us form already built in. This functionality is enabled by creating a page with a handle of contact-us. When this page is loaded, a default contact form is added to the page to enable your customers to send messages to you via an email that is submitted by the form.

By default, if you also have a page with a handle of contact-us-thanks, then this page will be displayed once the form has been submitted successfully.

Building and Customizing your own Contact Forms

If you want to have more control over the formatting and content of your Contact forms, then you can use the Liquid form tag to build your own contact forms.

A Contact form can be included on any page by simply including the following tags:

{% form 'contact' %}
...
{% endform %}

Within the form tags, you can include an HTML fragment that defines the input fields in your form. You can include any input fields that you like, but you must include a name, an email and message (or body) fields.

All fields that are defined within the HTML fragment must have a name of contact[field_name].

Here is an example of some HTML being used to define a custom contact form. The form should appear below the Template:Page.content tag.

{% form 'contact' %}
  <dl class="group">
    <dt id="contact_name_dt"><label for="contact_name">Name</label></dt>
    <dd id="contact_name_dd"><input id="contact_name" maxlength="40" name="contact[name]" size="30" type="text" placeholder="Joe Bloggs" /></dd>
    <dt id="contact_email_dt"><label for="contact_email">Email</label></dt>
    <dd id="contact_email_dd"><input id="contact_email" maxlength="255" name="contact[email]" size="30" type="text" placeholder="joe@example.com" /></dd> 
    <dt id="contact_message_dt"><label for="contact_message">Message</label></dt>
    <dd id="contact_message_dd"><textarea cols="25" id="contact_message" name="contact[message]" rows="10" placeholder="Enter your message"></textarea></dd>
  </dl>
  <input name="commit" type="submit" value="Send" />
{% endform %}

It is also necessary to add some code to handle errors and display some information for the user if the form was submitted successfully.

Displaying a response if successful

If the form is posted successfully, then the form variable can be tested for success as follows:

{% form 'contact' %}
  ...
  {% if form.posted_successfully? %}
    <div class="successForm feedback">
      <p>Thanks for contacting us! We'll get back to you as soon as possible.</p>
    </div>
  {% endif %}
  ...
{% endform %}

As with the default contact forms, if the page contact-us-thanks exists, then its content can be accessed from the form variable and can be displayed instead of using the default message coded in the page.liquid template.

{% form 'contact' %}
  ...
  {% if form.posted_successfully? %}
    <h4>Form Submitted Successfully</h4>
    {% if form.success_message %}
      {{ form.success_message }}
    {% else %}
      Thanks for contacting us! We'll get back to you as soon as possible.
    {% endif %}
  {% endif %}
  ...
{% endform %}

If you use a Contact Us Thanks page, then you can edit the contents of the response message directly by editing the page, rather than having to go into the Theme Editor to edit the page.liquid template.

Displaying Error Messages

You will also need to include some code to deal with error messages, which may occur if the user enters incorrect information into the form.

The form.errors variable includes some information you can use to display error messages to the user.

{% form 'contact' %}
  ...
  {% if form.errors %}
    <div class="errorExplanation" id="errorExplanation">
      <h2>{{ form.errors.size }} {{ form.errors.size | pluralize: 'error', 'errors' }} prevented this Contact Form from being submitted.</h2>
      <p>There were problems with the following fields:</p>
      <ul>{% for field in form.errors %}
        <li>{{ form.errors.messages[field] }}</li>{% endfor %}
      </ul>
    </div>
  {% endif %}
  ...
{% endform %}

Using Snippets

You can use the form tag directly in the page.liquid template by specifying on which page(s) you want the form to be included.

<h1>{{ page.title | strip_html }}</h1>
<div class="textile">
  {{ page.content }}
  {% if page.handle == 'contact-us' %}
    {% form 'contact' %}
    ...
    {% endform %}
  {% endif %}
</div>

In this example, we include the form on the Contact Us page.

As an alternative, you can include the form tag in a snippet, and include that in the page.liquid template instead.

<h1>{{ page.title | strip_html }}</h1>
<div class="textile">
  {{ page.content }}
  {% if page.handle == 'contact-us' %}
    {% include 'contact_form' %}
  {% endif %}
</div>

If you do decide to include your form tags using an include tag, it's important to ensure that the snippet is named _contact_form.liquid, so that the software can determine that a form tag is being included in the template.