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.
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.
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.
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.
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.
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 end
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.
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.
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.
Last, submissions can be exported. This is done from the submissions listing for a particular form. This will dump all dynamic fields, along with
updated_at, for each form submission from that form.