Archives for August 2009

Last time, we setup our route, and now if you go to: http://localhost/index.cfm/ads/3, you won’t get an error. But, just like on Page 63 of Head First Rails, the ads are blank and the page is kind of boring — There’s no data.

First, we need to fix our controller at /controllers/Ads.cfc. Make sure your show function looks like:

1
2
3
4
5
6
</pre>

<cffunction name="show">

<!--- Find the record --->

<cfset ad = model("Ad").findByKey(params.key)>

</cffunction>

<pre>

When Wheels created the model, it automatically adds the findByKey method. All we have to do is tell it which key we want, and params.key has the key value!

We still need to fix /views/ads/show.cfm to display the data. Change this file to:

1
2
3
4
5
6
7
8
9
10
</pre>

<cfoutput>

<p><b>Name:</b>#ad.name#</p>

<p><b>Description:</b>#ad.description#</p>

<p><b>Price:</b>#ad.price#</p>

<p><b>Seller Id:</b>#ad.seller_id#</p>

<p><b>Email:</b>#ad.email#</p>

<p><img src="#ad.img_url#"/></p>

</cfoutput>

<pre>

Pretty neat. Just put the values in the view and wrap it up in a <cfoutput> tag! Wheels handles the hard part of getting the data from the database into the model.

Go back to: http://localhost/index.cfm/ads/3, and you’ll see that the data is now being correctly displayed.

Routes offer a way to map web URLs to specific controllers in your application. It’s one place where you might use configuration in CFWheels.

There’s a good section in the CFWheels docs on Using Routes.  But, I’m going to continue following along with the examples in Head First Rails, starting on page 56.

If you try a URL like this: http://localhost/index.cfm/ads/3, Wheels will give you an error: Could not find the view page for the ‘3’ action in the ‘ads’ controller. That’s because, Wheels is looking for the Ads controller with the “3” action. Rails would complain that there is no action (Method in the Ads controller) called ‘3’. But, Wheels is smarter and just goes straight to the view. We don’t have a ‘3’ method in Ads.cfc, but Wheels still tries to load a view from /views/ads/3.cfm. The file isn’t there, so it throws an error.

Setting up a Route will let us fix this! Open up /config/routes.cfm. It defaults to something like:

1
2
3
</pre>

<cfset addRoute(name="home", pattern="", controller="wheels", action="congratulations")>

<pre>

Did you ever wonder how you got to that nice congratulations page when you just go to: http://localhost/? What happens is that our route, the “home” route, says, that if the URL pattern is “” (Blank String), Wheels should go the the wheels controller, and run the action congratulations.

Take a peek at /controllers/Wheels.cfc. Sure enough, there is a congratulations method that loads up info on the current version of Wheels. And, then of course, it looks for the view in /views/wheels/congratulations.cfm. The file is already there as part of the default Wheels installation. If you open it up, you can see the HTML code including the place where it inserts the version information Wheels got from the controller.

The default routes.cfm file is nice, but lets make some changes!

1
2
3
4
5
</pre>

<cfset addRoute(name="ads", pattern="/ads/[key]", controller="ads", action="show")>

<cfset addRoute(name="catchall", pattern="[path]", controller="redirect", action="index")>

<cfset addRoute(name="home", pattern="", controller="redirect", action="index")>

<pre>

It’s important to understand that Wheels goes through the routes in order from top to bottom. As soon as it finds a match, it goes to the appropriate controller. Here’s how you interpret this route.cfm:

• Ads. If the URL pattern looks like: http//localhost/index.cfm/ads/3, go to the show action in the ads controller. Did you notice the pattern includes [key]? This tells Wheels to set the key parameter to whatever is in the URL — 3 in this case.
• Catchall. If the URL doesn’t match the Ads pattern, Wheels will try the next pattern. This pattern matches [path]. In other words, it matches anything, and puts the value in the path parameter. Actually, it doesn’t put everything in the path paramter — Just the part before the next slash, “/”. http//localhost/index.cfm/xxx/yyy/zzz/3 will only have “xxx” in the path parameter. A route like this is a good one to add to catch any unknown URLs a user might enter — Sort of like a 404 Error page.
• Home. If the URL pattern  is blank, we’ve got one more route to cover that case. Remember, the pattern is just the stuff that comes after http//localhost/index.cfm/.

