Form Processing : the OO Way

Apparently, the old saying is true: great minds think alike. Well, that may be giving me too much credit, but in a post last week by Ben Nadel here, Ben was continuing his exploration of object orientation.

I made a comment about how OO, though definitely not a magic bullet, could assist us in handling forms. Over the weekend, I started writing some code to explain this. The industrious Mr. Nadel came up with a solution.

I had in mind a more universal solution, which this post will detail.

Let's start with with a simple form. The form can either be called directly -- or it can be called from its corresponding CFC. Suppose we have a form called "MyForm" that looks like this:

(You can see this code running here.)

Apart from the CFINCLUDE of "MyForm.pgm" -- wel'll get to that in a moment -- it's a pretty standard form.

But we want some validation on the form. We can, of course, use standard client-side processing using jQuery or qForms or any other number of solutions. But these suffer from some problems:

(a) What if we have a constraint that the client can't know about -- usernames being unique, for example? That precludes a strictly client-side approach.

(b) We still need validation on the server, so any code we write for the client will be additional code.

We can solve these problems by moving validation to the server and using Ajax to do our form submission and alerting of any errors. To do this, each form will have its own corresponding CFC. Since we have "MyForm.cfm", we'll have a "MyForm.cfc" that looks like this:

Notice that the structure, "variables.instance" holds two keys: "value" and "rules". The "value" variable will be used to store the user responses; the "rules" variable is another struct with the rules we wish to apply to this particular field. Again, we'll see how these are put to use shortly. For now, just note that we can have a variety of rules and that any field can have zero or more rules applied to it.

Next, I've created an array called "variables.instance.errors". This will be used to collect any validation errors encountered and will, eventually, be sent back to the client.

The first method we encounter is "display". I mentioned above that the form could either be called directly or, as in this case, from the form CFC by calling its "display" method. The choice is a personal one; I don't see either as having a clear advantage over the other.

Next, we have a "populate" method. This method will be called when we want to submit the form. Of course, in "MyForm.cfm", there's no code to do submission. We'll handle that shortly in "MyForm.pgm". The "populate" method has arguments corresponding to the names of the forms. (To make this particular scheme work, the id of the field and the name of the field need to be the same.)

Inside "populate", I loop over the arguments. If a corresponding entry in "variables.instance" exists -- that is, if an argument named, say, "age" has a corresponding "variables.instance.age" entry -- we place the value of the argument in that structure. The value, of course, is the entry the user made in the form.

Next, we call the CFC's "validate" method, sending the entire structure entry for that argument. So, staying with our "age" example, we pass "variables.instance.age" which contains both the user's entry in that field and the validation rules that should be applied to this field.

I then have an empty "if" statement that checks to see whether there are any errors. Right now, it doesn't do anything -- we'll see shortly how this might be used. Finally, I return the entire "variables.instance.errors" array in JSON format.

So, what about this "validate" method? It's awfully short. That's because it uses an external validation class. The nice thing about this class is that it can be used for any sort of validation -- it has no idea that it's being used as part of this plan; it just does simple validation. Inside our "validate" method, we accept the "id" of the field (which matches the "name" of the field) and the "fieldStruct" -- the entry in "variables.instance" that corresponds with the field being validated. So with our "age" example, "id" would be "age" and "fieldStruct" would be the structure: .

A blank structure called "response" is declared and initialized. Then, I loop over the rules in "fieldStruct", calling that third-party validation class (I've set this up in my Application.cfc's "onApplicationStart" method to instantiate it in the application scope), using the validation class's "validate" method. That method is passed the "ruleName" (e.g. "datatype"), the arguments for that rulename (e.g. "numeric"), and the value the user entered.

The validation CFC returns a structure with two keys: "valid" (a Boolean) and "msg" (a string explaining the type of validation error). If validation produced a "valid" value of "false", we've encountered an error and the "response" structure is added to the variables.errors array.

Heading back to the "populate" method, we can see that after all validation processing is done, I've returned that errors array.

We're going to look at "MyForm.pgm" and see how all this integrates, but first, let's take a quick look at "Validator.cfc" -- that class responsible only for doing simple validation:

This class is not dependent on any particular form: it has methods that can do a wide variety of validation -- and of course, you can add to the ones I've shown here.

Now, let's head over to "MyForm.pgm", which was included in "MyForm.cfm":

I begin by creating a CFAJAXPROXY to "MyForm.cfc". I instantiate that JavaScript class under the name "myForm"; it could be anything I choose. I set a callback handler -- a function that will be called when "MyForm.cfc" returns its response from the "populate" method. Inside this anonymous function, after checking that the array has some elements in it, I loop over the array, using jQuery to populate the various "msg" elements with the error message supplied to it by our Validator.cfc.

If there were no errors, I used an alert box.

Also, "myForm" has an error handler -- not very robust, but this is demo code.

How does the form get submitted? I begin by trapping the form's normal submission process. I then empty out anything in the various message elements. This is necessary in case validation failed and the user resubmits the form -- we don't want old error messages hanging around when they may no longer be valid.

I then call "myForm.setForm('myform');" This is a ColdFusion feature of the CFAJAXPROXY tag. It alerts ColdFusion that the next call to the "myForm" proxy should send all the form data inside the form with an id of "myform". That "next" call is immediate: "myForm.populate();". This automatically sends all form fields (with user-entered values) to the "populate" method, whose responsibilities we've seen before.

The final piece is to "return false" so that normal form processing is not attempted.

A couple of other points should be made.

1. I used a ".pgm" file. Why? I do this in order to separate the HTML markup from any processing that occurs. This isn't always possible -- if I were looping over a query, say, I'd have the CFLOOP on the .cfm page, but in general, it keeps a nice separation -- and makes it easier for designers to apply their design magic.

2. I have an empty CFIF based on whether the array is empty. In a real situation, this is where (if I were working with objects), I would instantiate the object and cause it to be persisted.

3. In a real environment, I wouldn't simply alert the user the form had been processed, but would take them to the appropriate page.

4. As some of these points illustrate, this is demo code. In a real situation, I'd need to "robustify" the code.

Apart from those, I'm pretty happy with this solution. What do you think?