Our first step towards defining our component to Webform is hook_webform_component_info(). In this hook we give our component a name, a description, and a list of Webform features we would like to enable or disable.
Using our favorite text editor, let's open our module file for editing so that we may start the process of defining our new Webform component.
When we utilize a hook we must be careful to rename the function according to our module name. With that in mind, let's add the following code to the new webform_imei.module file we created previously:
/**
* Implements hook_webform_component_info().
*/
function webform_imei_webform_component_info() {
$components = array();
$components['imei'] = array(
'label' => t('IMEI'),
'description' => t('IMEI number type.'),
'features' => array(
'csv' => TRUE,
'email' => TRUE,
'email_address' => FALSE,
'email_name' => FALSE,
'required' => TRUE,
'conditional' => TRUE,
'title_display' => TRUE,
'title_inline' => TRUE,
'private' => TRUE,
'group' => FALSE,
'spam_analysis' => FALSE,
'attachment' => FALSE,
),
);
return $components;
}
In this function we have given Webform a very high-level definition of our IMEI component. Webform now has a name for our component type and a simple description of what it is used for. We have also listed a bundle of features and specified whether they are enabled (TRUE) or disabled (FALSE).
The component label that we defined in the array is the name that will appear in the component selection drop-down list on the Webform Form components page.
Let's take a look at what the various feature switch elements in our array mean. Strictly speaking, we do not need to list all of these in our definition, as Webform provides default settings, but it is just as well to be specific about what we want.
Some of these settings pertain to the way Webform handles our component internally, whereas others apply to the component edit page (that is, the page we see when we add a component to a form).
Unless we have good reasons for not wanting the user-entered data for this component to appear in our CSV downloads, this setting will generally be set to TRUE.
Here we are allowing this component's data to be sent in e-mails. When we're working with sensitive data, such as passport numbers, for example, we may opt to not include this component in e-mails.
Our IMEI number component can never contain a valid e-mail address, therefore we do not allow this component to appear as an option when setting up FROM: or TO: e-mail addresses on our Webform Emails form.
We do not want our IMEI component used as a FROM NAME: or TO NAME: in our Webform e-mails as its numeric nature may cause the e-mails to be flagged as spam.
This indicates that we want to be able to optionally set our component as required (mandatory) on the component edit page.
This setting enables us to use this component as an option when defining other components as being conditionally displayed (that is, they will only display if the selected component meets the specified logical criteria) on the component edit form. Note that conditionals only apply when we have a multipage Webform.
With this setting we can cause our component to optionally display above the component, or not at all. This setting is found in the DISPLAY fieldset on our component edit page.
Here we permit the component title to optionally be displayed in line with the component, as opposed to the default where it displays above the component on the client form.
This setting enables an option which allows us to hide the component from anyone who does not have Webform results access. In other words, no one other than a site administrator will ever see this component when this option on the component edit form is enabled.
Certain components, for example fieldsets, can act as a group container of other components. This is not true of our IMEI component, thus we disable this feature.
Some contributed modules, such as Mollom, can analyze submissions to determine whether they're spam or not. Here we are not allowing such modules to inspect data submitted to our IMEI component type.
If our new component required form users to upload a file that we would want to attach to our Webform e-mails, then we would set this to TRUE. We do not need this functionality for our IMEI component, so we disable it here.
We may make use of another hook called hook_webform_component_info_alter to make changes to the definitions of any existing Webform components. This function is called after all components have been loaded, so we can override the required settings by changing the appropriate array. For example, to change the label of all textfield components from Textfield to Text Field, we would implement this hook containing the line $components['textfield']['label'] = t('Text Field');.