Objective Bias

Last week at the Boston CFUG meeting, we had an "open mic" night where CFUG members went up and gave short presentations in front of the group. I decided to follow up the talk that Luis Majano gave on the ColdBox framework back in July and give an intro on ColdBox plugins. I had some technical problems with my Winblows laptop early on, but Brian Rinaldi graciously let me borrow his laptop for my presentation. It was fun to present and it went well overall. But due to time constraints, I didn't get a chance to go over the code of the custom plugin that I demoed, so I decided to do it here on my blog. (Besides, it's been getting stale around here).

I built a plugin to display CAPTCHA images and validate form input against them using CF8's cfimage tag. It was pretty simple to do. To prepare, I looked at the code for another visual ColdBox plugin, the Messagebox plugin, the ColdBox docs, and this blog post by Ray Camden on CAPTCHA with cfimage. The plugin can be downloaded by clicking the link at the bottom of this post. Let's take a look at the code to see how it works.

<cfcomponent name="captcha" hint="plugin for CF8 built in captcha functionality" extends="coldbox.system.plugin" output="false" cache="true"> <cffunction name="init" access="public" returntype="any" output="false"> <cfargument name="controller" type="any" required="true" /> <cfscript> super.Init(arguments.controller); setpluginName("captcha"); setpluginVersion("0.25"); setpluginDescription("CAPTCHA plugin for CF8 cfimage captcha functionality"); //Return instance return this; </cfscript> </cffunction>

This is the general format for the cfcomponent tag and the init() method of ColdBox plugins. The only think noteworthy about the cfcomponent tag is that I'm telling the framework to cache this plugin by adding the metadata attribute cache="true". By default, ColdBox plugins are not cached. But since this plugin us generally used over multiple requests (for displaying and then validating the CAPTCHA), I decided to have it cached. By default it uses the caching parameters in the framework's config files, but these can be overriden if desired by using the cachetimeout and cacheLastAccessTimeout attributes (see the docs for more info). Also, all plugins must extend the base plugin class (coldbox.system.plugin).

The init() function just takes the coldbox controller as an argument and sets some basic info about the plugin (name, version, description). The beauty of plugins, though, is that you don't need to worry about the init() method when you call them because the framework runs the initualization for you.

Let's take a look at the rest of the code.

<cffunction name="display" access="public" returntype="any" output="false" hint="I display the captcha and an error message, if appropriate"> <cfargument name="length" type="numeric" default="4" /> <cfargument name="text" type="string" default="#makeRandomString(arguments.length)#" /> <cfargument name="width" type="string" default="200" hint="width of captcha image in pixels" /> <cfargument name="height" type="string" default="50" hint="height of captcha image in pixels" /> <cfargument name="fonts" type="string" default="verdana,arial,helvetica" hint="fonts to use for characters in captcha image" /> <cfargument name="message" type="string" default="Please enter the correct code shown in the graphic." hint="Message to display below captcha if validate method failed."> <cfset var ret = "" /> <cfset setCaptchaCode(arguments.text) /> <cfsavecontent variable="ret"> <cfimage action="captcha" text="#arguments.text#" width="#arguments.width#" height="#arguments.height#" fonts="#arguments.fonts#" /> <cfif not isValidated()> <br /> <span class="cb_captchamessage"><cfoutput>#arguments.message#</cfoutput></span> </cfif> </cfsavecontent> <!--- clear this in case user just navigates to another page and comes back ---> <cfset setValidated(true) /> <cfreturn ret /> </cffunction> <cffunction name="validate" access="public" returntype="boolean" output="false" hint="I validate the passed in string against the captcha code"> <cfargument name="code" type="string" required="true" /> <cfif hash(lcase(arguments.code),'SHA') eq getCaptchaCode()> <cfset clearCaptcha() /><!--- delete the captcha struct ---> <cfreturn true /> <cfelse> <cfset setValidated(false) /> <cfreturn isValidated() /> </cfif> </cffunction> <!------------------- PRIVATE ------------------------> <cffunction name="getCaptchaStorage" access="private" returntype="any" output="false"> <cfif not structKeyExists(session,"cb_captcha")> <cfset session.cb_captcha = {captchaCode = "", validated = true} /> </cfif> <cfreturn session.cb_captcha /> </cffunction> <cffunction name="setCaptchaCode" access="public" returntype="void" output="false"> <cfargument name="captchastring" type="string" required="true" /> <cfset getCaptchaStorage().captchaCode = hash(lcase(arguments.captchastring),'SHA') /> </cffunction> <cffunction name="getCaptchaCode" access="public" returntype="string" output="false"> <cfreturn getCaptchaStorage().captchaCode /> </cffunction> <cffunction name="setValidated" access="private" returntype="void" output="false"> <cfargument name="validated" type="boolean" required="true" /> <cfset getCaptchaStorage().validated = arguments.validated /> </cffunction> <cffunction name="isValidated" access="private" returntype="boolean" output="false"> <cfreturn getCaptchaStorage().validated /> </cffunction> <cffunction name="clearCaptcha" access="private" returntype="void" output="false"> <cfset structDelete(session,"cb_captcha") /> </cffunction> <cffunction name="makeRandomString" access="private" returnType="string" output="false"> <cfargument name="length" type="numeric" default="4" /> <cfset var min = arguments.length - 1 /> <cfset var max = arguments.length + 1 /> <!--- Function ripped of from Raymond Camden (http://www.coldfusionjedi.com/index.cfm/2008/3/29/Quick-and-Dirty-ColdFusion-8-CAPTCHA-Guide) ---> <cfset var chars = "23456789ABCDEFGHJKMNPQRSabcdefghjkmnpqrs"> <cfset var captchalength = randRange(min,max)> <cfset var result = ""> <cfset var i = ""> <cfset var char = ""> <cfscript> for(i=1; i <= captchalength; i++) { char = mid(chars, randRange(1, len(chars)),1); result&=char; } </cfscript> <cfreturn result> </cffunction> </cfcomponent>

