Drupal at Cal Poly

Cal Poly's Content Management System

Webforms Guide Index

Creating a Webform

Webform creation is a process that consists of several steps. Many of these steps are covered in full detail in their own sections (see the Webforms Topics box above), but here is a synopsis of the webform creation process:

CAUTION: Do Not Collect Level 1 Data Via Webforms!

If you need to ask users for sensitive information like their social security number of date of birth, ask us drupalsupport@calpoly.edu about a Secure Forms site.

1. Create the Webform Page

First, create the page that the webform will "live" in. Click Add Content, and then select the content type Webform. You will see a page with CKEditor, just like you see when creating a basic page. Content you add here will precede the Webform. This can be left blank, or can be used to offer context/instructions relevant to the Webform.

Assign a section to the page (by default, This Site). Click Save, and then a new tab called Components will appear on the screen. After you have this configured, click Save.

2. Add Components

Components are the elements your form will be built out of. Most of them collect user input. They will be created and configured one at a time.

First, add a Label, then select a Type, and then click Add. This will take you to a new page where you can configure the additional settings for the component you're adding. For more details on the different component types and how to configure them, click on the Form Components link in the Webforms Topics box (see above).

3. Configure Form Settings

Form settings are accessed by clicking on Webform, then Form Settings. Full details on form settings and what they do can be found in the Form Settings section in the Webforms Topics box (see above).

4. Configure Email Settings

Webforms can optionally be configured to send emails upon form submissions. This is configured by clicking on the Email tab, entering an address, and clicking Add. Full details are available in the Email Settings link in the Webforms Topics box (see above).

5. CAPTCHA

CAPTCHA is a challenge-response test used to help determine whether the user is human and can mitigate the amount of spam your form receives from spambots. To activate CAPTCHA:

  1. ​Click the View Published tab
  2. Scroll to the bottom and click where it says CAPTCHA, no challenge enabled
  3. Select Place a CAPTCHA here for untrusted users.
  4. Note that only anonymous (unathenticated) users will see the CAPTCHA. If you want to test it, you must not be signed in to your Drupal site.

6. Viewing and Downloading Submission Results

  1. Click the Results tab
  2. Click the Download link for a spreadsheet (in Excel or .csv format) of the submission results

7. Form Conditionals (For Complex Webforms)

Conditionals can be used to show (or hide) different form components based on certain conditions, such as a user's response to a question. An example and short tutorial is available on our Webform Conditional Example page.


Check out the following guides for even more information on webforms:
Webforms Quickstart Guide
Webforms User Guide (15 page PDF)

Form Components

Components are the building blocks of webforms. Here is a list of some of the more common components:

Textfield and Textarea

These components both allow you to collect basic text input from users. A textfield allows a single line of input, while the textarea gives users a box of variable size to enter their input.

Textfield ComponentTextarea Component
 

Fieldset

Fieldset creates a box that allows you to group other components. This is usually used to visually group similar or related components (such as contact information).

Fieldset Component
 

Email

The email component is very similar to a textfield, but designed specifically for collecting email addresses as input.

Email Component
 

File

The file component allows users to upload a file such as a document or image. Please note that you may not ask users to upload any files contaiing Level 1 data!

File Component
 

Markup

Markup is a component that allows you to add custom HTML to the webform, even between other form components.

Date

The date component creates a drop-down that can be used to select a date

Grid

Grids create a questionnaire-like section using radio buttons.

Grid Component
 

Select Options

This versatile component allows you to create checkboxes, radio buttons, drop-down lists, and list boxes. Users may select a choice or choices from the options, depending on how you configured this component.

The primary configurations available for this component utilize the "Multiple" and "Listbox" settings. Below the different combinations of those settings are shown:

Radio buttons: multiple and listbox both off.

Default Configuration – Multiple and Listbox Both Off

Checkboxes: turn on only multiple.

Checkboxes - With Multiple Only Turned On

Drop-down menu: turn on only listbox.

Dropdown - With Only Listbox Turned On

Listbox: turn on both multiple and listbox.

Listbox – With Multiple and Listbox Both Turned On

 

Advanced Select Options Display Settings

