Getting started with Hyrule validation framework

A couple days ago I blogged about validation in ColdFusion 9. Today I would like to walk you through a quick start of using Hyrule. The first thing you need to do is head over to RIAForge and download the project.

The Hyrule validation frameowrk can be installed a couple different ways. The easiest is to just drop the hyrule folder in to your webroot. If you do not wish to do that you can always drop it anywhere on disk or even in your project somewhere and then just create a mapping to it. With per application mappings this is very easy. component { this.name = "hellohyrule"; this.mappings["/hyrule"] = expandPath("lib/hyrule"); }

Now that we have Hyrule setup we are ready to start using it. Remember the goal of the project is to allow us to define constraints on our domain objects. In the example below we have a very basic User object. We could be using this is a persistent or non persistent object, either way it works the same. If we are not using ORM the only thing we need to make sure of is that we set accessors to true so that It will create a getter and setter for each property. Here we are using the constraint not empty to tell the framework that I just want something to be entered. The display name attribute is a way to display a friendly name to the user of what field caused the error. If you do not pass a display name it will use the property name. /** * @output false * @accessors true */ component { /** * @display First Name * @NotEmpty */ property string firstname; /** * @display Last Name * @NotEmpty */ property string lastname; }

Now that we have our domain setup we can test it out. In my test script I am going to create an instance of the user object. I am going to run the setter methods and set the properties to an empty string. If you remember we set the constraint to not null so this should thrown and error for both. <cfset user = new User()> <cfset user.setFirstName("")> <cfset user.setLastName("")> Next I am going to create an instance of the hyrule framework. In a real application I would store this instance in the application scope. Next you pass the object that you are trying to validate into the frameworks valdiate method. <!--- 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)> The validate method will not return anything. There are a couple of methods in the framework to help you out though. The has errors method will tell you if validation produced any and the get errors message will return the errors array. In this example I am dumping out the contents of the user object, looking to see if any errors occurred and then dumping them out. <cfdump var="#user#"> <!--- did this object have any errors ---> <cfdump var="#hyrule.hasErrors()#"> <!--- dump the errors array ---> <cfdump var="#hyrule.getErrors()#">

As you can see it is pretty easy to get started using Hyrule but it just the beginning. I have a ton of samples in the download showing you many ways you can take advantage of using the framework. We saw 1 constraint in this example but in fact the framework has over 30 constraints you can use. To learn more about them you can check out the Wiki. I hope you will give the project a look and let me know your thoughts. I will posting many more examples here in the near future.