|
Getting Started with cfrails
There may be updated versions of this file at
http://www.codeodor.com/cfrails_getting_started.cfm.
If you'd like more information on the public methods available throughout the project,
you can find the docs about the base components at http://www.codeodor.com/cfrails_documentation.
To get started, you need to do a few of things:
-
If you haven't already, you should download cfrails at
http://cfrails.riaforge.org/index.cfm?event=action.download
- 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.
- 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.
- Copy the app_skeleton directory to where you want your app to reside, and rename it accordingly.
- 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.
- Modify the
config/database.cfm file to have the appropriate datasource, username, and
passwords for database access.
- 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">
<cfscript>
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");
</cfscript>
</cffunction>
<cffunction name="down" access="public">
<cfset drop_table("post")>
</cffunction>
</cfcomponent>
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()>
-
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.
-
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">
</cfcomponent>
-
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">
</cfcomponent>
-
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">
</cfcomponent>
-
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.
Notes
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.
Issues
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:
- 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.
-
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.
-
The automated tests found under
/tests won't run without CFUnit.
Upcoming in the next release:
-
Most importantly, testing this and getting it to work with MySQL, and perhaps some other database.
-
Better documentation, including some that will explain some of the existing features better.
-
Anything you'd like to see? Visit http://www.codeodor.com/about.cfm to let
me know about it.
|
Me
|