The ony public methods of this plugin are display() and validate(). The display() method is essentially a wrapper for the cfimage action="captcha" tag. It's set up with default arguments so that calling "display()" will give you a 50 X 200 pixel captcha image of 3 to 5 random characters (the length will range between +/- 1 of the value in the "length" argument). Of course, you can customize the image by passing in arguments. The default random characters are built using the makeRandomString() function which was taken from Ray's blog post. But if you have your own way of generating the captcha text, you can pass that text in as an argument (in which case the "length" argument will be ignored). The "message" argument sets an error message which will appear if under the CAPTCHA image if the user is redirected back to the form after a failed CAPTCHA validation. This message can be be styled using the "cb_captchamessage" css class to make it stand out

Before the display() method sets up the image, it calls the setCaptchaCode() function. What this does is set the CAPTCHA text and a "validated" flag in a structure inside the session scope. That structure (cb_captcha) is accessed through the getCaptchaStorage() function. OOP purists out there will point out that it's not good practice to directly reference the session scope in your CFCs because it breaks encapsulation. Yes, technically, one should use a session facade, but I decided to side on pragmatism here and keep things simple. However, since I did isolate access to the session scope to the getCaptchaStorage() method, I made it very easy for anyone to modify the code to use a facade. In fact, the ColdBox "SessionStorage" plugin can be used for that purpose (since it's possible for plugins to call other plugins). Also note that the CAPTCHA text is converted to lower case before it is hashed and stored. I did this to make the validation case-insensitive. You can simply take the lcase() out to make it case-sensitive or even set up another argument to control case sensitivity.

The validate() method simply takes in a string and validates it against the CAPTCHA code that was set up to display. It then sets the "validated" flag to true or false based on if the values were equal. This can be used to redirect users back to the form or go ahead and process the form.

Usage

So here is an example of how you would use this plugin. First, you would use the display() method in your form view along with an input field for people to enter the code: <form name="myform" method="post" action="index.cfm?event=general.handleForm"> <!--- Your form fields here ---> <!--- Display CAPTCHA image ---> <cfoutput>#getMyPlugin('captcha').display()#</cfoutput><br /> <!--- Ask for code ---> <label for="captchacode">Enter the security code: </label> <input type="text" name="captchacode" /><br /> <input type="submit" value="Submit" /> </form>

Now, in your event handler that would handle this form input, you would do something like this:

<cffunction name="handleForm" access="public" returntype="void" output="false" hint=""> <cfargument name="Event" type="any" required="yes"> <!---get a reference to the request collection, which contains the submitted form values ---> <cfset var rc = event.getCollection() /> <!--- do any non-CAPTCHA form validation here ---> <!--- validate CAPTCHA form input ---> <cfif getMyPlugin('captcha').validate(rc.captchacode)> <cfset setNextEvent("general.successFormSubmit") /> <cfelse> <!--- redirect user back to the form, where the captcha display() method will now include an error message ---> <cfset runEvent("general.dspForm") /> </cfif> </cffunction>

That's it! With cfimage CAPTCHA functionality in this tidy little package, you can use CAPTCHA images throughout all of your ColdBox applications. Feel free to download the plugin using the link below, use it, take it apart, and/or modify it to your heart's content.

Also, be sure to check out the two projects that were also presented at our open mic, night: Tom Mollerus's Clickheat for ColdFusion and Charles Kaufmann's Coreforms custom tag library.

Download Coldbox CAPTCHA plugin.