Scaffolding a Generic Admin - Part 6 - Bean, Form and List Views - The Finale

In this post I'll provide a deeper insight into how Dispatcher works and introduce the three generic views that make up the "generic admin". After generating some code with Illudium, we'll have all the pieces to perform CRUD operations...

The central concept behind the generic admin is to render add/edit form and list pages directly from a TransferObject using transfer metadata. So, instead of generating many scaffold views, we have only 3 "smart" views, TransObject(s) and transfer to do the job.

I was originally going to introduce a bunch of workarounds to make this all happen, but thanks to some great suggestions from Mark Mandel, I've decided to limited the amount of decorated methods within a TransferObject, remove my superfluous "TransferConfig" component, and use transfer within my views to do the heavy lifting. The result is a much cleaner and more cohesive. The downside is that I had to revise my Illudium template (again). The upside is I have less conventions! :)

The steps I use to generate code and setup my application are as follows:

1. Within the Illudium code generator, first select a datasource and table, then type a "package" path such as "model.user.User" (for the user table) in the CFC Path field. This will generate the Service and Decorator with paths "model.user.UserService" and "model.user.User" respectively. Note that at this time I choose to place all my controllers in a "listeners" folder, so the path is currently hard coded to generate a controller as "listener.UserController".

2. Use the browse feature to navigate to the project folder where I would like to save the files, then generate the Service, Controller and Decorator for each table.

3. For Transfer and Coldspring XML, I simply copy and paste the portions of the file I want into the transfer.xml and beans.xml files respectively.

4. When all components are generated, I update the main() method of Application.cfc to add listeners (the generated controllers) to Dispatcher.

Here's what the final version of the main() method looks like.

If you are following along and want to generate the code, you can grab the latest version of the Illudium template from the Google Groups site.

One thing that I have to say about using Illudium and I know that Brian has stressed this as well, is that it is designed to alleviate the tedium of writing repetitive code. It is not designed to be an end to end solution. So we will have to dig in to add transfer relationships and add some code to parent controllers so that they generate lists when a child object is created or edited.

First, I'll add bit of code to the ViewManager to prepare the correct view based on a url "cmd". The onRequest() method for ViewManager has a three level switch/case block. The first level checks the page that is being called, the second checks the first part of the url cmd (typically an object name) and the third checks the action to be performed. We'll add a defaultcase to the onRequest() method so that it now looks like this.

At the top of the method, I've added a test for errors that the request may have and add an "ErrorView" should that be the case. A common design choice is to have a business object "validate" itself prior to saving. Since transfer objects do not have this facility built-in, I have followed Brian Rinaldi's idea to add validation to the TransferObject decorator. My implementation is different as I would prefer to have a method like isValidForSave() return a boolean, rather than a validate() method return an array of errors. So in my decorator I have addError(), getErrors() and isValidForSave() that process object validation.

I've gone ahead and bundled all the pieces together as the enclosure for download to expedite things. Also, Some styles to sample.css to make it a little more friendly to the eyes. To make it a working code base, I have also updated the onRequest() methods for each (parent) controller. For any object that has a parent I have to add a switch/case block to listen for edit and new actions and add a list query to the RequestEvent object. I'm no software guru, but I have included minimal error handling within RequestEvent to throw an error when a requested collection or property of a collection is undefined. For example, without updating the UserController to add a list of users to the RequestEvent when a new Game form is generated, RequestEvent will throw " Property UserList of collection query undefined!" To update the UserController, I added the following to the onRequest() method.

A critical piece in making it all work is having the correct relationships defined in transfer.xml. The transfer.xml in the enclosed zip file has the complete relationships defined. Below is the objectDefinition for the User object.

In this definition, I have a couple of conventions. First is the "className" which is comprised of the name attributes of the <package/> and <object/> elements which are both "User". The Illudium template will generate the values of the name attributes and the decorator path as well. Currently, the generic ListView expects a className where the package name and object name are the same. Second, the <onetomay/> name is in the format {parent}_{child}, which is similiar to what you might name a foreign key in a database. The generic FormView relies on this naming convention to generate select lists for editing a child object.

Here are code blocks for the List, Form and Bean views. A cautionary note that I haven't fully commented the code. Also, in order to pull it off, I make use of ColdFusion's Evaluate() function.

Briefly, each of these views accesses either an object or query based on the url cmd and uses transfer to access the object metadata. The views are then generated from the object, or query and the metadata.

FormView.cfm

ListView.cfm

BeanView.cfm

Many to many relationships are not covered yet, so for now it is a solution for simple a one-to-many relationship model.

I'm going to continue revising this code and will eventually add a nice gloss with Ext JS.

Questions and comments welcome. I realize this represents more hands on approach than other frameworks, but if you work with transfer and Illudium, it's relatively easy process to build a Dispatcher application and generate the code to implement a "generic admin".

Finally, I'd like to thank both Brian Rinaldi and Mark Mandel for their mentorship and encouragement to throw this project together. :)