Today's Best of ColdFusion 9 entry is Hyrule from Dan Vega. This entry is - to me - a slight break in the rules. It is an existing project and not something created brand new for the contest. I don't think I was specific in that regards and since the code is ColdFusion 9 specific and therefore pretty much new, I'm letting it slide here. Plus it has a Zelda-based name and therefore it must be cool.
At it's heart, Hyrule is a validation framework. Now - I don't know about you - but one thing I've yet to really nail down in my development is a good way to do validation. I have a few different ways I do it in my applications, and I don't expect to have "One Right Way", but I would like to have a method that I feel confident in and that I use most of the time. I'm just not there yet. Hyrule looks to be a solution for that problem.
In his readme, Dan says that Hyrule is based off of both the QuickSilver project and Hibernate Validation. Neither of those are projects I've been exposed to so I can't really comment on how well Hyrule implements them.
Hyrule makes use of annotations. An annotation is a non-code based comment that is treated specially by either the server compiling the code or other code processes. Certain tags in ColdFusion, since the MX time frame, have allowed you to add additional arguments. So for example, your component tag can look like this:
<cfcomponent name="Cobra Commander" snakevoice="true" egoOfARubyDev="true">
Now obviously those last two attributes aren't supported by ColdFusion, but if you run code like this you won't get an error. Instead, ColdFusion simply copies those arguments into the metadata about the component.
With the introduction of script based components in ColdFusion 9, we now have a new way of doing this. For example:
/**
* @name "Cobra Commander"
* @snakevoice true
* @egoOfARubyDev true
*/
component {
So technically none of this is very useful. Some metadata items are used in documentation, but outside of that they really don't do anything. That's where Hyrule comes in. By following some basic rules, you can quickly add validation to a component. So for example, consider this simple User component (which comes from the nicely documented samples):
/**
* @output false
* @accessors true
*/
component {
/**
* @display First Name
* @NotEmpty
*/
property string firstname;
/**
* @display Last Name
* @NotEmpty
*/
property string lastname;
}
You can see that each of the two properties have a few comments above them. Each of these annotations will be picked up by Hyrule. Here is a quick example of running the validator against the component:
<cfset user = new User()>
<cfset user.setFirstName("")>
<cfset user.setLastName("")>
<!--- create an instance of the hyrule framework --->
<cfset hyrule = new hyrule.Validator()>
<!--- validate the object by passing it to the validate method --->
<cfset hyrule.validate(user)>
Once you've validated your component, you can then get the result:
<!--- did this object have any errors --->
<cfdump var="#hyrule.hasErrors()#">
<!--- dump the errors array --->
<cfdump var="#hyrule.getErrors()#">
The result:
Pretty nifty. There is a long list of validators supported by Hyrule, including basic type checking (numeric for example), range checking, regex patterns, etc. And if you don't find a validator to your liking, you can actually create a custom one:
/**
* @custom hyrule.samples.custom.isUniqueUsername
*
*/
property username;
All in all, very slick. As a framework, it has the typical "installation" process of copying the folder. It then have one glaring fault - and this may already be fixed in the latest release. The code tries to load a resource bundle for error messages. That's nice because it means you can localize the errors. However, it uses a . Line 34 of ValidatorMessage.cfc has:
var rbPath = dir & "resources\" & getResourceBundle();
Repeat after me: Stop using . / works just fine on Windows and Unix. If this isn't fixed in the latest version, simply replace the \ with a /, and next time you see Dan, tell him Ray said he has to buy you a beer.
Ignoring that - everything works smoothly. I like the samples page - although I wish he would also show more of the code. So instead of just telling me about a feature and linking to a result, actually show the code you used to set up the validation. That would save me from having to open the CFC and look at the code directly.