Drupal Webforms and Contact Forms — Building Forms and Managing Submissions

In this tutorial, you'll learn how to build forms in Drupal using both the core Contact module and the contributed Webform module — from simple contact pages to complex multi-step forms with file uploads and email handlers.

What You'll Learn

• Setting up the core Contact module for basic contact forms
• Installing and configuring the Webform module for advanced forms
• Adding form elements like text fields, checkboxes, file uploads, and CAPTCHA
• Configuring email handlers to send form submissions
• Managing, exporting, and viewing form submissions
• Building multi-step forms with conditional logic

Why It Matters

Forms are how your site communicates with the outside world. Contact forms let visitors reach you, registration forms collect user data, surveys gather feedback, and payment forms Process transactions. Drupal's Contact module handles simple use cases, but the Webform module is one of the most powerful form builders available for any CMS. Understanding both tools means you can build anything from a two-field contact form to a 50-page survey with conditional logic and file attachments.

Real-World Use

A local government website uses the Webform module to manage permit applications. Residents fill out a multi-step form: step one collects personal information, step two describes the project, step three uploads architectural drawings, and step four handles payment. Each step validates data before proceeding. Submissions are stored in Drupal, emailed to the planning department, and exported weekly to a CSV for the permitting system.

Learning Path

flowchart LR
  A[Layout Builder] --> B[Text Formats]
  B --> C[Webforms & Contact]
  C --> D[URL Aliases]
  D --> E[Theme Anatomy]
  E --> F[Installing Themes]
  F --> G[Twig Templating]
  G --> H[Sub-themes]
  H --> I[Template Suggestions]

The Contact Module

The Contact module is included in Drupal core. It provides a simple site-wide contact form and allows you to create additional contact forms for different departments.

Enabling the Contact Module

Go to Extend and check the Contact module under the Core section. Once enabled, visit Configuration > People > Contact forms to manage your forms.

# Enable Contact module via Drush:
drush en contact

Default Contact Form

Drupal creates a default "Website feedback" form. You can customize its settings:

1. Go to Structure > Contact forms
2. Click "Edit" on the default form
3. Set the recipients email address
4. Configure auto-reply message
5. Set the subject and from address

Adding Contact Forms

You can create multiple contact forms for different departments:

1. Go to Structure > Contact forms > Add contact form
2. Enter a label like "Sales Inquiry"
3. Set the recipients to sales@example.com
4. Configure auto-reply
5. Save

Each form gets its own URL: /contact/sales-inquiry.

Contact Form Fields

The core Contact module has limited fields: Subject, Message, and a copy option. You cannot add custom fields without the Webform module or custom code.

The Webform Module

For anything beyond a basic contact form, install the Webform module. It is the most popular contributed module on Drupal.org with over a million active installations.

Installation

# Install Webform via Composer:
composer require drupal/webform

# Enable the module:
drush en webform webform_ui

After installation, a new "Webforms" section appears under Structure.

Creating a Webform

1. Go to Structure > Webforms > Add webform
2. Enter a title: "Event Registration"
3. You can start from a blank form or use a template
4. Click "Save" to enter the form Builder

The form builder shows a preview of your form on the right and an element selection panel on the left.

Form Elements

Webform provides dozens of element types organized by category.

Input Elements

• Textfield — single line text input
• Textarea — multi-line text input
• Email — validates email format
• Number — numeric input with min/max validation
• Telephone — phone number field
• URL — validates URL format
• Date — date picker
• Time — time picker

Selection Elements

• Select — dropdown list
• Checkboxes — multiple choice, multiple select
• Radios — multiple choice, single select
• Buttons — clickable option buttons
• Tableselect — select items from a table

Advanced Elements

• File upload — file attachment with size and extension limits
• Signature — draw signature on canvas
• Rating — star rating widget
• Range — slider control
• Color — color picker

Markup Elements

• Markup — static HTML content
• Processed text — rendered text with tokens
• Horizontal rule — visual separator

Adding Elements to Your Form

Let us add a few elements to the Event Registration form:

1. Click "Add element" and select Textfield
2. Set the title to "Full Name"
3. Make it required: toggle "Required" to Yes
4. Click "Save element"

Repeat for Email, Telephone, and a Select element for "Attendee Type" with options: Student, Professional, VIP.

# Example webform element configuration:
elements: |-
  full_name:
    '#type': textfield
    '#title': 'Full Name'
    '#required': true
  email:
    '#type': email
    '#title': 'Email Address'
    '#required': true
  attendee_type:
    '#type': select
    '#title': 'Attendee Type'
    '#options':
      student: Student
      professional: Professional
      vip: VIP
    '#required': true
  comments:
    '#type': textarea
    '#title': 'Additional Comments'
    '#rows': 5

Email Handlers

Email handlers send form submissions to specified recipients. You can configure multiple email handlers per form — for example, one to the submitter and one to the site administrator.

1. Go to the Webform and click the "Email" tab
2. Click "Add email handler"
3. Configure the following settings:

# Email handler configuration:
handler_settings:
  to_mail: admin@example.com
  from_mail: '[webform_submission:values:email]'
  from_name: '[webform_submission:values:full_name]'
  subject: '[webform:title] submission from [webform_submission:values:full_name]'
  body: |
    Name: [webform_submission:values:full_name]
    Email: [webform_submission:values:email]
    Type: [webform_submission:values:attendee_type]
    Comments: [webform_submission:values:comments]
  html: true
  attachments: true

The attachments: true setting attaches any uploaded files to the email. Tokens like [webform_submission:values:email] are replaced with actual submission values.

Confirmation Messages

After submission, you can show a confirmation message or redirect to a confirmation page.

1. Go to Settings > Confirmation
2. Choose confirmation type:
   • Inline — message displayed on the same page
   • Page — redirect to a confirmation page
   • URL — redirect to an external URL
