Drupal 10 Webforms: The Ultimate Guide
Webforms have always been a vital ingredient in the World Wide Web cocktail; Humans need an easy and practical way of converting their thoughts into structured data and forms do exactly that. Through the use of various field types, webforms allow users to provide information such as completing surveys or submitting inquiries and support all kinds of interactions like registrations and purchases.
In this Episode...
In this tutorial, we'll be using Drupal's interface and one of its most widely used contributed modules, Webform. The same high-level principles apply to WordPress or any other modern website-building platform.
We'll be using one of our active Drupal projects but the same principles apply to any Drupal website you have installed locally or hosted on a Cloud-based server.
You can always use the tutorials listed below to create your first Drupal website locally as well as push its codebase to a Bitbucket repository and deploy it to the Cloud before returning to this post to continue with the project:
Let's dive straight into it!
This tutorial is also available on ORION WEB. ORION WEB can help you design and build your brand-new web application as well as migrate your legacy site to a modern, feature-rich Content Management platform. Contact us for a free consultation.
The Webform Module: Introduction
It would be an important omission if we didn't mention Jacob Rockowitz, the creator of the Webform module. He started building and maintaining the current version of the module in 2015. One of the things he's mostly proud of is the community-built Webform add-on modules that represent the worldwide impact of his work.
Now, let's dive into the world of the Webform module! From the Webform module's project page on Drupal.org:
The Webform module provides all the features expected from an enterprise proprietary form builder combined with the flexibility and openness of Drupal.
Still on the module's project page, a list of features the module comes with is presented below:
These lists merely cover the primary functions the Webform module provides and it would probably take a whole booklet to mention every feature available. But fear not! You don't have to be a Webform module expert to be able to put your first form together. Read on for a detailed guide on how to build your first Drupal form...
Webform Module Installation
1. Adding the module to our project
1.1. Using the Drupal UI
Drupal provides an easy and accessible way to add a new module to your project. This method doesn't involve Composer and it's not recommended if you're working on a commercial project where all dependencies and packages have to be tracked (if that's the case, skip straight to the Composer method below).
Under /admin/modules/install, the "Add new module" screen is available:
This page allows you to add a module to your project using its compressed files' unique URL. You can also directly download the module's .tar.gz code from its project page https://www.drupal.org/project/webform and then use the "Upload a module or theme archive" field on the module addition page to upload the module's files.
On the module's page (https://www.drupal.org/project/webform), scroll down to reach the Releases section, then click on the latest stable release for your version of Drupal (you should be using Drupal version 10.x at the time of writing):
You should then be directed to the unique URL for that release (something like https://www.drupal.org/project/webform/releases/6.2.2) where you can find the tar.gz link URL, something like https://ftp.drupal.org/files/projects/webform-6.2.2.tar.gz:
You can now use this URL on the module addition page above to install the latest version of the Webform module.
1.2. Using Composer
The recommended and most common method of adding a new module is via Composer, Drupal's dependency manager. This method ensures that all the dependencies of your project are documented with their installed versions as well as their own dependencies. If you have been following our previous LocalGov Drupal tutorials, you should already have Composer installed on your machine. If not, you can go back to our LocalGov Drupal Tutorial #1: Local Installation with Lando tutorial and follow the instructions in the corresponding section.
Open up your Terminal/Command Prompt/Shell and type the following command in your project's root folder (the latest stable project version might have changed since the time of writing this):
composer require 'drupal/webform:^6.2'
2. Enabling the Module
To be able to use the module, we also have to enable it. You can do that on the Drupal UI by visiting /admin/modules (in the screenshot below, we have already enabled the main Webform module as well as the Webform UI sub-module which allows us to configure the module on the Drupal UI):
Alternatively, you can enable the module via drush (we are using DDEV to run drush for this example but you can also use the equivalent Lando command if that's how you've set up the project locally):
ddev drush en webform
3. Exporting Configuration into Code
After enabling the module, we can also export all related settings to configuration i.e. in code. To do that, we run the corresponding drush command:
ddev drush cex
The same step should be repeated whenever we change any configuration settings around the Webform module (or any other site-wide settings) to make sure that our code is always up-to-date. This (as well as the next Git version control step) is essential in deployment workflows where every code deployment/release comes with a configuration import step. That way, if you apply any configuration changes on any environment (that could be the live site, for example) and you export all of these changes into code (locally, for example), nothing will get overwritten when a deployment imports the configuration back to the website. You can read more on Drupal's Configuration Management here.
4. Updating our Remote Code Repository
If you're maintaining your project on a remote repository, you can commit and push your code changes:
git add -A
git commit -m "Adding and enabling Webform module"
git push origin master
(master is the main branch used for this example but it could be a different branch in your case.)
Now that we have added and enabled the Webform module, we are ready to explore its rich features!
Webform Module Permissions
Under /admin/people/permissions#module-webform, you can review and set up permissions for all webform-related actions and tasks, per user role:
There are numerous permissions under the Webform section on this page which allow you to fine-tune what each role can do. If you're implementing a content moderation workflow with various content editor roles, publishing states and transitions between publication states, you'll find yourself making more use of the module's permissions. On the other hand, if you're working on a simpler project, with a minimum amount of users logging in for administrative tasks (it might as well be just you), you'll most probably not have to change much (if any) on the permissions page for this module.
Global Webforms' Configuration
Below, we are presenting the main screens that come with the Webform module:?
1. Forms (/admin/structure/webform):
Navigate to Structure > Webforms or type the page's path directly to access the main screen:
Here, all the available webforms are listed along with some useful information:
2. Submissions (/admin/structure/webform/submissions/manage):
This leads to the Submissions screen where you can access and manage (purge, for example) all the previous submissions for every Webform.
3. Options (/admin/structure/webform/options/manage):
The Options configuration page lists reusable predefined options/values available for select menus, radio buttons, checkboxes and Likert elements. ?For example, the Days element looks like the following:
You can edit all available presets to your liking and also maintain your own bespoke options library.
4. Configuration (/admin/structure/webform/config): This is the global configuration settings page and applies to all Webforms on your site.
These screens provide a plethora of settings, including:
5. Add-ons (/admin/structure/webform/addons):
The Add-ons page lists Drupal modules and projects that extend and provide additional functionality to the Webform module and Drupal's Form API. You can find hundreds (251 at the time of writing this) of different modules on this page as well as links to their dedicated Drupal project pages.
6. Help (/admin/structure/webform/help):
The Help page (/admin/structure/webform/help) offers a useful selection of links to tutorials and documentation pages around the Webform module, its functionality as well as integrations.
Creating a Webform
At the bottom of the Forms page (/admin/structure/webform), you can see a default "Contact Us" form listed. This webform was automatically created when we enabled the module (but we have since changed its title from "Contact" to "Contact Us"). You can use this contact form as is or configure it further according to your needs. Alternatively, you can delete this webform and create your own from scratch. For the purposes of this tutorial, we'll be adding a brand new webform to our website.
Clicking on the "+ Add Webform" button reveals the following popup dialogue box (we have populated the fields with some information already):
In the Categories field, we have selected Other but also added a new category, "custom forms".
Upon clicking "Save", our new ORION Webform is created and we are redirected to its dedicated screen (/admin/structure/webform/manage/orion_webform):
Adding a Webform Field (Element)
The webform is there but it has no fields so let's add some! Click on the "+ Add element" button to select a field type to add to the Webform. As you can see, there's a huge number of field types available (for the sake of the screenshot we have closed all the available field groups apart from the first one, Basic elements):
We are going to add a humble text field for a start. Upon clicking on "Add element" next to "Text field", we are presented with the "Add Text field element" side dialogue box which consists of several tabs. The same tabs are also available for existing fields we've previously added so don't worry if you realise you've missed something after pressing "Save"; There are always additional opportunities to configure your Webform fields!
Let's see what options are available under every tab:
"General" element settings tab:
These settings are the first to appear every time we add or Edit a field. Depending on the selected field's type, the settings under this tab can vary but some of the fields will always be fixed (the Title for example).
There are numerous settings and options available on this screen:
Element settings:
These are the primary settings for our field:
Element description/help/more:
This section allows us to add helpful information we want to display to our users. Simple fields like First name don't require additional help text but, for the sake of this tutorial, we've added some dummy wordings here so we can see how they render later:
Here's the list of the settings/fields available in this section:
Form display:
These settings and fields are related more to how the form renders on the front-end.
Here's the list of the settings/fields available in this section:
Form validation:
These options/fields allow us to add validation to our field. The simplest setting usually applied here is "Required" but more complicated ones - such as regular expressions - can also be used, depending on the requirements of the project. For our First name field, we have only really ticked "Required" but, in the screenshot below and to show you all the available fields, we display this section of the form with all options ticked:
Here's the list of the settings/fields available in this section:
Upon saving the field form, we land on the webform's Build page (/admin/structure/webform/manage/orion_webform):
We can click on "View" to get a taste of how our webform looks like:
(For the sake of the screenshot, we've hovered over the field's help text icon to display the help title and help text wordings.)
Adding More Fields
Following the same workflow, we are going to add the following fields to our webform:
Following the addition (and saving) of these fields, the resulting Build screen should look like the following:
The resulting View screen looks like the following (your front-end theme will most probably look completely different compared to the theme used for this demo):
领英推荐
At any time, we can always go back to the Build screen of any webform (for our example webform the path for this screen would be /admin/structure/webform/manage/orion_webform) and view the fields it consists of. Clicking on the "Edit" for any field opens the element edit dialogue box on the right side of the screen.?
We have explored the settings available under the General tab. We are going to have a closer look into the other element settings tab available for every field.
Additional Field (Element) Settings Tabs
"Conditions" element settings tab:
The conditions tab comes after the General tab/screen of settings for any Webform element (field) and provides the ability to add conditional logic between fields. This feature is making use of Drupal's States API. A "state" means a certain property on a DOM element, such as "visible" or "checked". A state can be applied to an element, depending on the state of another element on the page. In general, states depend on HTML attributes and DOM element properties, which change due to user interaction.
It is important to understand that all states are applied on presentation only i.e. on the loaded page and on the user's client (a web browser for example). None of the states force any server-side logic, and, as a result, they will not be applied for any of your site visitors without JavaScript support.
In the screenshot above, we are looking at the conditional logic for the First name field. In the "State" dropdown we have the following options:
Visibility:
State:
Validation:
The states above describe resulting behaviours we want our "controlled" field to exhibit, based on certain conditions. For example, we might want a field to only be required when a checkbox field is ticked or a text area field is populated with text. Or we might need a field to be hidden at all times, apart from when another text field is filled in with a certain pattern of text. Countless combinations are possible and, at ORION WEB, we have never encountered a conditional logic scenario that can't be implemented using field states.
Every condition consists of the "controlling" field and the trigger (action):
For example, a trigger could be a text field being populated ("Value is") with a specific wording, or a text field being filled in with a number "Greater than" 1000. Needless to say, upon selecting the trigger on the UI, we'll be prompted to add a value for the selected trigger. For example, we can set the First name field to not be required if the Last name field has been populated with any value but "Smith" (this scenario will probably never manifest in real life but it's perfect for the purpose of demonstrating how states work):
After we've set our states and "Save" the field, we can "View" the webform and confirm that our states work as expected.
We can also join conditions together with the following operators:
That way, we could fullfil scenarios like the following:
"Field C should only be visible IF Field A's Value is "X" AND Field B IS NOT Empty"
"Field B should be Disabled IF Field A's Value is Between 0 AND 10000"
Drupal's states add an extremely valuable layer of automation to webform implementations which would normally require custom code to be written instead. Make sure you try out different scenarios - it's always fun to see how a webform gradually becomes animated!
"Advanced" element settings tab:
Moving on to the "Advanced" field settings, we can again control how our field will display and/or behave by setting certain attributes:
The first section allows us to define a default value for our field. This can be set for any kind of field that accepts value(s) from the user and it's really handy when we need certain value(s) to be pre-set for the user to leave as is of ammend. A field's default value will still be taken into consideration when any set conditions (as described above) get evaluated and the field will play its dynamic role accordingly - it'll either "control" another field (or set of fields) or be "controlled" by another field.
The additional sections (right below the Default value section) are mostly related to how our field will look like on the front-end i.e. whether we want to enrich its looks with additional styles and/or classes and/or additional attributes. Most of the time, there are three main sections here (some field types will have less settings available, for example Fieldset type fields only have Element attributes):
Wrapper attributes:
Element attributes:
Label attributes:
Moving on, the "Advanced" element settings tab also includes the following settings (for most field types):
The following sections are included here:
Submission display: This section allows us to format the results of webform submissions i.e. provide a custom way of presenting the submitted data.
Single item > Item format: This field allows us to select how a single value is displayed in the webform submissions. There are three possible options here:
Here are the Twig variables that can be used in the custom HTML and custom Text fields:
All of these variables, according to what their name suggests, represent piece of data related to the webform submission or a more broad context such as the site's language code, metatags or the current page.
You can read more about Twig, Drupal's default template engine in the following sources:
Let's move on and explore the remaining settings available in the "Advanced" element settings tab:
Administration:
Custom settings:
"Access" element settings tab:
The last tab of settings available to us when we edit a webform element has the following three main sections:
1. Create submission:
This section allows us to select roles and users that should be able to populate this element when creating a new submission. By default, all the existing roles of our website are selected, which means that this webform can be submitted by everyone.
We can limit this according to our requirements. For example, when a project demands only a certain sub-group of logged-in users to have access to a webform, this can be defined here. We can even add certain users registered on our website or even specific permissions a user should have in order to be able to access and submit the webform (all relevant permissions will be displayed in a list the second you focus your cursor in the "Permissions" field below):
2. Update submission:
This section offers the same set of fields as the one above it ("create submission") and it allows us to select roles and users that should be able to update this element when updating an existing submission. In other words, this setting refers to the ability of, not only accessing submissions for the webform this element belongs to, but also, being able to change the data submitted for this element in the "parent" webform's submission records.
3. View submission:
This section allows us to select roles and users that should be able to view this element when viewing a submission for the webform this field belongs to and, as expected, it consists of the same set of fields as the two sections above it:
The last setting displayed at the bottom of the "Access" element settings tab is the "Display element" checkbox. If unchecked, the element will never be displayed and it will only be visible within the form builder and hidden from all other displays including submission details, results, and download. This can be handy when we are working on a field (as part of a minimum viable product (MVP)'s next phase for example) and don't want to display it publically in the current phase of our project.
This concludes the analysis of the settings and options available as part of editing an existing or creating a new field in a webform. In the next section, we are going to incorporate our webform into content!
Incorporating Webforms into Content
There are various method of displaying webforms in content and making them accessible to their target "audience":
1. Direct access to the Webform URL
By default, every webform can be access via its dedicated URL. This is automatically generated when a webform is first created and the setting that defines this behaviour is available on the Settings page of every webform. For our "ORION webform", that path would be /admin/structure/webform/manage/orion_webform/settings. On that settings page, the following section, URL path settings exists:
As you can see in the screenshot above, you can always set your own preferred URL alias for every webform i.e. override the default URL pattern assigned. This section also alllows us to set a custom confirmation page URL alias (which, by default follows the format /form/{webform-id}/confirmation?token={DISTINCT_TOKEN}).
Finally, the "Page theme" dropdown allows us to select the theme we want used to display any webform. The Default setting will use the front-end theme to render the webform.
2. Using the Webform content type
The Webform module comes with a large number of sub-modules. One of these sub-modules, Webform Node, provides a Webform content type which allows webforms to be integrated into a website as nodes.
With the Webform Node module enabled, under Structure > Content types (/admin/structure/types), we can now see the Webform content type and its settings are available under /admin/structure/types/manage/webform. Its manage fields screen (/admin/structure/types/manage/webform/fields) looks like the following:
The second field on the screenshot above is of the "Webform" type and allows us to reference an existing Webform on our Webform nodes.
On the "Add content" screen (/node/add), we can click on the "Webform" content type to add a new node of this type. The Webform node add screen (/node/add/webform) looks like the following:
The Webform dropdown should now allow you to choose one of the existing webforms on the website. The Webform nodes behave like nodes of any other content type and can be configured (field settings, node form settings, ?display settings etc.) on the UI and also themed according to your project's requirements.
3. Attaching a webform to any content type
We can always use a different content type to attach our webforms to i.e. we don't have to necessarily use the Webform node content type described above. To do that, we'll have to add a new field to a content type of the "Webform" type. To do that, we select our content type of choice on /admin/structure/types and then click on "Manage fields" > "Add field".
For example, for our "Post" content type, here's how the field add screen looks like:
Upon selecting "Webform", we'll get the usual field settings dialogue from Drupal. You can select the defaults and save the field. Next time we edit this content type, we'll also get the newly added Webform reference field on the node add/edit form:
The dropdown at the top of the screenshot allows us to embed any existing webform and, below that, we are presented with a couple of handy settings that will affect only this embedded webform instance.
4. Attaching a webform to a block
To attach an existing webform to a block, we'll use the Block Layout screen available under Structure > Block Layout (/admin/structure/block). On that page, you'll see all the available regions for your front-end theme. Pick the region you want to add the webform block to and click on "Place block":
Type "webform" in the search field and then click "Place block" next to "Webform". This will open the "Configure block" popup window. Search for the webform you want to attach to this new block (in this case we've selected "ORION webform":
There are lots of available settings to configure here and similar settings exist for any type of block:
The "Webform settings" section offers the ability to define the structure of the submission data in YAML syntax (this is also available on the webform settings level).
Below this section, we have the classic visibility settings available for every type of block:
In this section, you can limit the scenarios where you want the block to appear by Page(s), User Role(s), Content Type(s) and Taxonomy Vocabularies. The two webform-related tabs, "Webforms" and "Webform" can be left with their default settings as this is a webform block and we are not intending to attach it to a webform (that could a weird loop of existence for our webform block!).
We then "Save block" and our webform block should now appear on the front-end and in the region we added it to!
Webform Configuration & Source
Drupal webforms are configuration entities which means that they can be exported to YAML files and this makes it easy to transfer a webform from one environment to another.
1. Webform Source YAML
For every webform, on the "Build" screen, we have the "Source" screen available right next to "Elements":
The "Source" tab displays the YAML file for the current webform. The syntax is human-friendly and easy to understand and, from observing a webform's source code in YAML, you can learn lots of things about the properties and building blocks of a webform (note the hashtag # symbol in front of every attribute). According to the message at the top of this screen, the (View) Source page allows developers to edit a webform's render array using YAML markup. Developers can use the (View) Source page to alter a webform's labels quickly, cut-n-paste multiple elements, reorder elements, as well as add custom properties and markup to elements.
1. Export & Import Webform Configuration
On the top level of every webform's settings, we can also find the "Export" screen:
The configuration displayed here is a full representation of the webform object as it includes configuration-related properties such as the webform's distinct configuration uuid and the webform's properties (contrary to the YAML Source screen which primarily focuses on the webform's fields).
This screen basically allows developers to quickly export a single webform's YAML configuration file. A single webform's YAML configuration file can easily be imported into another Drupal instance, using the configuration import screen available under /admin/config/development/configuration/single/import?config_type=webform.
An example scenario for this would be getting (exporting) a webform's configuration from the live environment and importing it locally to work on expanding the webform and its features. The resulting (updated) configuration would then be re-imported as part of a deployment cycle and it would finally reach the live environment and refresh the webform's configuration with the updated version.
Webform Email Handlers
We've already covered the submission records available for each webform. Sometimes we need to immediately notify certain people in our organisation about submissions coming from a webform. Email handlers do exactly that and are available under /admin/structure/webform/manage/{WEBFORM_ID}/handlers for every webform on our site. By clicking on "+ add email", the corresponding popup dialogue box appears:
Numerous settings allow us to set up the following:
Most of the settings above are token-friendly and some of them already have tokens as default values. As a refresher, tokens are placeholder variables and as records are displayed, contextual values are replaced, such as [current-date:medium] or [site:name]. This means that, in the fields described above, we can use tokens from the corresponding popup ("Browse available tokens") and that way, we can enrich our webform submission results' emails with additional information:
Conclusion
We have managed to create a brand new webform, populate it with fields, configure it according to our requirements and display it to our users - from here, the sky is the limit!?
The Drupal community has gone a long way with repairing issues and enhancing features and, as a result, most common scenarios should always be covered by the "out-of-the-box" functionality of the Webform module. You can always further develop your webforms and create more beautiful experiences for your site's visitors.
ORION WEB can help you design, build and configure beautiful user journeys. Contact us for a free consultation - we'd love to discuss your organisation's digital strategy!?