When you go to the forms tab, you'll see that forms act very much like templates. They have custom, dynamic fields, and some options for being customized. The two differences that distinguish a form from a template are:

  • Forms have submissions, meaning they accept public visitor input.
  • Forms are not essential to having a working site.

Creating Forms

When you navigate to Forms in the builder, there is a New Form button from which you can create new, custom forms.

This presents you with all the options for the form, but you have to save the form before you can get to the custom fields.

Form Fields

Unlike a template, we start out without a single field when you create a new form. This makes the form entirely flexible and up to your imagination.

Since you're likely to build templates before forms, I'll just say that fields act very similarly with forms as they do with templates. You can drag and drop to reorder, you can hide fields, require fields, etc. The main difference is that form fields do not have an associated group, since they must all be displayed as one form.

Form Options

Forms come with a lot of options, which are now all consolidated on the Settings page for each form. Here are the options:


This is simply an arbitrary title by which you represent the form in the builder.


Description has no current use and will be deprecated soon.

Submit Button Label

This enables you to change the value attribute on the submit input when the form is rendered. If you leave it blank, the Simple Form default will be used.

Notification Emails

When a new submission is created, you can be notified via email. Place each email address on a separate line and each email address will get a notification.

Page Response

When a form submission is created on your site, what is happening behind the scenes is a request is being sent to your Sapwood API. After receiving and completing it, it redirects back to the page on which the form was rendered. However, in this case, the form fields are removed and there is a response message where the form used to be. It is in this section that you write the HTML markup for that response.

Custom Email Response

This was born out of a sponsored feature request, which you might imagine considering its narrow use. You are able to build a custom email to be sent to the visitor who creates the form submission on your site.

To do this, you will need to designate one of your custom fields as being the email address for that form submission. That is what the mailer uses for the To address when sending the message.

Note: It is wise to test your email response before deploying to production.

Rendering a Form

You need to hard-code a form into a specific page template, but you can do so using some Sapwood helpers.

First, you have to find the form, which is done best via the form's slug. You get the slug from the URL when inside the form builder (it should look like .../forms/[form_slug]/edit). To retrieve the form object, you can use the following code from within your service object.


def contact_form
  @site.forms.find_by_slug(slug) # where `slug` is the form slug

If you have retrieved the form object, then in your view, all you need is:

<%= form_markup(viewer_service.contact_form) %>

And the form will be automatically rendered.

Form Submissions

In the builder, each form has a Submissions tab. This tab lists the form submissions created for that form. You are now able to manipulate and export this data.

Editing Submissions

When you hover over a form submission, you'll see an Edit link. This will take you to a form that will enable you to edit the submission.

Do note that any hidden fields will be available to be edited here. That is a good use case for having fields that you don't want visitors to populate, but that you can populate after you take action on the submission.

Viewing A Submission

There is also a View option for each submission, which simple lists the fields for that submission and their associated values.

Exporting Submissions

Last, submissions can be exported. This is done from the submissions listing for a particular form. This will dump all dynamic fields, along with created_at and updated_at, for each form submission from that form.