The heart of ICEGen is the __Customize__.xml file. This is the file that you will want to edit when you first run ICEGen. Essentially this file allows you to customize how ICEGen will generate your code. The file is located within the __ICEGEN__ directory that was created where you told ICEGen to save your generated code.
Upon opening it up will you notice that that the XML is broken down into easy to read sections like so:
Each table section or node represents a table in your DSN. Within each table node is the columns node which contains a representation of each column in that table.
In the example above I have a table named “tblContact”. To make things easier in my code I’ve decided that I wanted to rename this to “Contact” for my application. By changing the <alias> node within the table node to “Contact”, I’m telling ICEGen to now create a CFC called “Contact” that will represent the “tblContact” table. It’s important that you do not edit the <name> node as this tells ICEGen the original table name that exists inside your DSN that it will externally rename for you.
Also ICEGen allows you to do this for each column within the table also. I usually choose pretty good names for my columns, but suppose I wanted to alias the “creationdate” column by some other name, say “createddate”. All I would have to do is edit the <alias> node for the “creationdate” column and change it to “createddate”. ICEGen would then create a corresponding getter and setter for “createddate” while still internally mapping the alias to the “creationdate” column. This allows you to take badly planned or cryptic column names and turn them into names that you can understand within your model.
Besides the <alias> node, there are a couple of other nodes that you can customize with ICEGen for each column. Here’s what they do:
<required> -This allows you to take a column that normally would accept a null value within your table and make it required within your model. Say for instance that I want to make sure that each contact had a firstname. I would change the required node value to 1 and upon rerunning ICEGen, it would create the corresponding validation making this property required within my model. Valid values are 1 and 0 (default).
<default> – ICEGen tries to translate the default that you have set within your DSN for each column to ColdFusion code. As great as this may sound, there are sometimes where it just can’t do this, since each database server has it own code. This node allows you to do this yourself or change the default to something else. You’ll notice that the “creationdate” column has a default of “#now()#”, this is a default that ICEGen was able to translate from the database. But suppose I want to change this to only write the date and not the time to the column, and example would be “07/30/2007”. What I can do is edit the default for the “creationdate” column and change it to “#DateFormat(now(), ‘mm/dd/yyyy’)#”. Remember that you have to put the pound signs around any CF functions that you are going to be using.
<validateas> – Sometimes just making sure that a value is entered for a property just isn’t enough, you want to make sure that it’s a certain type. Using “validateas” can make that happen. After ICEGen checks to make sure that a value is passed in for the property it will validate as one of the following using IsValid(): creditcard, date, time, email, eurodate, ssn, social_security_number, telephone, url, uuid, usdate or zipcode. In the example abov, I’m telling ICEGen to make sure that any value entered for the email column must also be a valid email address.
<unique> – ICEGen will make sure that only unique values are entered into this column. In the example above ICEGen will make sure that no two contacts enter in the same email address. Valid values are 1 and 0 (default).
By editing the __Customize__.xml file, you can manipulate the properties for your tables and columns for your current application within having to change the database directly. It’s important that you rerun ICEGen after making any changes to the __Customize__.xml for your changes to take affect. Also ICEGen will NOT delete any of the old CFCs that it created before. This allows you to copy already existing code from an old CFC to the new one without losing anything.
During the last two installments of this (I don’t know how many) guide to ICEGen, I told you how to install and run ICEGen with your project. Now that you’ve use it to generate some code for you, I bet you’re itching to find out exactly what the hell it generated.
If you look at the directory that you told ICEGen to save it’s files to, you’ll notice two directories that were created. The first one is an “__ICEGEN__ ” directory that contains a whole bunch of xml files.The only file that you will need to worry about in this directory is the “__Customize__.xml” file. I will tell you everything you need to know how this file in the next installment of this guide. For now just put it aside in your head.
The next directory that ICEGen created was a “DAO” directory. This directory contains a whole bunch of CFCs and a directory called “generated”. You’ll notice, in the “DAO” directory, that there is a CFC for each table in your DSN, for instance if you had an “Admin” table in your DSN, you will have an “Admin.cfc” here. All the CFCs in this directory can be editted directly as they will not be overwritten the next time ICEGen runs.
If you look in the “generated” directory you will see that there are also CFCs that correspond to each table in your DSN. These CFCs are generated automatically with each time ICEGen is ran and are overwritten. The CFCs in the DAO directory above, extend these CFCs. Remeber that the CFCs in the “DAO” directory are the ones that you can edit, NOT the ones in the “generated” directory.
Take some time now and look at the files that ICEGen has genereated and check out all of the different methods available for each CFC. In the next installment we will go over the “__Customize__.xml” file and how you can use it to customize and override the output that ICEGen generates.
Now that you have ICEGen installed, it’s time to start using the thing to generate some code! Fire up your favorite browser and browse to the directory that you installed ICEGen to. If everything is kewl, your page should look like this:
ICEGen only has 5 settings that you need to give it to start generating code.
1) DSN Name – Enter in the name of the DSN that you have setup in your CF Administrator that you want to generate code for.
2) DSN Variable – Enter the DSN Variable that ICEGen should use to reference the DSN Name within the generated code. This is the value the will go into the dsn attribute of the cfquery tag. It can be anything you want and you must surround it with pound signs.
3) Database Type – Choose the database server type that the DSN resides on. For now ICEGen only supports Microsoft SQL Server. In the future I hope this list grows to include other database servers.
4) Save Project Path – This is where you tell ICEGen what directory you want to save the generated code to. The directory doesn’t have to be created already as ICEGenwill create the directory path if needed. Remember that this setting is relative to the webroot of the project. The path must begin with a “/”. So let’s say you wanted to save the generated code to http://www.mykewlproject.com/mymodel directory; enter “/model” (without the quotes) into the field.
5) Library Path – Enter the library path, relative to the weboot, for the saved generated code. Most of the time, this will be identical to the “Save Project Path” setting. So using our http://www.mykewlproject.com/mymodel directory as reference; we would enter “mymodel” (without the quotes.).
That’s pretty much it, now click “Submit” and ICEGen will start to generate the code and save it to the directory we specified. When ICEGen is finished, you will get the message below telling you that it finished and how long it took to generate the code.
In out next installment, we’ll look at the directories that ICEGen created. Later we’ll start exploring the code.
Getting ICEGen up and running with your project is very simple. There are no mappings to configure and literally you can drop it into your project and start using it.
The first thing to do is to download ICEGen from RIAForge.
After you’ve downloaded it, you will need to unzip it.
After you unzip it, copy the unzipped icegen folder into a directory on your website. It doesn’t have to be off the root if you don’t want to.
Then all you need to do is run the thing. Suppose you saved ICEGen off the root of your website. To run it, just browse to:
Icegen finally hit RC1 last night. I’ve been using Icegen exclusively on a project that I’m doing right now for a client and it really helped to debug and get the release candidate launched.
In case you don’t know, Icegen is a code generator that uses the Active Record approach. Within no time at all you’ll have all your getters and setters, CRUD and simple validation for all your tables. This can save you mountains of time when you first start out a project.
I still want to get Oracle and MySQL Support working at some point, but the people that contacted me before about testing out the code seemed to have disappeared. If anyone would like to take on the task to help me get Oracle and MySQL support working, contact me.
The thing that always bothered with IsValid() is that you can’t validate an object as a certain type. Currently all you can do is see ifa variables is an object is call the IsObject() function and it will return true if the variable is an object and false if it isn’t. But suppose that you wanted to make sure that not only is the variable an object but a certain object. Suppose that you needed to make sure that the variable is a certain bean like “model.beans.UserBean”. Currently you can’t do: IsValid(“object”, myobj, “model.beans.UserBean”). Could be a nice little addition to CF8.
I use to use dns2go for my dynamic dns needs. The problem I had once that they only allow you to have one dynamic domain. The problem I have is during development I can’t stand doing development within a subdirectory of my main site. Why? Because it’s a pain when you have to create mappings for every client because each client will not be in it’s own root directory.
Enter Dyndns. Their free service allows you to have 5, not 1, dynamic domain name. Also they allow wildcards!!! What this means is that your can register mydomain.dyndns.org and then create client.mydomain.dyndns.org. So in essence you have an unlimited amount of domains that you can create. The best part is that you can give each of your client that your developing for, their own root directory.
An even better reason to use this service, is playing around with different frameworks. Let’s say your writing a website for a client in Mach-ii 1.1.1, but want to play with Mach-ii 1.5.0. If you couldn’t have separate root directories you couldn’t have both on the same server. But with root directories you can drop 1.1.1 in one root and 1.5.0 in another and not have to create any mappings!
Go over to their site and take a look at them.
I’ve been beating my head against the wall for an hour now trying to figure out why FCKEditor wouldn’t pass the text I’m entering into it into the Mach-ii event. It finally dawned on me that I had debugging turned out, so I though let’s trying turning it off. Sure enough that solved the problem. Apparently since having debugging on would recreate the form again in the debug output, that really screwed up FCKEditor.
So if you’re using FCKEditor, do yourself the favor and turn debugging off for that view, otherwise you’ll be cursing yourself later.