Users can leverage more advanced control over the layout of a select options component by appending either "_rm_w(X)" or "_cm_w(X)" to the end of the field key, where X is replaced with a number like 2 or 3.

What these options mean:

cm = Column Major ordering (order items from top to bottom, then left to right) 
rm = Row Major ordering (order items from left to right, then top to bottom)
w(X) = The number of columns you will get in your layout

Some examples:

Original Field Key Formatted Field Key Layout result
week_days week_days_cm_w2 Two columns with content organized by column
months months_rm_w3 Three columns with content organimzed by row

Webform Settings

Form settings can be accessed by clicking the Webform tab, and then the Form Settings sub-tab.

Confirmation Message

This CKEditor instance allows you to build a custom message to be displayed when the form has been successfully submitted. Also known as a “thank you” page.

Redirect Location

Determines where the user is sent after they have successfully submitted the form. By default, they are pointed to a page where they see the Confirmation Message, but you can change this to point to a custom URL.

Status of This Form

If set to closed, the form will no longer accept submissions. Closing a form will not break links to it, instead, visitors will see a message displayed to inform them the form is no longer accepting submissions.

Submission Access

Can be used to limit the form such that only authenticated or internal users can submit it.

Progress Bar

Is turned on by default, but only appears on forms that have multiple pages. Can be configured with a variety of information such as whether progress displays by page number or percentage.

Preview Page

Adds a page users can review to double-check the form before submitting.

Available as Block

Enabling this option makes the webform available as a block. This can be useful if you have a form you want available on multiple pages, as all submissions will be consolidated.

Confidential Submissions

When checked, your webform will not collect the IP address a submission originated from. For this to work, the submitter can not be authenticated.

Submit Button Label

Allows you to override the submission button with a value other than “Submit”.

Authenticated-Only Settings

There are several additional features here that rely on user authentication to function properly. For most Cal Poly sites, your end users will not be authenticated, so these features will not behave as expected, and we advise against using them:

  • Total/Per User Submission Limits
  • Show “Save Draft” Button
  • Show notification about previous submissions

Email Notifications for Submissions

Drupal Webforms can be configured to send emails when a form submission is received. Emails can be sent as a notification to you or your internal users who need to know when there is a new submission, and they can also be sent to the end user to verify a successful form submission. Many advanced settings are also available.

1. Add Email Recipients

Select the Webform tab, then the E-mails tab. From here, you can set the recipient's address under the E-mail To column by using the Address field. Multiple users can be entered by separating addresses with commas.

Adding a New Email to Webforms
 

Additionally, the E-mail To value can be set using a Component Value. This is most commonly used to send confirmation emails to the user submitting the form by setting Component Value to an E-mail form component.

The email recipients can also be modified after you've clicked Add.

Advanced Recipient Routing with Component Value

Other components offer more advanced configuration choices. A Select Options component, for example, will give you an E-mail Address field for each Option, and send an email to whichever addresses are associated with the Option the user selects.

As an example of how this could be used – if a webform collects requests to reserve a room, but different people are in charge of that room depending on the day of the week, a Select Options component could collect the day of the week, and email the appropriate user.

Using a Select Options for the Component Value of E-mail To
 

2. Enable Sending

This checkbox at the top of the message offers a quick and easy way for you to disable email messages if necessary. This may be useful if you anticipate needing the message to be active again in the future, as it can be used in place of deleting the email and you won’t have to start from scratch to get it set up again.

Configure Recipients after clicking 'Add' or Toggle 'Enable Sending'
 

3. Email Header Details

Here you can set the subject of the email and define the “from” address and name. If you don’t enter any information here, the webform will try to pull information from your global Webform Settings. If you haven’t entered information there either, the webform will pull from your Site Information. Both Webform Settings and Site Info can be found in the site’s Configuration menu (available to Site Administrators).

These default values may be replaced with a static custom value, or may be based on the value of a component in the webform.

Email Header Details
 

4. Email Template

This is where the actual content of the email is defined. The default template lists who submitted the form, when they submitted it, the values that each form component collected, and a link that can be used to view the submission (note that this link can only be used by authenticated users, so end users will not be able to see their submission).

Email Template
 

