Thanks to a some contributions from a friend, we will call him Lance, we were able to make some important updates to the project over the last week. If you have never heard of or used Hyrule please check back soon as I am going to start a new series on using the framework. In the meantime here is a quick intro to the framework.

Hyrule is a validation framework for ColdFusion. Contrary to popular belief it's not just for ORM (Hibernate) based applications. The Hyrule framework will work with ColdFusion 9+ applications that use a model driven behavior for business objects. All this means is that use a class (component) to describe your objects such as user, person or employee.

This framework gives you multiple ways to declare your validation rules or as the framework refers to them, constraints. Once you have defined your constraints you can pass in an object to the framework and it will let you know if it passes validation. This approach gives you a simple way to perform data validation in your object oriented based applications.

This framework was created because there was a real need for it. When I started building most of my applications in a model driven form it became clear that there had to be an easier way of validating data. My inspiration was and still is the Hibernate Validator project from the Java community.

Now let's talk about the changes we made.

Documentation: The download now contains the 1st draft of our documentation. While it isn't perfect I think it's enough to get you started. If you are just getting stated and find anything in the docs confusing please let me know. If you want to view the docs online you can check them out here

Rule Parser: The core rule parsing engine was refactored. This was an important update for us to move forward. The most important change to you is that you no longer need to define a validator for annotation based rules. Annotations, property attributes and the new constraints struct all live in the metadata parser.

Display Name: There are times when humanizing the property name (what we do by default) just won't cut it. Take for instance a user component that has a variable named ssn. When we display the error to the user we want the property to display as Social Security Number. You can use the displayName attribute to override the default property display name. When the required constraint fails the message will read "The field Social Security Number must contain a value." component accessors="true" { property name="firstname" required="true"; property name="lastname" required="true"; property name="ssn" required="true" isvalid="ssn" displayname="Social Security Number"; } Constraints Struct: You can now declare constraints using a constraints struct stored in the this scope of an object. component accessors="true" { property String firstname; property String lastname; property String email; property String username; property String password; this.constraints = { firstname = {required=true,min=5}, lastname = {required=true,min=3}, email = {required=true,type="email",unique=true}, username = {required=true,size="6..15",unique=true}, password = {required=true} }; public User function init(){ return this; } } There are two cons to using this approach. First off any variables stored in the this scope are publically exposed. Second, say we have an employee object that extends our user object above. If we added another struct called constraints it would override the parent objects constraints. To avoid this collision you must define all of the constraints individually in a child object. /** * @accessors true * @extends User */ component { property Numeric salary; this.constraints.salary = {required=true}; public Employee function init(){ return this; } } IsValid Constraint: Instead of adding individual constraints for types like creditcard,email and ssn we implemented a catch all constraint. This will validate any type that the built in isValid() function supports except regex and range, which we already have constraints for. At the property level you must declare this constraint as isValid="type(ssn,email,etc)" but using the constraints struct you can use the type constraint. This is because a property already has an attribute called type to define its data type. component accessors="true" { property String fullname; property String email; property String ssn; property String phone; this.constraints = { fullname = {required=true}, email = {required=true,type="email",unique=true}, ssn = {required=true,type="ssn",unique=true}, phone = {type="telephone"} }; public User function init(){ return this; } } Tests: All of the MxUnit tests have been updated and are green across the board. If you ever have questions on how the constraints work this is a good place to look.

Bug Fixes: There were a ton of bug fixes and a few other enhancements.

I feel really good about where the project is right now. Please grab the source code using the link below and try it out. We could really use your feedback to make this framework better.

https://github.com/cfaddict/hyrule

This entry was posted on April 10, 2012 at 8:40 AM and has received 630 views. Comments 3 | Print this entry.

I updated the git repository last night with a new sample application. This example is how to use Hyrule in a ColdMVC application. If you have never had a chance to check out the ColdMVC framework by my friend Tony Nelson I suggest you give it a look. From the sample application you will see how clean and separated the code is and how Grails like it feels.

This entry was posted on October 1, 2011 at 12:35 PM and has received 1265 views. Comments 0 | Print this entry.

I just wanted to throw out a quick question to anyone still actually reading this blog ;) I am working on updating my Hyrule Validation framework and I came across an interesting scenario. I never supported rules on collections so I am struggling with what I should do here.

Say we have a product class and a product has a collection of categories. The product could have one category or it could belong to many. I have a @Min constraint which I use for things like string lengths, numbers and dates. It just seems strange to place a min constraint on a collection. For collections I have a size constraint. It will allow you to pass the size min and max in the form of n..n where n is a valid number or -1 for no max. In the example we talked about earlier I could do something like this. It just seems weird to support collections with the @Min constraint, what are your thoughts? component persistent="true" { property name="id" column="product_id" fieldtype="id" generator="native"; /** * @blank false */ property name="name"; /** * @blank false */ property name="description" ormtype="text"; /** * @size 1..-1 */ property name="categories" fieldtype="many-to-many" cfc="hyrule.samples.advancedorm.model.category.Category" linktable="product_categories" fkcolumn="product_id" inversejoincolumn="category_id" lazy="true" cascade="all" singularname="category"; public Product function init(){ setCategories([]); return this; } }

