Documentation

Introduction

Forms allow your Web site visitors (or end-users) to enter and submit data to you. Forms can be used to gather email addresses for contact lists, present visitors with a survey, create order forms, and more. The following tutoral will explain how to create and add forms to your pages.

You may find it helpful to view this sample form while reading through the tutorial. Each of the form elements detailed below are listed in parentheses on the sample form.

ATTENTION SENATE CLIENTS: Policy states our forms are not allowed to store visitor data. Any form you create will be UNABLE to perform a data export. Instead, you will need to add a Notification Email or CMS Email form action (see Step #3) to your form.

Steps to Creating a Form in Formbuilder

Step 1 - Create the Form

Place your mouse cursor over the "Warehouse" tab, located in the top menu of your HillTop Dashboard. From the drop-down menu, click on the "Forms" link. This will bring you to a page that lists the existing forms stored in your Warehouse, if any.

Forms Menu Link

Next, click the "Add new form" link, located in the right margin.

Add New Form Link 

After clicking the "Add new Form" link, you will enter the preliminary information for your new form, as shown in the image below. After you have completed the fields, click the "Submit" button.

Title: The title of your form.

Name: This field wil auto-complete, based on your title. This field should be left to the default setting. However, if this field is edited, no spaces or special characters should be used.

Content: This field is used to enter a message that will appear above the form, once it has been added to a page. This section should include information about the purpose of the form.

Thank You: The information in this field will be displayed to the visitor, once they have filled out and submitted the form.

Abstract: This field is used to enter a short description of your form. This information will not appear to visitors, and is for internal reference.

Is Active: This setting determines whether the form is available for use on your site.

Permissions: Use this field to give access to additional HillTop users, if they will need to view, edit, or own the form.

Create new form

return to top
Step 2 - Add Form Fields

Clicking the "Submit" button will take you to the form editor. Here you will add the fields that allow your visitors to enter data. Fields can be created that will allow visitors to input their name or e-mail address, select a donation amount, vote on a topic, and more. The various Form Field formats are described in detail below.

To begin adding Form Fields, click the "Add new field" link, located in the sidebar menu on the right of the page.

Add form field

 

After clicking the link, you will be forwarded to the first of two Form Field settings pages. First, select the type of Form Field you will be creating from the "Form Field" drop-down. The field types you can choose from are explained in detail below the example image.

Enter the title of the Form Field in the "Title" field. The title is an internal identifier, and allows you to easily distinguish your completed fields from one another, when viewed in the form editor. The title should be based on the information that will be entered by a visitor (or displayed by the Form Field, if it is not used to collect information). For example, a field that asks for a visitor's first name would be titled "First Name."

The "Is Saved" option determines whether or not any data entered into the Form Field will be saved in the database, and can later be exported. If the data entered into this field should be saved, such as names, phone numbers, or other pertinent information, select "Yes." If the data does not need to be saved, this option can be set to "No."

If the "Is Saved" option is set to "Yes," the "Name" field becomes available. The "Name" field is also used internally, for actions such as form export, and form data export. The name you enter should be short, and reflect the purpose of the Form Field. Using spaces and special characters is not recommended. As an example, the name for a field that collects a visitor's home phone number could be "homephone," or "HomePhone."

The "Is Active" setting determines whether this field will appear on the completed form. Inactive Form Fields are removed from the public form, but can still be edited within HillTop.

Add text form field

Form Field Types

  • Text: Allows visitors to submit a single line of text, such as their name or email address.

  • Textarea: This is a larger, multi-line text field, used for comments or messages.

  • Select: This option will create a drop-down menu.

  • Checkbox list: This creates a list of separate items, with checkboxes next to each item.  Multiple items can be selected in this field.

  • Radio list: This option creates a vertical list of options, with radio buttons for selection. Only one item can be selected from the list.

  • Multi-radio: Similar to the radio list, but options are displayed horizontally. Only one item can be selected at a time.

  • Content: This field allows you to enter text that will be displayed on the form, such as instructions for visitors or a subtitle / subheading. The content added here can be edited as if it were a standard Text Block.

  • Horizontal rule: This creates a graphic that acts as a horizontal border, used to separate sections of your form.

  • Fieldset: This options allows you to group multiple fields together, visually, and adds a text heading for the group.

  • Hidden: This is a hidden field, not visible to your visitors, that can contain a static value needed by the form. This is useful if you need the form to submit information that the visitor submitting the form should not be able to change.

  • Placeholder: (developer use only)

  • Param: (developer use only)

Once you have selected a Form Field, and entered the "Title" and, if saved, the "Name," click the "Submit" button. The form will then expand to show more fields and options, which are specific to the chosen Form Field type (Text, Radio Button, Hidden, etc.). The expanded form will be different for each Form Field option. The image below dispays the expanded form for the "Text" Form Field:

  • Label: The text entered into this field will be displayed on the public form. For example - if a "Text" Form Field is being created to collect the first name of visitors, and "First Name:" is entered into this field, the visitor will see "First Name:"  displayed next to a blank field on the finished form.

  • Is Required: Selecting "Yes" will not allow the form to be submitted if this field is left blank. Selecing "No" will make the field optional, and allow submissions if it is left blank.

  • Values: This field is only appears for "multuple choice" type Form Fields, such as a "Radio List" or "Checkbox List" field. Each set of left and right-hand fields, separated by an "equals sign," is known as an "item." Additional items can be added to the Values list by clicking the "Add Item" button. The added "items" will be the field's selectable choices.

    The text entered in the left-hand field of an item is displayed to visitors on the public form, similar to the "Label." If this item is selected by the visitor, the text in its right-hand field will be recorded amd saved in the database. The value entered in the right-hand field will also appear in the form data that is attached to a "Notification Email" (explained in the "Form Actions" section, below), and bulk exports of form data.

    Note: The values entered in the left-hand fields are the only valid choices for use with the optional "Dependency Value," listed below.

  •  Error Text: This field is optional. Text entered here will be used as a customized error message, for instances when a "required" field is left blank, or the field is otherwise completed incorrectly by the visitor. Leaving this field blank will display the default error message. 

  • Default Value: This field is optional, and records the same static value entered here each time the form is submitted. If the same static value must be attached to each form submission (such as a two letter "State" abbreviation - if the form data is only to be submitted by residents of a specific state), create a "Hidden" type field, and enter the static value in the "Default Value" field. This will attach the static value to the form submission, but your visitors will not need to enter it manually.

  • Tip: The text entered here will be displayed along with the field, such as special instructions for the current field.

  • Validation RegEx: This field is optional. Here, you can use a ColdFusion Regular Expression to check against the information entered by the visitor. This is used in instances when the entered information must conform to a specific format.

  • Validation Error Text: This field is dependant on a Regular Expression being entered in the above field. If the information entered by the visitor does not pass the Regular Expression check, the text entered here will be displayed to them.

  • Dependency Name: Use this in conjunction with both the Dependency Value below, and an existing "Radio List" type field. Using this option will dynamically make the current field you are adding "required" - depending on the visitor's selection in the "Radio List" field. Note: If a field should always be required to be filled out by visitors, select "Yes" for "Is Required," and these options can be ignored. 

    Enter the form field name of the existing "Radio List" field, whose setting will then determine whether or not your current field will be made "required." The value that makes your field "required" is entered in the "Dependency Value" field below.

  • Dependency Value:  Enter the value that the "Radio List" chosen in Dependency Name must be set to, in order to dynamically make your current field "required. The value entered here must exist in one of the Radio List's left-hand "Values" item fields. See "Values" above for more information.

    For example, if the field in Dependency Name is a "Yes" / "No" Radio List, which must be set to "Yes" to make your current field "required," enter "Yes" in this field. When that "Radio List" is set to "Yes," the visitor will be "required" to fill out the field - if the "Radio List" field is set to "No," the current field can be left empty. This way, you can make your form fields "required" dynamically, based on a visitor's selection in a previous field.

  • Wrapper Attributes: Use only if directed by GSL Solutions.

Once you have entered your information in the expanded fields, click the "Submit" button to create your field. Once your field has been created, you will be redirected back to the main form editor. To edit fields after you have created them, click the pencil next to the field you wish to edit. Note that you cannot change the type of the Form Field after it has been created, for example you cannot change a "Text" field into a "Textarea," or a "Radio List" field into a "Checkbox List."

To see a sample form with the different types of fields and options, click Sample Form. Once you have created all the necessary fields for your form, you will add Form Actions, as described in the next step.

return to top
Optional - Reorder Form Fields

The fields you have added will be displayed on the public page in the order they appear in the Form Editor. To rearrange the order, first mouse over the field you wish to move. Your cursor should now be replaced with a "four arrow" icon.

You can now click and drag the field vertically, to select a new position. Once the field has been placed into its new position, the public form will automatically be updated to reflect this change.

return to top
Step 3 - Add Form Actions

Once your fields have been created, you can add Form Actions. Form Actions take the pieces of information entered into your Form Fields by visitors (ex. Name or Email Address), and apply automated tasks to them, such as sending personalized "Thank you" emails, or adding the visitor's email address to a newsletter subscription list.

To begin adding a form action, click the "Add new action" link, located in the right margin.

Add form action

 

Similar to the Form Fields, adding a form action is a two-step process.  On the first page, you will choose a "Form Action" from the drop-down menu, and select whether it is active or not. After clicking the "Submit" button, the form will expand to provide you with more, "Form Action" specific, fields and options. Each "Form Action" is described below the following image.

Thank You Email Form Action

The different Form Actions are:

  • Thank-You Email: This sends a "Thank you" email message to the visitor who has submitted the form.

    On the expanded form, you will choose the field which contains the visitor's email address, then add a subject for the "Thank you" message, and the message itself.

  • Notification Email: This Form Action will prompt you for an email address ("To Address") and a subject line. Upon submission, it will send the completed form (fields and answers) to the email address(es) in the "To Address" field.

  • CMS Email: This action is designed forward each submission's data to your Constituent Services vendor. Please contact your vendor for informaion on how to view the form data in their system.

    With this Form Action, you will enter a subject line, recipient address, and message text. Your vendor should be able to supply the required subject and recipient address upon request. The message field will utilize a set of XML tags (also known as a Parm file), to pass the form data to your CMS vendor. At the bottom of the page, select a vendor type (if your vendor is not on this list, you may leave it blank).  

    Consult your vendor for information on how to properly format the message text - we suggest contacting your vendor to both provide a link to your new form, and request the XML tags, or Parm file. For assistance in utilizing the XML tags/Parm file, please contact support@gslsolutions.com.

  • Note: HillTop uses a special templating system for generating Thank You and CMS messages.  You may use the notation ${KeyName} to have the value of a field appear in the email.  For example, if you have a field in your form with the name "State," in your CMS field you can use the notation ${State} to have the value submitted in this field appear in the message.

  • Subscribe: This will take the data entered into a field, and add it to HillTop's subscription service.  Two field types can be subscribed: email addresses, and cell phone numbers.  

    On the expanded form, you will be shown fields asking you what type of subscription it is, what subscriber lists you would like the email or cell phone number added to, and what lists you would like to appear on the form as subscription options (ex. Newsletter, Issues, etc.).  

  • Unsubscribe: Similar to the subscribe action, it takes a user-submitted email address or cell phone number and unsubscribes it from a list.  Again, you must choose the subscription type (email or cell phone), what lists to automatically unsubscribe from, and what "unsubscribe" options the visitor can select.

  • User Information: This is useful if you would like to collect data from visitor submissions and store it in HillTop's database.  On the expanded form, you will be directed to select which fields to collect, and what type of information each field contains.

  • CAPTCHA and reCAPTCHA: These actions are used to verify an actual person, and not an automated "spam bot," is submitting the form. Both actions will display an image with several letters and numbers, which your visitor must correctly transcribe into a field, in order to submit the form. 

    reCAPTCHA is a more advanced and reliable implementation of this service, however it is recommended to contact support@gslsolutions.com to ensure reCAPTCHA is available for your site. All sites will have the CAPTCHA service available.

  • Donation: This Form Action is used to collect monetary contributions. Contact support@gslsolutions.com before using this Form Action.

  • Paypal Transaction: This is used for "shopping cart" transactions, such as when selling merchandise. Contact support@gslsolutions.com before using this Form Action.

Custom form actions can be added to your HillTop site, if the need arises. Contact support@gslsolutions.com to request a custom action for your site.

Once you have added the appropriate Form Actions, your form is complete and can be added to any of your pages.

return to top
Finish - Add the Form to a Page

To add your completed form to a Web page, first click the "Pages" link, located in the top menu of your HillTop Dashboard. Next, edit the page you wish to add the form to, by clicking the Edit button (pencil icon) to the left of the page title. This will bring you to the page's content editor.

If you will be creating a new page for your form, see Creating a New Page.

In the content editor, click the "Forms" link, located in the right margin, under the "Add Content" heading.

Add form link

 

Clicking the link will add a Form Group to your page. Next, click the "+Existing Forms" button, located on the bottom of your new Form Group. Locate the appropriate form from the list in the left pane, then click the arrow icon next to the form's title to select it. Once you have selected your form, click the "Submit" button to add it to your page.

Note: Any other Content Elements on the page will continue to be displayed after the form has been submitted. For this reason, it is recommended that the form be the only content on the page.

return to top
Exporting Form Information - US House of Representatives Only

All data submitted by visitors is stored on your site's database.  You can retrieve this information by using the export function.

To use the export function, first mouse over the "Warehouse" link, located in the menu at the top of your HillTop Dashboard, then click on "Forms" in the drop-down menu. This will bring you to a page that lists the site's forms. Locate the form you wish to export, then click the Edit button (pencil icon) to the left of the title.

In the form editor, there will be "From" and "To" fields, located under the "Export Records" heading in the right sidebar. The "From" and "To" fields allow you to limit the exported data by entering a date range (mm/dd/yyyy), and only exporting the data submitted during that time. Leave these fields blank to export all submitted data.

Next, click either the HTML or CSV button. The HTML button will produce a readable web page, while the CSV (comma-separated values) button will produce a download promt for a .csv, which can be converted into a spreadsheet file.

Note: The Google Docs Suite's "Sheets" application includes a feature to automatically convert a .csv into a spreadsheet file (click here for more information).

return to top