The Included E-mail Values section can be expanded to show a list of all components in the form and a checkbox. Unchecking a component will prevent values it collects from showing up in the email. There is also a checkbox at the bottom that can be used to exclude any “empty” components that were not filled out when the form was submitted.

Customizing the content of the email can be done by adding or removing static text. As an example, adding “Thanks for your submission!” at the end of the template will add exactly that. If you wish to add dynamic content, you will need to use tokens. You can see some of these tokens in use in the default template, and can examine what other tokens are at your disposal by clicking Browse Available Tokens.

Tokens are also discussed in more detail in their own topic (see above).

Tokens

A token is a placeholder for a variable value. The value called by the token depends on what token is being used. Tokens can be used in many different places, ranging from the webform itself to the email notifications it sends, and can accomplish a variety of tasks.

For a full list of tokens, click Browse Available Tokens while working in Drupal. Keep in mind that though many other tokens are available, some of them rely on information that will only be available if the submission came from an authenticated user. Since in most cases end users are not authenticated, some tokens will not function as expected.

Some tokens that will function correctly on most Cal Poly Drupal webforms are listed below:

Current Date Tokens

These tokens are all based on the current date. Exact display content varies by token.

Long Format – [current-date:long]
     Ex: Friday, October 9, 2015 - 12:15

Medium Format – [current-date:medium]
     Ex: Fri, 10/09/2015 - 12:15

Short Format – [current-date:short]
      Ex: 10/09/2015 - 12:15)

Raw Timestamp – [current-date:raw]
      Ex: 1444418133

Time-since – [current-date:since]
      Ex: 45 years 9 months

Current Page Tokens

Values called by these tokens are related to the webform submissions.

Date Submitted – [submission:date]

Edit URL – [submissions:edit-url]

Submission Values – [submissions:values:?]
The “?” in this token can be replaced with the field key (including any parent field keys separated by colons).

Webform Reports

Webform Reports are generated by a second module that can tap into the main Webforms module and generate customizable displays of your form submission results. This is done by applying filters to the report that can remove irrelevant submissions or fields.

Reports, like Webforms, are a second layer that live inside of a container (page). And, just like with Webforms, the publishing options only affect the container.

To Generate a Report:

  1. Click Add Content, then Webform Report. As with a Webform, you’ll create the container first, and then the actual Report later.
  2. Give the report a Title and Section. The optional Description will appear at the top of the Report, if information is entered here.
  3. Using the dropdown labeled Webform, designate which Webform your Report will be pulling submission results from.
  4. Click Save. Note that reports are not publicly visible, so the publishing options only affects the default view for internal users
  5. Under the Edit tab, select Report Criteria. This takes you to the Report itself.
  6. Add columns, filters, and sorts to build your report. Each of these is explained in more detail below.
  7. Some additional settings can be adjusted in the Options box at the bottom of the page.
  8. Click Update to save your changes.

Report Columns

Report columns determine what information will be displayed in the report to describe each submission. All form components will appear here, as well as some additional information that may be collected by the form such as the time and date the submission was received. Finally, some functional options also appear that allow the inclusion of links to easily edit, view, or delete a submission.

In the box labeled Add Column, you can select what information you want to add to the report, and then click the Add Column button to insert it. Once inserted, columns can be reordered via click-and-drag with the four-way arrow icon (like form components).

Depending on what the information that will be displayed in each column is, some additional options may appear. For example, if a date is added, a dropdown will appear to allow the date display format to be selected – ex: DD/MM/YYY.

Report Columns
 

Filters

Filters can be added almost exactly like Report Columns, but they have an additional dropdown option called Filter Type. This can be set to a variety of qualifiers and is used to include or exclude submissions based on the value of whatever component you have added a filter for.

This is the basic format for a filter:

[form component] [filter type] [filter value]

Filters
 

The Filter Type contains options such as “contains,” “less than,” “is not empty,” and several others. These options, combined with the filter value (when applicable), create the filter.

As an example, say we want to create a report for a room reservation form. Reservations for 50 or more people require additional setup time, so we want to create a report to filter for reservation size to easily identify if any big events are coming up. We would create the following filter:

[Number of Attendees] [is greater than] [49]

