In a specific business context we may find benefit in creating custom components for our Webforms. In this manner, we can apply specific customized validation and formatting rules to a component type that is available to all Webforms across our website. Additionally, we may set the component up with various defaults already in place, making things easier on our developers, as well as the administrative folks who create our forms.

In Webform, a component is a unit of functionality that encapsulates a data field and defines how that field will look, how the field may be used, and what validation criteria need to be satisfied on data input. We see, then, that a component is much more than just a data entry point, as it includes all of the required functionality around.

The exercises in this chapter will see us building a demonstrator custom component which will enable the capturing, basic validation, and formatting, of mobile telephone IMEI numbers (International Mobile Equipment Identity numbers). Let's discuss the specifications for our component a little before we start, so that we have a clear idea of where we're heading.

According to the information available on the Wikipedia web page at http://en.wikipedia.org/wiki/International_Mobile_Equipment_Identity there are three ways that an IMEI number may be expressed, all of which affect the length of the number that will be input. The submitted number may:

Our validation processing will need to take these factors into account.

An additional challenge that we face is the presentation of the IMEI number. While the typical 15-digit standard IMEI number is composed of three groups of digits (eight digits comprising the Type Allocation Code, six digits comprising the device serial number, and the one check digit), not all manufacturers specify the number in that exact grouped format. Then, we need to also bear in mind that there may be almost any number of punctuation type characters (for exaxmple, hyphens, periods, or slashes) contained within the numbers our users will enter.

From a usability perspective, it is easier for our administrative users to work with only the numeric digits, so any separation characters (that is, hyphens, periods, or slashes) should be removed from the input data. Having said that, though, we would like the submitted IMEI numbers to be displayed in the full standard format (for example, 12345678-123456-1) when submissions are being viewed, e-mailed, or downloaded. When submissions are being edited, however, the number should be displayed as 15 contiguous digits.

In the case where the user-entered IMEI number contains 14 or 16 numeric digits, we need to calculate the check digit value according to the Luhn algorithm (http://en.wikipedia.org/wiki/Luhn_algorithm) and append it to the input. In the case where the submitted value contains 15 digits (that is, it already includes the check digit), we are required to ensure that the check digit is valid according to the Luhn algorithm. The intention is that only 15 digit IMEI numbers will be stored within our database.

The Luhn algorithm was developed by Hans Peter Luhn as a method of protecting against data capturing errors. The intention behind the algorithm is to provide a method of ensuring that a sequence of digits, such as a bank account number, for example, has been correctly entered. The algorithm accepts a sequence of digits as input, calculates a check-digit value, and appends that check digit to the original sequence of digits. Let's take a quick look at how it works by using an arbitrary string of numeric digits (6488) to calculate the value of check-digit X.

Getting back to the requirements for our component, certain defaults must be set when a new IMEI component is added to a Webform. We would like the component to have a standard description already populated to save Webform administrators the bother of having to type it out each time such a component is added to a form. The component should automatically be set with a maximum input length of 25 characters (to allow for the 14 to 16 numeric digits as well as some separation characters).

The final requirement of our specification is to include the optional uniqueness validation, which will ensure that no IMEI number occurs more than once within our database.

Perhaps this all sounds very complicated and tricky to implement, but we will be relieved to see how the Webform API makes the creation of seemingly complex custom components rather easy. Each phase in component creation breaks the overall problem into small digestible steps.

A file exists in our Webform module folder at sites/all/modules/webform/webform.api.php which contains helpful reference information to supplement the examples listed below. Note that the full coding given in the following exercises is required for our component to work as expected. Screen displays will be shown to illustrate various aspects of what we cover and these, again, will likely only be visible on our site once we have completed all of the project code.