Ultimately Routes just offer a convenient way to map a URL to a controller. They are useful for having prettier URLs that make more sense to the users.  You can always use query params in your URL and completely bypass routes. This URL, http://localhost/index.cfm?controller=ads&action=show&key=3 directly specifies the controller and action, so there’s no need for Wheels to check the route!

We’re on Page 52 of Head First Rails, and we need to create a custom Controller and View.

I’m going to keep following the book, but there is a great tutorial that covers the same ideas over on the CFWheels website.

Convention Rules!  CFWheels has conventions for almost everything. As long as you follow the conventions, things just work naturally.

For example, look at a URL like this http://localhost/ads/show/5. CFWheels will automatically interpret this to run the show function in the ads controller. The number 5 is passed as a “key”.

Before I keep going, I have to touch on URL rewriting. The URL I just used as an example will only work if your server supports full URL rewriting. I’m using the ColdFusion development server, and it only offers “partial” URL rewriting. So, I have to use a URL like this: http://localhost/index.cfm/ads/show/5. Notice that index.cfm has to be inserted in the URL!

You can also specify the Controller and Action like this: http://localhost/index.cfm?controller=ads&action=show&key=5. Doing it this way will always work. It bypasses routes and any server URL rewriting problems. You might want to just use this form of URL while you are learning or if you are debugging a problem.

In any case, the idea is to run the show function in the ads controller. CFWheels will look for Ads.cfc in the controller folder, and will look for the show function inside Ads.cfc.

Then, it will run the show function and load the view. It will expect there to be a view file in /views/ads named show.cfm to match the function you called.

But, guess what? If you don’t create the Ads.cfc controller, CFWheels, will still try to run the view. Normally, you’ll want the controller to get some data for you, but if not, you could skip the controller altogether.

Here’s my controller code for /controllers/Ads.cfc:

1
2
3
4
5
6
7
8
9
10
11
12
13
</pre>

<cfcomponent extends="Controller">



<cffunction name="index">



</cffunction>



<cffunction name="show">



</cffunction>



</cfcomponent>

<pre>

Later, we’ll add some functionality to the controller, but I’m following the book. And, for now, the only two actions we need are index and show.

At this point, you could try to go to http://localhost/index.cfm?controller=ads&action=show&key=5. But, you’d get a Wheels error because there is no view file.

Here’s my view code for /views/ads/show.cfm:

1
2
3
4
5
6
7
8
</pre>

<p><b>Name:</b></p>

<p><b>Description:</b></p>

<p><b>Price:</b></p>

<p><b>Seller Id:</b></p>

<p><b>Email:</b></p>

<p><img src=""/></p>

<pre>

I know, this doesn’t do much either, but we’ll add on. Be Patient!

Now, if you go to http://localhost/index.cfm?controller=ads&action=show&key=5, you’ll see the lovely static view file you just created.

Next time, we’ll look at routes some more, and eventually, we’ll actually make this app work.

Continuing the series on using Head First Rails to learn CFWheels, lets move on to Chapter 2 — Beyond Scaffolding. We are going to create the MeBay application!

Starting on Page 45 in Head First Rails …

Whether we use scaffolding or not, we still have to create the database. In Rails, you do this with the script/generate model command and then running rake. But, in CFWheels, it’s easiest to just use SQL and create the database directly. Here is some mySQL code to create the needed ads table.

Later on, we’ll want to populate the table with some sample data, so let me go ahead and show the full SQL that creates the table and adds the test data:

It’s easy enough to manually create the Model, but for convenience, let’s use the scaffolding plugin anyway.

Click the Scaffold link at the bottom of any CFWHeels page —  In the debug section, next to Plugins. Then, on the scaffold page, enter ad as the Object name, select Model from the Type drop down, and click Generate. Remember, the table is named ads (plural with an “s”), but the the model is named ad (singular).

Now, open /models/Ad.cfc. You’ll see something that looks like:

1
2
3
4
5
6
7
8
9
</pre>

<cfcomponent extends="Model">



<!--- All initialization related tasks are done in the "init" function which is run the first time the model is requested. --->

<cffunction name="init">

</cffunction>



</cfcomponent>

<pre>

That’s all it takes to create a model! Your model must extend Model.cfc — That’s where all the CFWheels goodness happens. Other than that, all you need is an init function. Later on, you can use the init function to add extra capabilities, but for now, all that’s needed is a blank init function!

In Part 2, we looked at Editing the View in CFWheels.

We thought we were done, but now the boss wants to record events along with ticket sales. Remember we are following along in Head First Rails, and converting everything to CFWheels!

Fortunately, with scaffolding, all we need to do is create the new database table and run the scaffolding plugin.

Here’s the create table SQL query:

I got the idea from a Rails app to create a “spec” directory to hold application specification information. And, I created a database sub-directory to hold all my table creation SQL. So the query is stored in /spec/database/events.sql.

Next, click the Scaffold link. Look in the debug information at the bottom of each page, next to Plugins. Then, on the scaffold page, enter event as the Object name, and click Generate. Remember, the table is named events (plural with an “s”), but the the object is named event (singular).

All that’s left is to open /views/events/ and edit the labels in edit.cfm, index.cfm, new.cfm and show.cfm. This last step isn’t really needed to make things work, but the boss is kind of picky.

Great — We’ve finished with Chapter 1 of Head First Rails. You now know how to:

• Create a new CFWheels application
• Install the scaffolding plugin to CFWheels
• Setup a database table and  use scaffolding to automatically generate the Model, View, and Controller code.
• Edit HTML in the View
• Add fields and new tables to the database

Next time, we’ll start Chapter 2, and build an application from scratch — Without using scaffolding.

In Part 1, we looked at Scaffolding Basics in CFWheels.

Now, I’ll continue working through the exercises in Head First Rails and converting things to CFWheels.

Page 27: Edit the HTML in the View

When you use scaffolding, the labels will be the same as the field names in the database. This may be OK, but if you need to change them to make them more readable by humans, it’s easy enough to edit the HTML in the views.

• Look at the directory for webroot/views/tickets. You’ll see four files named edit.cfm, index.cfm, new.cfm, and show.cfm. These are the four files that you need to edit.
• Open up edit.cfm, and you’ll see the code like: <label>Seat_id_seq</label>. Seat_id_seq isn’t a very human-friendly label, so let’s change it to Seat #.
• Change the code to <label>Seat ##</label>. Remember this is inside a <cfoutput> block, so you have to escape the # symbol by typing it twice.
• Open index.cfm and change the appropriate line to <cfcol header=”Seat ##” text=”#seat_id_seq#” />.
• Now make similar changes to new.cfm and show.cfm.
• Save everything, then go to http://localhost/tickets/index.cfm?controller=tickets&action=index to see your beautiful new labels!

I made one other change to the code to make things work correctly! At the bottom of the show.cfm file, there’s a line that starts out with
#linkTo(text=”Return to the listing”, action=”action”)#. This may be a bug in scaffolding, or maybe I did something wrong. This line should really say:
#linkTo(text=”Return to the listing”, action=”index“)#. This way, the link will go back to the index view.

Page 31: Adding a new data field

The Boss forgot that we need a phone number field, so now we have to add it!

In Rails, you have to do > script/generate migration … and then run > rake db:migrate. In CFWheels, we’ll just run an Alter Table query on the database. Here’s the query I ran:

ALTER TABLE tickets
ADD phone varchar(255)

But, just like with Rails, changing the database isn’t enough (Page 36). We still have to update the code in the View files to handle the new field. Here’s the code I added to edit.cfm and new.cfm:

<p><label>Phone</label> <br />
#textField(objectName=’ticket’, property=’phone’)#</p>

Notice the textField() function. This is the CFWheels equivalent of <%= f.text_field :phone %>. Rails also has the f.label function. I’m not sure of the advantages of using a helper function for labels. But, this doesn’t seem to be available in CFWheels — At least not yet!

By the way, you can get details on any helper function like the textField tag at:

http://code.google.com/p/cfwheels/wiki/textFieldTag

The changes to show.cfm and index.cfm are similar. If you have any trouble, leave me a comment!

I heard a rumor that the Boss wants to add event information to our application. We’ll look at this next time!

I choose CFWheels as my first ColdFusion framework to learn. I was going to learn ColdBox, but quickly discovered that I would really have to learn Transfer or Reactor and Coldspring at the same time. These may be good tools, but I wanted to focus mostly on mastering the Model View Controller pattern.

I’ve been really pleased with CFWheels. It’s the ColdFusion answer to Ruby on Rails, and it just makes sense to me!

The documentation is good. Still, for a new learner, some things are missing. So, I thought maybe I can leverage some Rails resources. I found a great book — Head First Rails. I’m going to do some posts on translating the book to CFML and to CFWheels. I think this will help my learning and may help others.

From here, I’m assuming that you know something about web development, CFML, and already have a ColdFusion server running on your computer. If not, this information may be too advanced for you. CFWheels runs great on the development edition of ColdFusion that’s available from Adobe. Railo is also supported. You can learn more about the requirements at: http://cfwheels.org/docs/chapter/requirements.

Now on to Head First Rails, Chapter 1: Really Rapid CFWheels

Page 7: Creating a New Application

In Rails, you open a command prompt and type > rails tickets.  This sets up the folder structure for your app.

In CFWheels, you do the same thing by downloading the CFWheels files and just unzipping them to a folder named tickets in your webroot. The name of the folder is very important. CFWheels and Rails both rely on convention instead of configuration. Things have to be named consistently!

Page 14: Creating Tables (Migration)

In Rails, you create tables in the database by going to a command prompt and typing > ruby script/generate scaffold tickets … Then, you have to run a migration by typing > rake db.migrate. These two commands also write code for your application! Rails will automatically create Model, View, and Controller files for your new table.

CFWheels handles this a little differently, but you can quickly get to the same place. First, you have to install the Scaffolding plugin.

• Download the scaffolding plugin
• Save the .zip file in your wwwroot/tickets/plugins folder.
• Reload CFWheels by running this URL in your browser: http://localhost/tickets/?reload=true
• CFWheels will automatically unzip and install the file! You’ll see Scaffold listed as a plugin at the bottom of the page along with other debugging information.
• NOTE: Apparently there’s a problem with the Plugin Manager right now. I had to delete the Plugin Manager files from the plugins directory. Then, this process worked for me. I discovered the problem was with my ColdFusion server configuration. I had added a Dump() method to Component.cfc. When Wheels tried to load multiple plug-ins, it saw the duplicated method, and threw an error as a result of the naming conflict.

You’ll only need to do the steps above once. Now, lets use scaffolding to create an app in CFWheels. Instead of using the script/generate syntax, CFWheels expects you to just create your table via a SQL query or whatever database tools you like to use. Most developers know how to do this, and I like this approach better than learning a new syntax in Rails!

Here’s my Create Table SQL script. This is essentially the same command you type into Rails via script/generate.

CREATE TABLE `tickets` (
`id` int(11) NOT NULL auto_increment,
`name` varchar(255) NOT NULL,
`seat_id_seq` varchar(255) NOT NULL,
`address` text NOT NULL,
`price_paid` decimal NOT NULL,
`email_address` varchar(255) DEFAULT NULL,
PRIMARY KEY  (`id`)
)

Now, it get’s really easy. Either click the Scaffold link on the bottom of your browser screen, or point your browser to http://localhost/tickets/index.cfm?controller=wheels&action=plugins&name=scaffold. This will display the scaffolding plugin screen.

Just enter the name of the table and click Generate. That’s it! Instant Application. Go to  http://localhost/tickets/index.cfm?controller=tickets&action=index to see your new application. Rails automatically creates a route, so their URL is simpler, and you can easily do the same thing if you want. For me, when learning, I’d rather see the controller and action clearly shown in the URL. There’s always time to switch to pretty URL’s later on.

Next we’ll edit the HTML in the view. But, that’s another post. Please leave a comment if I got something wrong or you like my approach!