My Secret Life as a Spaghetti Coder
home | about | contact | privacy statement
Getting Started with cfrails
There may be updated versions of this file at If you'd like more information on the public methods available throughout the project, you can find the docs about the base components at

To get started, you need to do a few of things:
  1. If you haven't already, you should download cfrails at
  2. Copy the source files to a folder you want to keep them. These are the files in the cfrails subdirectory. There is no need to include them in every application that you build.
  3. Create a mapping via cf administrator to point to cfrails source folder. The mapping should be to /cfrails. If for some reason you don't want to create a mapping, that should be ok - you should be able to put them where you want and refer to them accordingly, including having them in the same directory as your application. I haven't tested this, but if you need help, I'm willing to try! However, the tests most certainly will not (without some changes), as they rely on the mapping.
  4. Copy the app_skeleton directory to where you want your app to reside, and rename it accordingly.
  5. Create a database - no need to worry about the tables, as you can use migrations for that. However, if you'd rather create your own database tables, you certainly can.
Now we're ready to build our first app. Let's build the one I've included in the tests, which is simply a management interface to the post table in a blog application.
  1. Modify the config/database.cfm file to have the appropriate datasource, username, and passwords for database access.
  2. If you waited to create the tables, you can use the migrations to do it. Look under the /application_root/db/migrate folder. Create a file called CreatePost.cfc. In it, we just want to define some fields for our blog post. You can use this code:

    <cfcomponent extends="cfrails.Migration">
        <cffunction name="up" access="public">
             tableName = "post";
             columns = structNew();
             columns.user_id = "integer";
             columns.title = "nvarchar(100) not null";
             columns.meat = "ntext";
             columns.date_created = "datetime";
             columns.date_last_modified = "datetime";
             columns.show_this_post = "bit";
             create_table(tableName, columns, "user_id,title,meat,date_created,date_last_modified,show_this_post");
       <cffunction name="down" access="public">
          <cfset drop_table("post")>

    Now, simply navigate your browser to the application_root/db/migrate/_run_migrations.cfm and the all of the up() functions in the cfc's you have will be run. Out of the package, it will only run the up() function if the table does not exist. To change this behavior to automatically drop the table and add again, in the catch block in that file you could do something like:

    <cfset theObj.down()>
    <cfset theObj.up()>

  3. Now, we can start coding. This all assumes you've followed the defaults, so if you changed the directories you stored the cfrails source in, for example, you'll need to make the appropriate adjustments. Other than that, you'll need to create three files.
    1. Under the /application_root/models directory, create a file with the same name as the table it should access. For our example, we'll create Post.cfc. In it, simply have it extend cfrails.Model. The complete code is:

      <cfcomponent extends="cfrails.Model">


    2. Under the /application_root/controllers directory, create a file with the same name as the model it should use, with _controller appended to it. For our example, we'll create Post_controller.cfc. In it, simply have it extend cfrails.Controller. The complete code is:

      <cfcomponent extends="cfrails.Controller">


    3. Under the /application_root/views directory, create a file with the same name as the table it should access. For our example, we'll create Post.cfc. In it, simply have it extend cfrails.Model. The complete code is:

      <cfcomponent extends="cfrails.View">


  4. Navigate your browser to application_root/index.cfm/post and play around - you've just created your first application using cfrails, complete with server-side data validation.
cfrails, by default, will order the columns in the same order they are listed in your table. To change this order, use the set_priority method of your Model.
Known: As far as I can tell, everything works in this release as I intended. That being said, there are some issues you probably want to know:
  1. As I just wanted to prove this possible for working on a new project, I only supported/tested on my own development environment. So, this works fine for me using: IIS on Windows, Macromedia's (or Adobe now) Coldfusion MX 6.1/7, and Microsoft SQL Server 2000/2005. I don't think I've used anything unique to IIS or Windows (though I may have inadvertently forgot to convert some unix-style paths), or CFMX 6.1, so you may very well be able to run on Linux using CF 7. However, the database needs to be MS SQL Server. I plan to correct this in the next release.
  2. For the reason mentioned above (wanting a proof of concept), I only built support for a few of the most common SQL types. These are: bit, int, nvarchar, ntext, and datetime, plus some others. If you run into one that is not supported, please let me know and I'll upload a new file to the repository fixing the issue fairly quickly.
  3. The automated tests found under /tests won't run without CFUnit.
Upcoming in the next release:
  1. Most importantly, testing this and getting it to work with MySQL, and perhaps some other database.
  2. Better documentation, including some that will explain some of the existing features better.
  3. Anything you'd like to see? Visit to let me know about it.

Picture of me

.NET (19)
AI/Machine Learning (14)
Answers To 100 Interview Questions (10)
Bioinformatics (2)
Business (1)
C and Cplusplus (6)
cfrails (22)
ColdFusion (78)
Customer Relations (15)
Databases (3)
DRY (18)
DSLs (11)
Future Tech (5)
Games (5)
Groovy/Grails (8)
Hardware (1)
IDEs (9)
Java (38)
JavaScript (4)
Linux (2)
Lisp (1)
Mac OS (4)
Management (15)
MediaServerX (1)
Miscellany (76)
OOAD (37)
Productivity (11)
Programming (168)
Programming Quotables (9)
Rails (31)
Ruby (67)
Save Your Job (58)
scriptaGulous (4)
Software Development Process (23)
TDD (41)
TDDing xorblog (6)
Tools (5)
Web Development (8)
Windows (1)
With (1)
YAGNI (10)

Agile Manifesto & Principles
Principles Of OOD
Ruby on Rails

RSS 2.0: Full Post | Short Blurb
Subscribe by email:

Delivered by FeedBurner