This entry was posted on September 6, 2011 at 3:58 PM and has received 1152 views. Comments 0 | Print this entry.

I am not going to go on a rant here about how ColdFusion absolutely needs static variables. Instead I would like to present a use case from a recent experience and I would like to get your thoughts on it. I was working on a personal open source project called Hyrule. This project allows you to do validation on business objects (beans/ORM Entities/etc) by describing constraints in your objects.

Currently you can describe these constraints using annotations. I found out in a recent project though that this can get very messy. Having played around with Grails before I really enjoy being able to define my constraints like this. I thought why not create a similar way to describe constraints for Hyrule, so I set out on my mission

My first attempt went pretty well. I created a new Validator to handle constraints based settings and ended up with a model that looked like this. component persistent="true" table="Users" extends="BaseEntity" { property name="id" column="user_id"; property name="firstName"; property name="lastName"; property name="email"; property name="age"; property name="username"; property name="password"; property name="passwordConfirm" persistent="false"; property name="type"; property name="roles" fieldtype="many-to-many" cfc="Role" singularname="role" fkcolumn="user_id" inversejoincolumn="role_id" linktable="users_roles"; this.constraints = [ {property="firstName",blank=false}, {property="lastName",blank=false}, {property="email",blank=false,email=true,unique=true,context="create,foo,bar"}, {property="age",blank=false,size="18..30"}, {property="passwordConfirm",blank=false,validator="passwordsMatch"}, {property="type",blank=false,inList="employee,manager"} ]; public User function init(){ return this; } } I was really happy with this and it seems like a much cleaner implementation than having a million annotations running around. Then a friend pointed out something that I totally overlooked. This method would not support inheritance. You can not access the this scope from a parent object. So if we had an employee object that defined its own constraints and extended User we would never be able to get the user constraints. This obviously brings up a huge issue and killed any dreams I had of implementing this.

So here is my use case for static variables in ColdFusion. In case your not quite sure what static variables lets review. A static variable can be accessed from a class without instantiating that class. So going back to our example say we have 2 components here, person and employee. Employee component persistent="true" { property id; property salary; static.constraints = [ {property="salary",blank=false} ]; public Employee function init(){ return this; } } Person component persistent="true" { property id; property firstname; property lastname; static.constraints = [ {property="firstName",blank=false}, {property="lastName",blank=false} ]; public Person function init(){ return this; } }

Now when if create an instance of the employee object we can use meta data to find out if the component extends any other components (inheritance) and if it does we would have the full name of the component. From there it would simply be a matter of accessing the variable constraints. I am not sure how the implementation would be that would be the basic idea behind it. So that is my case let know your thoughts on static variables/methods in general. I would also be all ears in figuring out a different solution to my little problem here.

This entry was posted on March 18, 2011 at 8:52 AM and has received 2242 views. Comments 15 | Print this entry.

Last night I released v 0.71 of Hyrule I thought I would take a couple minutes to walk through a couple of the changes that were made.

So first off we have a bug with the display property. IF you have been paying attention you should of seen a bunch of examples that look kind of like this. component accessors="true" { /** * @display First Name * @NotEmpty */ property firstname; /** * @display Last Name * @NotEmpty */ property lastname; } When we get an error it will display an error message based on the default message template which looks like "notempty=The field {display} must contain a value.". In the case above it will replace {display} with the @display property. This is all great but what if you don't have a display property. Well what it should do is use the property name. It was not doing this so I fixed that part. Then my friend Tony said why not just humanize the property name. Great idea so thats what we are going to do now. The following will do the same as the example above. component accessors="true" { /** * @NotEmpty */ property firstName; /** * @NotEmpty */ property lastName; }

The next problem I came across on my own. Take the following example. Now if you fill nothing in for all 3 properties your going to get back 3 errors. The first 2 because they are still empty and the 3rd because your empty string does not follow the rules of a phone number component accessors="true" { /** * @NotEmpty */ property firstname; /** * @NotEmpty */ property lastname; /** * @Phone */ property phoneNumber; }

This was obviously a problem. What if you just wanted to validate that if the user did enter a phone number that it was valid. It was because of this for validators like phone,ssn,credit card,etc... that we now check to make sure the property is not empty before we validate it. If you want to make sure the phone number has something in it and that its a phone number then you can do the following. component accessors="true" { /** * @NotEmpty */ property firstname; /** * @NotEmpty */ property lastname; /** * @NotEmpty * @Phone */ property phoneNumber; }

There were some other minor changes but that was the bulk of it. All of the unit tests were also updated to contain a testIsBlankReturnsTrue method. Let me know your thoughts on all of this and feel free to join the Google Group.

This entry was posted on May 4, 2010 at 9:04 AM and has received 2369 views. Comments 4 | Print this entry.