3. Customize the confirmation message:

# Confirmation settings:
confirmation_type: page
confirmation_title: 'Thank You'
confirmation_message: |
  Thank you, [webform_submission:values:full_name]!
  Your registration has been received. You will receive a confirmation email shortly.

Submission Management

All form submissions are stored in Drupal's database. You can view, edit, delete, and export them.

1. Go to Structure > Webforms and find your form
2. Click "Results" to see all submissions
3. Each submission shows: serial number, created date, IP address, and all values
4. Click "View" to see a single submission in detail
5. Click "Edit" to modify a submission
6. Use the checkboxes to select multiple submissions for bulk operations

Exporting Submissions

1. Go to Results > Download
2. Choose format: CSV, Excel, or JSON
3. Select which fields to include
4. Click "Download"

You can also export submissions programmatically:

<?php
// Export submissions using Drush:
// drush webform:export webform_id --format=csv --delimiter=,

// Or via PHP:
$webform = \Drupal\webform\Entity\Webform::load('event_registration');
$submissions = \Drupal\webform\Entity\WebformSubmission::loadMultiple();
foreach ($submissions as $submission) {
  $data = $submission->getData();
  // Process each submission.
}

Multi-Step Forms

For long forms, split them into multiple pages. Each page appears as a step in a progress bar.

1. In the form builder, add a "Page break" element where you want each page break
2. Elements before the first page break are on page 1
3. Elements between page breaks are on subsequent pages
4. Configure progress bar settings in Settings > Form

# Multi-step form with page breaks:
elements: |-
  personal_information:
    '#type': webform_wizard_page
    '#title': 'Personal Information'
    first_name:
      '#type': textfield
      '#title': 'First Name'
    last_name:
      '#type': textfield
      '#title': 'Last Name'
  project_details:
    '#type': webform_wizard_page
    '#title': 'Project Details'
    project_name:
      '#type': textfield
      '#title': 'Project Name'
    project_description:
      '#type': textarea
      '#title': 'Description'
  confirmation:
    '#type': webform_wizard_page
    '#title': 'Review and Submit'
    review:
      '#type': webform_markup
      '#markup': 'Review your information and click Submit.'

Conditional Fields

Show or hide fields based on user selections. For example, show a "Company name" field only when the user selects "Business" as attendee type.

1. Add a select element with options "Individual" and "Business"
2. Add a textfield for "Company Name"
3. Click "Edit" on the Company Name element
4. Go to the "Conditions" tab
5. Add condition: Show this field when attendee_type equals Business

# Conditional field configuration:
company_name:
  '#type': textfield
  '#title': 'Company Name'
  '#states':
    visible:
      ':input[name="attendee_type"]':
        value: business

Webform Access Control

You can control who can access which forms and what they can do with submissions.

1. Go to Settings > Access
2. Configure permissions per operation:
   • Create — who can submit the form
   • View — who can view submissions
   • Update — who can edit submissions
   • Delete — who can delete submissions

# Access control settings:
access:
  create:
    roles:
      - anonymous
      - authenticated
  view:
    roles:
      - administrator
      - webform_manager
  update:
    roles:
      - administrator
  delete:
    roles:
      - administrator

Anti-Spam

Webform includes several anti-spam measures:

Honeypot

A hidden field that bots fill in but humans do not. If the field has a value, the submission is discarded.

1. Go to Settings > Form
2. Enable "Use Honeypot"

CAPTCHA

Add a CAPTCHA element to your form:

1. Enable the CAPTCHA core module
2. Add a CAPTCHA element to your webform
3. Configure reCAPTCHA for Google's free spam protection

Common Mistakes

1. Not setting email handler tokens correctly: Using wrong token names causes empty email fields. Check available tokens under the token browser in the email handler settings.

2. Allowing unlimited file uploads: Not setting file extension and size limits can lead to security issues. Always restrict uploads to safe file types like PDF, JPG, PNG.

3. Creating forms without confirmation: Users submit a form and see nothing. Always configure a confirmation message or redirect so users know the submission succeeded.

4. Ignoring spam protection: Webforms on public pages without Honeypot or CAPTCHA will get spam submissions within hours. Always enable at least one anti-spam measure.

5. Too many form fields: Long forms reduce completion rates. Split long forms into steps with page breaks, or remove unnecessary fields to improve user experience.

Practice Questions

1. What are the key differences between the core Contact module and the contributed Webform module for building forms in Drupal?

2. How do you configure an email handler to send a copy of the form submission to both the site administrator and the person who submitted the form?

3. What anti-spam techniques does the Webform module support, and how do you enable them?

4. Challenge: Build a job application webform with three pages: personal details (name, email, phone), qualifications (education, experience, skills checkboxes), and document upload (resume PDF, cover letter). Add conditional logic to show a "years of experience" field only when the applicant has relevant experience. Configure email handlers to send the application to HR and a confirmation to the applicant.

FAQ

Mini Project

Goal: Build a complete event registration webform.

1. Install Webform module via Composer and enable it
2. Create a new webform called "Conference Registration"
3. Add fields: Full Name (textfield, required), Email (email, required), Organization (textfield), Attendee Type (select: Student, Professional, VIP)
4. Add conditional logic: if VIP is selected, show a "VIP Code" textfield
5. Add a page break after personal details, with a second page for "Session Selection" using checkboxes
6. Configure an email handler to send a confirmation to the registrant
7. Enable Honeypot spam protection
8. Test the form by submitting as different user roles
9. Export submissions to CSV and review the data

What's Next

Now that you can build forms, proceed to URL aliases and redirects to create clean SEO-friendly URLs. After that, explore theme anatomy to understand how Drupal themes work.