Okay, it is time to take our brand new Webform component for a test drive. The first step will be to enable our new module. Once the component module has been activated we will create a new Webform to test our IMEI component on.
If we encounter the dreaded WSOD (White Screen Of Death) at any point in the following exercise, then we will need to go back and check that we have entered all the code correctly. Those of us fortunate enough to have access to our web server error log will find information detailing the filename and the line number where the PHP error was found, while the rest of us will have to manually recheck everything, unfortunately.
Some typographical errors may not be serious enough to cause a WSOD, but may instead throw PHP notices or PHP warning errors. These messages will indicate the relevant file and line number to help us locate the error.
We're going to run through a few preparatory steps so that we are able to thoroughly test our component.
- Enable the module by navigating to Modules and scrolling down the page to locate our new module. Check the box and click on Save configuration.
- Let's click on Add content and select Webform so that we create a new piece of Webform content entitled
Webform Test of IMEI Component. Since this is merely a test form, we may leave the other settings as they are and click on the Save button at the bottom of the page.
- Now that we have a new Webform, let's add an IMEI component to it. Let's label the new component
IMEI test, select theIMEIcomponent type, and click on the Add button.
- On the Edit component: IMEI test form where we now find ourselves, let's scroll down to the VALIDATION fieldset, check the boxes next to Mandatory and Unique, and finish off by clicking on the Save component button.
- Finally, we may view our form by clicking on the View tab.
In the last three steps we have successfully tested that Webform knows all about our custom IMEI component. On the component edit form we see that Webform is aware of the features and default values we specified in our code, including the additional fields we created for the component edit form.
On our form view we see that Webform has correctly rendered our component as a textfield, along with the default field description that we set up in our module code. We are happy that the first half of our coding is having the desired effect.
To test the validation processing and display formatting, let's Submit the value 35-209900-176148. This is a 14 numeric digit value (when we exclude the separator hyphens), so we should find that Webform accepts the value, appends a check digit with a value of 1, and stores it in the database as 352099001761481.
When we click on the submission number to view the submission, we see that the display formatting is properly applied.
To ensure that the format of the data in the database is in the form of 15 contiguous digits with no separators, let's click on the Edit tab to see our submission in the EDIT mode.
As a final test of the validation, let us return to our Webform and attempt to Submit a value of 35/209900-176.148-34 (a 16 numeric digit value, which should be picked up as a duplicate remember that the last two digits will be removed in our validation processing).
We have successfully built a custom component from the ground up. At the outset it may have seemed like a terribly complicated process, but by separating the various functions out and understanding what it is that they accomplish, we see that the process is not at all difficult to grasp.
There are three more of the pseudo-hooks relating to custom components that we have not yet touched on.
This function will allow us to make final changes, for example formatting, to data submitted to the custom component prior to the data being stored in the database. In our example, had the specification required that the IMEI component be stored in 12345678-123456-1 format instead of as 15 contiguous digits, then we would have applied that formatting here. This function will be executed whenever data is submitted for this component.
We may at some point conceive of and create a new component that requires extra actions to occur when the component is deleted from a Webform. As an example, the webform.api.php file contains an example of what one may typically see in this function when the pertinent component causes files to be stored in the Drupal file system.
function _webform_delete_component($component, $value) {
// Delete corresponding files when a submission is deleted.
$filedata = unserialize($value['0']);
if (isset($filedata['filepath']) && is_file($filedata['filepath'])) {
unlink($filedata['filepath']);
db_query("DELETE FROM {files} WHERE filepath = '%s'", $filedata['filepath']);
}
}
Whenever this component is deleted from a Webform, this function will fire and delete the associated physical files, as well as remove any reference to them in the Drupal system database file table.