The purpose of Webform is to enable rapid form development, so we're going to add our first component and specify some settings for it. To avoid repetition in the process descriptions when adding other components, we will go over the settings of this first component in great detail. As we move on to additional components, the process descriptions will only deal with new settings specific to that component type. Due to the practical nature of this demonstration, it is recommended that we read the following while referring to the relevant on-screen displays.
When we saved our node we were automatically redirected to the page that enables the adding of components. Any time in the future we need to add or make changes to any of our form components, we can click on the WEBFORM tab above our form and then on the Form components subtab as shown in the following screenshot:
- The first field on the form is going to be where we can capture the first name of the registering speaker, so let's enter the text First name in the textbox that reads New component name under the heading of LABEL.
- The type of component we wish to add is a textfield, so ensure that textfield is the selected TYPE in the drop-down list.
- We will want to force registering speakers to enter something in this field as their names need to be known, so let's check the box under MANDATORY and then click on Add to create the component.
- Every component has additional settings, which we can use to manipulate the display of the component, or affect the validation of user entered data. The component settings page we have been redirected to exposes these additional settings. Because each component type is different, there will be differences in the settings that will be shown on this page for each component type. For now though, we will accept the defaults and click on the Save component button at the bottom of the page to return to the Form components overview page:
Our First name textfield has been saved and is shown in the components table. The hyphen in the VALUE column indicates that we have not specified a default value for this component on the component settings page.
When the form is rendered, that is, shown to site visitors, the component name we just supplied will be shown as the field label. A red asterisk will appear after the label to indicate that the field is a required input - if the site visitor leaves it blank, Webform validation will not allow the form to be submitted.
After clicking on Add on the Form components page we are redirected to the component settings page where we can fine tune how the component will be displayed as well as additional validation rules.
This is the field name we entered on the previous page and can be changed at any time. When the Webform is rendered this is the label that names the input field. It is a required field on the settings page and will also be used to identify the column of data in reporting.
The field key is automatically generated by Webform and is based upon the very first name given to a component. This key is used to identify the component internally to the system and is built using rules specific to database and programming languages. As indicated by the red asterisk, this is a required field on the settings page.
Should the component label above be changed at any time, the field key will remain the same as it was. We may change this value if we wish, but it is just as well to leave it alone as it has no bearing on the user experience. This is also the name of the field as we will use it when we write custom code for our Webform.
Under certain circumstances we may want to have a component pre-populated with data. All components that support this feature will have a Default value option on their respective settings pages. We are not limited to only those default values, we can type in other values ourselves. Webform also has support for a variety of token values (given as follows) that may be used to specify defaults.
Tokens are basically placeholders that will be replaced by an actual dynamic value when the form renders, for example, the token %username will be replaced by the actual username of the logged in user. When we click on the TOKEN VALUES heading we see a listing of all the tokens that Webform supports. Note that a token name starts with a percentage symbol (%) which is immediately followed by the token name.
Certain token names refer to a group of possible tokens, so we need to specify the exact field from the group which we want to use. This is achieved by naming the specific field by its key in square brackets immediately following the token name, for example, %tokenname[key].
There are times where we would like to explain to the end user what the purpose of a particular field is or what kind of information is being requested. Webform permits us to specify some explanatory text here which will display below the field when the form is rendered. Note that we may make use of token values (see the previous description) in this description.
The Webform module makes some basic field validation available to us. Users will be unable to submit a form if any one or more of these rules is broken by their attempted submissions. The field validations are as follows:
- Mandatory: Check this box if a field absolutely must receive a value from the end user and may not be left blank. By default, if this setting is checked, the field label will be marked with a red asterisk to indicate that user input is required for this field.
- Unique: This is a useful setting for fields where no two form users may enter the same value, for example, e-mail address or passport number. We should exercise care when using this setting as we must be sure that it is a reasonable setting to apply. Imagine the frustration that would be experienced if we set this validation for a first name field for example.
- Maxlength: Here we can specify the maximum number of characters that users may enter into a field.
We have several options that can affect the manner in which a field is rendered on the form as follows:
- Width: This setting defines the number of characters that will be visible in the text field.
- Label placed to the left of the textfield: It can be helpful to place an additional label to the left of a field to give the user an idea of the type of information required. For example, assume we have a field called Amount, we can enter a US Dollar symbol ($) here to indicate the currency type to the user.
- Label placed to the right of the textfield: Similar to the previous point, there are contexts where the descriptive label should rather appear on the right, for example, on a Weight field we may want to indicate that value entered should be in kilograms by specifying kg here.
- Label display: Field labels may be specified to be displayed above the input field, adjacent to the input field, or not at all.
- Disabled: Occasionally we may wish to show to our form users a default value that they may not change, such as their username token value. To make the field value non-editable we check this box.
- Private: Certain fields may be required for the use of form administrators, but do not require any form user input. By checking this box, only form administrators will have access to this field and it will not be shown when the form is rendered to non-administrative users.
After saving our component settings we find ourselves back on the Form components overview page where we see that the saved component now has three Operations links. The various operations are as follows:
- Edit: The edit operation allows us to effect any changes we may need to make to the current settings of a component.
- Clone: When we find ourselves needing to create several components of the same type with similar settings, we will find our efficiency is improved by merely cloning (making a copy of) an existing component. All we need to do is specify the label and field key for the new component and click on Save component to create the new component.
- Delete: Allows us to remove existing components from our form. Following through on this action will also remove all data that has previously been submitted for this component by user submissions. Use with care as the delete action is not reversible!