Creating Forms for User Submissions

Your starter Webvanta site comes preconfigured with a contact form. When a site visitor completes this form, you'll receive an email, and the message will be added to the site's database so you can review the message history at any time at the Submissions > Messages page.

Sometimes, however, you want to add fields to that form, or you want a variety of forms for different purposes. You may also want the information entered in a form to create a particular type of database item.

For example, suppose you have a site that lists local restaurants. You want the owner of a new restaurant to be able to submit their information. After you've reviewed their submission, you'd like to be able to instantly add it to the restaurant listings on the site.

Creating Custom Forms

To create a custom form, start by creating a custom item type (unless you already have a custom item type for the appropriate information; in the example above, you'll already have a "restaurant" custom item type). See Creating Custom Item Types for details.

Custom forms that can be submitted by site visitors support most, but not all, of the fields that you can include in a custom item type. You can use:

• Text field
• Text area
• WYSIWYG or code text area (but you need to ensure that your form page is loading the required JS and CSS)
• Pop-up menu or select list (taxonomy)
• Checkbox

Field types that are NOT fully supported on user forms include:

• Publication date
• Tags
• Categories
• Related items
• Related assets
• Static text
• Field set

You can include any of these field types in the custom item, but the corresponding fields will not appear in the user form. This is often still useful, though, because all fields will be in your admin form. For example, you may want to include a category picker for the restaurant item, and when you review the submission, you can assign the category.

In some cases, it is possible to make these field types work by adding some additional code to the form. In particular, see the help forum tips-and-tricks article Using a Related Item in a Custom Form if you want to use related items.

Setting the Form Options

To begin setting up the form, view the custom item types list on the Database > Item Types page, and click the Forms icon to the right of the desired item.

The form list page shows any forms you have already created for this item. You can have as many forms as you need, though usually you'll only have one form per item type. Click New Form to create a new one.

On the New Form page, you specify what page the form goes on and what happens when it is submitted:

1. Enter an ID for the form. This can be any valid CSS ID.
2. Specify the page that the form will go on. If you want to create a new page for the form, enter the slug for the page.
3. Specify the page that is displayed after a successful form submission. Typically this is some sort of "thank you" page.
4. Indicate whether the person who submits the form should receive an automatic acknowledgement email. You must include a field named "email" in the form if you want to use this feature.
5. Indicate whether you want a site admin to receive a notification email when a form is submitted. If you leave the admin email field blank, then the default email address specified in the Global Setting admin_contact_email is used. If you want the admin notification emails for the form to go to one or more other recipients, enter a comma-separated list of email addresses in the email field.
6. Indicate whether or not you want forms to be automatically accepted. If the box labeled Automatically Accept Form Submissions is not checked, the items submitted via forms must be reviewed and accepted by an admin before they will appear in results of database queries. If this box is checked, then they are immediately treated as having been accepted and do not appear in the Form Submissions list. You'll generally want to use this option for forms that are essentially contact forms.

Click the Create button to proceed.

Note: For Custom Item Types that you're using for form submissions, you'll usually want to check the "Private" option in the custom item type definition page to keep form submissions from appearing in site search results.

Installing and Customizing the Form Code

If you specified a new page to hold the form in the previous step, then your form is already on the new page.

If you specified an existing page, we do not put the code on the page for you automatically. Copy all of the form code from the bottom of the Form Template page and paste it into the page on which you want to display it. Note that for proper operation, you must put this code on the Form Page you specified.

Now you can modify the form as you'd like for layout and styling. You may want to rearrange the fields, add styling, and add explanatory text. You can change anything you want as long as you do not change any of the ID or name attributes, the field types, the submit action, or the hidden field.

Set up the Success Page

When a form is successfully submitted, the Success Page is displayed. Add the desired content to the page that you specified when setting up the form.

If you want to display any of the information from the form on the success page, you can access the submitted item via WebvantaScript, just as you would on an Item Page.

If you specified a new page for the Success Page in the previous step, Webvanta created that page for you automatically, so you can now edit it from your page list.

Customize Email Notifications

If you enabled the email options when setting up the form, an email will be sent to the person who submitted the form to acknowledge their submission, and to the site admin or specified notification recipients so they know there is new information to be moderated.

The details of how to customize email notifications are covered in the article Customizing Email Notifications for Form Submissions.

Moderating Submitted Forms

You can moderate your submitted forms either by clicking the link in the admin notification email, or by choosing Submissions > Form Submissions.

Form generated items are set to require moderation when submitted, so they will not appear on any public pages. You can edit the new item as desired, and select the Accept moderation choice if you want the entry to appear publicly.