Ninja Coding Monkey goes Canada

For the application I am currently developing I am trying to use OOP best practices. That means I tend to use many value objects for different things, e.g. names (first name, last name, salutation, etc), for addresses (street, city, etc) and for times (hour, minute – Ok, one could argue that a java.util.Date object should do the job, but that is far more than I need). Such objects are good for readable code but creating user interfaces gets cumbersome. The solution: custom PropertyEditors. This post shows you how to create conversion code that works transparently.

Using value objects makes developing applications easy as your objects get very structured as you do not clutter classes with non domain properties. On the other hand this imposes several problems when constructing user interfaces, especially with the scaffolding plugin due to the fact that the scaffolding plugin only handles basic values like Strings or Integers. And Date objects. That made me curious as the scaffolding plugin creates a nice date selector for you. What is even more amazing is that the date selector consists of several HTML inputs and their input is converted transparently into a Date object.

And this is the solution to the problems described above. However, documentation on this specific topic is scarce. So I digged through the Grails source code to find out how the conversion of dates and other datatypes it is done.

Setting the Scene

For this example I will use the following, really simple value object:

public class Time implements Serializable {
  Integer hour
  Integer minute
}

Understanding Binding in Grails

After digging through the source code for quite a while I finally found the package that does the magic. Grails relies on some Spring-magic here by using the ServletRequestDataBinder facility. This is basically a class that does the hard work of converting request parameters into the required format with the help of good old PropertyEditors from the Java Beans specification. With this knowledge in place, the whole thing boils down on creating an appropriate property editor and registering it with Grails.

Understanding PropertyEditor

If you are new to the concept of PropertyEditors I recommend reading the javadocs both for PropertyEditor and PropertyEditorSupport and some example code. In the Spring manual there is a section about validation that gives a good introduction.

In a nutshell a PropertyEditor is a class that is responsible for converting a string representation of some sort into a more complex structure.

Using your PropertyEditor with Grails

“Registering” the PropertyEditor is easy, name it according to the convention “classNameEditor” and drop it into the same package as the value class it is for. If the Time class is in the package app.domain.common, the editor goes to the same package. The editor must be called TimeEditor then it will be used transparently.

Using it is easy, too. Take the following example HTML code, that is backed by a bean with a property of type Time:

<input type="text" name="time" value="${bean.time}" />

Submitting this form will automatically cause the PropertyEditor to convert the value entered in the textbox to whatever value object it has been written to.

Caveat

Creating your own PropertyEditor you will get a very flexible tool for easily creating nice UIs but there are some things you should keep in mind. First of all, you have to do all input validation yourself. Depending on the input you are building this can be a complex task. You should invest some time to ensure your PropertyEditor only accepts values it should, usually a regular expression is a good way to ensure this.

Second, you should try to keep your PropertyEditor simple, do not bloat it. It should only perform operations required to convert the value and nothing more.

Conclusion

The solution presented in this post is an easy way to create custom input elements but has one major drawback: it only supports input from a single text field. Applied to our time example this means that there is only one field to enter hour and minutes which seems acceptable for this simple value object but for complex objects like an address that consists of various fields this might be insufficient. I’ll blog on this in the next couple of days if time permits.

I hope my post is of use to you and you now know how to create your own, powerful taglibs. As always, comments are welcome.

This entry was posted on Monday, August 18th, 2008 at 8:12 pm and is filed under Grails. You can follow any responses to this entry through the RSS 2.0 feed. You can leave a response, or trackback from your own site.