Objective Bias

A while ago, Brian Kotek released his FormUtilities.cfc. It's a very useful tool that allows you to create implicit arrays and structures from form fields which can be arbitrarily nested. Not only is this useful for dynamic forms where you don't know in advance how many sets of data will be submitted, but it can also be used to address the "all or nothing" nature of the entire event object being submitted along with the form in framework-based applications. Read more about this in Brian's blog post. I definitely saw how this could be useful in my ColdBox development, so I made a plugin out of it.

All I had to do was make some minor adjustments to the <component> tag and init() method of the CFC (which you can download from RIAForge):

<cfcomponent name="FormUtilities" hint="Form Utilities" extends="coldbox.system.plugin" output="false"> <cffunction name="init" access="public" returntype="any" hint="Constructor."> <cfargument name="controller" type="any" required="true" /> <cfscript> super.Init(arguments.controller); setpluginName("FormUtilities"); setpluginVersion("0.1"); setpluginDescription("Form utilities"); </cfscript> <cfset variables.instance.updateFormScope = true /> <cfset variables.instance.trimFields = true /> <cfreturn this /> </cffunction>

So, I had to make sure the component extended the base plugin (coldbox.system.plugin). The init() method takes the ColdBox controller as it's only argument and then there is some plugin configuration info in the cfscript block (read more about this in the ColdBox docs). The updateFormScope and trimFields variables were arguments in the original CFC which I just set to "true". I dropped this CFC into my plugins folder and I'm ready to use it.

To use it, let's say I had a simple user registration form in my site. The form would normally look something like this:

<form method="post" name="Userform" action="#event.buildLink('user.handleForm')#" /> <input type="hidden" name="userId" value="#oUser.getUserID()#" /> <label for="firstName"><b>First Name*: </b></label> <input name="firstName" type="text" id="firstName" value="#oUser.getFirstName()#" /><br /> <label for="lastName"><b>Last Name*: </b></label> <input name="lastName" type="text" id="lastName" value="#oUser.getLastName()#" /><br /> <label for="email"><b>Email Address*: </b></label> <input name="email" type="text" id="email" value="#oUser.getEmail()#" /><br /> <input type="submit" name="Submit" value="Submit"> </form>

In my user.handleForm event handler method, I would do something like this to populate a userBean with the values entered into the form:

<!--- get an empty user object ---> <cfset var oUser = getUserService().getUser() /> <!--- populate it from the rc ---> <cfset getPlugin("beanFactory").populateBean(oUser) /> <!--- bean validation and persistence logic follows --->

That's all well and good. But we're throwing the entire request collection structure at the user bean (not just the form values). For simple cases like this, this approach might suffice. But what if, for example, you have a large, complex form that you want to use to populate multiple beans? The form utilities plugin allows you to implicitly create child structures within the request collection structure. So, we can modify our form this way:

<form method="post" name="Userform" action="#event.buildLink('user.handleForm')#" /> <input type="hidden" name="user.userId" value="#oUser.getUserID()#" /> <label for="firstName"><b>First Name*: </b></label> <input name="user.firstName" type="text" id="firstName" value="#oUser.getFirstName()#" /><br /> <label for="lastName"><b>Last Name*: </b></label> <input name="user.lastName" type="text" id="lastName" value="#oUser.getLastName()#" /><br /> <label for="email"><b>Email Address*: </b></label> <input name="user.email" type="text" id="email" value="#oUser.getEmail()#" /><br /> <input type="submit" name="Submit" value="Submit"> </form> 

Note that my form field names now all have a "user." prefix. Now in my handler, I can do this:

<cfset var rc = event.getCollection() /> <!--- retrieve an empty user object ---> <cfset var oUser = getUserService().getUser() /> <!--- use FormUtility plugin to parse the request collection and build structures (and/or arrays) in the request collection according to form fields ---> <cfset getMyPlugin("FormUtilities").buildFormCollections(rc) /> <!--- populate my bean using only values from the user form ---> <cfset getPlugin("beanFactory").populateFromStruct(oUser,rc.User) />

Since all my user form fields had names with the prefix "user." the plugin created a "user" struct within the request collection containing only the form values. That way I can just use those values to populate my bean. This is pretty cool, but I went even further to make parsing forms even more seamless. I wrote a parseCollection method in my request context decorator which calls the plugin for me:

<cffunction name="parseCollection" access="public" output="false" returntype="struct" hint="uses FormUtilities plugin to parse request collection"> <cfset var rc = getRequestContext().getCollection() /> <cfset getController().getPlugin("FormUtilities",true).buildFormCollections(rc) /> <cfreturn rc /> </cffunction>

Now the event handler code can be shortened to:

<cfset var rc = event.parseCollection() /> <cfset var oUser = getUserService().getUser() /> <cfset getPlugin("beanFactory").populateFromStruct(oUser,rc.user) />

Keep in mind that I've just scratched the surface here on what the plugin can do. I'll refer you to Brian's post again on the ways you can use it to pass complex data structures with forms. I hope this also shows how drop-dead easy it is to integrate third party code into the ColdBox framework using its plugin architecthure.