As with conditionals, there may be multiple ways you could accomplish the same effect using filters. Since the number of attendees should always be a whole number (which I can ensure with form validation if needed), I simply used “is greater than 49,” to get the results I wanted.

However, if I was filtering a form component for something like a dollar value of $50.00 or more, I may have instead used a filter that was set to “greater than or equal to 50,” to maintain accurate results.

Note that all filters are “ANDed” together, which means they will all be applied. So, if we had two filters applied:

[Number of Attendees] [is greater than] [49]
[Catering] [equals] [Yes]

Then the report would show submissions where all applied filters are true. In other words, it only shows reservation requests for 50 or more people that need catering. It would not show a reservation request for 55 people if catering was not also requested.

Sort By

The basic interface of the Sort By section works just like the Filters and Report Columns. A dropdown can be used to select the order of sorting that will be applied to the component. This is the basic format:

[sort attribute] [order]

Sorty By
 

Consider the room reservation report that we’ve been using as an example. If we wanted to sort those results by size of attendees, we could use:

[Number of Attendees] [Descending]

Conditionals

Conditionals can be used to create advanced webforms that reveal or omit certain questions based on user input. For example, you could ask users at the beginning of the form to indicate if they are staff or faculty, and use a conditional to show different follow-up questions depending on their response.

It is usually best to configure conditionals after the rest of your Webform. From there:

  1. Click on the Webform tab, and then the Conditionals tab.
  2. Click on the + icon next to Add a new condition.
  3. Use the dropdown menus and text field to configure the conditional.
  4. Finally, click Save Conditions.

Basic Conditionals

A conditional will be configured by selecting a series of options that complete an if-then statement, as illustrated below (with the options in brackets):

If [form component] [condition] [value],
Then [form component] [condition] [state]

Most of these options are set using dropdown menus, so you don’t have to worry about memorizing variables to successfully configure your conditionals. As an example of a simple conditional, you might set up something like:

If [Question A] [is] [Answer X],
Then [Question B] [is] [shown]

Nested and Compound Conditionals

You can also nest statements to make compound conditionals. Additional If and additional Then statements can both be added by clicking the + icon that appears next to an existing If or Then.

When multiple If statements are used, an additional choice will appear to select if the statements have an And or an Or relationship. Ex:

If [form component] [condition] [value], [and]
If [form component] [condition] [value],
Then [form component] [condition] [state]

Selecting the And choice means both If statements must be true for the Then statement to occur. The Or choice means the Then statement will occur when either of the If statements are true.

Multiple Then statements can also be used to affect multiple changes on the Webform based on a single conditional. Ex:

If [form component] [condition] [value],
Then [form component] [condition] [state]
Then [form component] [condition] [state]

All of the above options can be combined to create a variety of conditionals ranging from very simple to complex to achieve a variety of tasks. Remember, fieldsets and page breaks are components – so you can reveal or omit multiple components with a single conditional by grouping them in a fieldset or page break.

As an example, consider a form used to submit requests to reserve a room. One question on the form asks the end user if they would like on-site assistance – but the staff don’t work weekends, so we can only offer on-site assistance on weekdays.

If [Day of the Week] [is] [Sunday][or],
   [Day of the Week] [is] [Saturday],
Then [On-Site Assistance] [isn't] [shown]

 

 

 

 

 

 

 

 

 

 

 

 

Related Content

Cal Poly's WCMS

Drupal Since 2009 Badge

Drupal has been Cal Poly's web content management system since 2009.

More About Drupal

Quick Start Guide

  • Quickstart Icon

    Learn
    Drupal Basics

  • Our Drupal 7 Quick Start Guide will help you get up and running in no time.

Start Drupalling!

User Management

  • User Management Icon

    Learn
    Users and Roles

  • Site admins can learn how to add/remove users, and what roles to grant their users.

User Management

Drupal Webforms

  • Webforms Icon

    Learn
    Webforms

  • This Webforms guide features a new interface to help you find the answer to all your questions quickly!

Webforms Guide

Mailing List

  • Mailing List Icon

    Follow
    Drupal Updates

  • Subscribe to our mailing list to stay up-to-date on Drupal news.

Subscribe