1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
<cfcontent type="text/xml" reset="Yes"><?xml version="1.0" encoding="UTF-8"?>

<rss version="2.0" xmlns:dc="http://purl.org/dc/elements/1.1/"

    xmlns:atom="http://www.w3.org/2005/Atom">

<channel>

  <atom:link href="http://www.YourSite.com/index.cfm/feed"

    rel="self" type="application/rss+xml" />

  <title>YourSite.com</title>

  <link>http://www.YourSite.com</link>

  <description>Your Description Goes Here</description>

  <cfoutput>

    <pubDate>#HTMLEditFormat(DateFormat(now(), 'ddd, dd mmm yyyy'))#

      #HTMLEditFormat(TimeFormat(now(), 'HH:mm:ss'))# EST</pubDate>

  <language>en-us</language>

  <ttl>40</ttl>

  <s:find slug="blog">

  <s:children-each order="publishedAt desc" where="status='published'">

    <item>

      <cfset thisChild = request.tags.currentChild>

      <title>#HTMLEditFormat(thisChild.title)#</title>

      <description><![CDATA[<s:content part="body" page="#thisChild#"/>]]></description>

      <pubDate>#HTMLEditFormat(DateFormat(thisChild.publishedAt, 'ddd, dd mmm yyyy'))#

         #HTMLEditFormat(TimeFormat(thisChild.publishedAt, 'HH:mm:ss'))# EST</pubDate>

      <guid isPermaLink="true">http://www.yoursite.com/index.cfm/#thisChild.slug#</guid>

      <link>http://www.yoursite.com/index.cfm/#thisChild.slug#</link>

    </item>

  </s:children-each>

  </s:find>

</channel></cfoutput>

</rss></cfcontent><cfabort>

Most of this code is the required RSS XML. Just drop in your site-specific domain name, description, etc.

The <s:find slug=”blog> tag finds the blog, and then <s:children-each> loops over all the children that are under the blog page. I used thisChild as a convenience variable instead of having to type request.tags.currentChild every time. The <cfabort> at the end keeps Splash from adding extra HTML tags at the end of the file.

You could also create an easy XML site map using a similar approach. Just change out the XML wrapper.

• <s: find>
• <s: children-each>
• <s: children-first >
• <s: children-last >
• <s: ifFirst >
• <s: unlessFirst >
• <s: ifLast >
• <s: unlessLast >

There’s a complete list of tags and documentation over on the GitHub Wiki. But, I’ll give you an overview and show you how to use these tags for a blog.

<s:find> This tag looks up a page and stores the page object so that subsequent tags can use that page object.

<s: children-each> The tag finds all the children of a page and loops over them.

<s: children-first > and <s: children-last > finds the first or last child page.

The rest of the tags are all used inside of a <s: children-each> tag. They check to see if the current child page is the first one, last one, or whatever.

Making a Blog page with Splash Tags

Let’s say you have a page named Blog, that has several posts that are child pages of Blog. Then, in the body for the blog page, put something like this:

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

<s:find slug="blog">

  <s:children-each

   order="publishedAt desc"

   where="status='published'">

    <cfset thisChild = request.tags.currentChild>

    <cfoutput>

      <dt class="blogList">

         <a href="#thisChild.slug#">#thisChild.title#</a>

            | #DateFormat(thisChild.publishedAt, 'long')#</dt>

      <dd class="blogDesc">#thisChild.description#</dd>

    </cfoutput>

  </s:children-each>

</s:find>

<s:find slug=”blog”> finds the blog page, and then <s:children-each> loops over all the pages. By the way, <s:children-each> uses the CFWheels findAll model method, so all of the cool CFWheels parameters are available in <s:children-each>!

If you want to see an example of what this looks like, visit the DonorUp blog page.

All in all, that’s a lot of output for very little programming effort. That’s what I call the secret to programmer happiness!

CFWheels is an open source ColdFusion framework that is inspired by Ruby on Rails. Besides being easy to use and learn, using CFWheels lets you adapt great ideas from Ruby on Rails (RoR) applications. RoR has the Radiant CMS, and Splash is the ColdFusion/CFWheels adaptation!

You can easily download Splash from http://wiki.github.com/russjohnson/SplashCMS/. The documentation for Splash is still kind of sparse, but the Radiant documentation is mostly applicable, and you can easily see how most things are supposed to work. Then, if you get stuck, email the Google Group.

Splash Layouts, Snippets, and Pages

Splash uses Layouts, Snippets, and Pages to build a website.

A layout, as you might imagine, is like a skin for an entire website. You can have multiple layouts and use different layouts for different pages.

Pages are specific URLs on a Splash site, and each page has a specific layout specified. A page can have multiple “page parts.” Most pages will have a “Body” part, but some might also have a “Sidebar” or other parts.

Snippets are reusable content chunks. You might have a navigation snippet that displays the main navigation for your site. Headers and Footers are other common snippets.

Splash Tags

There is one other very powerful component to Splash — Splash Tags. These are ColdFusion custom tags that extend ColdFusion and HTML to work with Splash. Here’s a simple example: the <s:title /> tag. This tag just retrieves the page’s title from the page object and inserts it in place of the tag. So, in your layout, you would typically have something like:

<title><s:title /></title>

The pages title information from the database is then easily inserted into the HTML title tag!

There are a lot more tags, so see the Wiki.

Splash in Action

I recently completed the DonorUp.com website using Splash. I was really pleased with how easily I was able to get many thing to come together. So, try Splash and leave a comment to let me know how you like it!

On the CFWheels Google Group, Cathy recently asked about the sendEmail() function. This is a pretty good example to show you some debugging tips.

sendEmail() wraps the cfmail tag. Here’s some more information:

CFWheels on sending email.

This all looks pretty straightforward, but what do you do if it’s not working?

First, setup a test view page. Go to the Wheels views folder and add a new folder called test. Then create a new file called index.cfm in the test folder. The path should be /views/test/index.cfm.

In the index.cfm file you just create, put the following:

1
2
3
4
5
6
<cfset

  set(functionName="sendEmail",

  server="yourServer",

  username="yourUsername",

  password="yourPassword")

>

This will trigger the sendEmail() function. You can access the test page at http://localhost/index.cfm/test. But, if you go to this page, you’ll get an error because we didn’t create myemailtemplate, yet. So, make another CFM page in /views/test/ called myemailtemplate.cfm. The content can be anything you want. Something like “Test email” is fine.

Wheels knows you are in the Test controller, so it looks for templates in the /views/test folder. Wait a minute! You never said anything about creating a controller. That’s one of the cool things about Wheels. Even without a controller, it will still show you the view page, and things still work!

Now, go back to the test page at http://localhost/index.cfm/test. If everything is working, you should get an email message. If it’s not working, you can put other stuff in your test page. Try these out:

• <cfdump var=”#params#”> will show you the params structure with your actions, controller, data you’re passing, etc.
• <cfdump var=”#wheels#”> will show information on your filters.
• <cfdump var=”#application.wheels#”> will show all the wheels settings, functions, routes — All kinds of cool things.

Now sendEmail() is a little trickier. It uses ColdFusion’s <cfmail> tag. Put this in your /views/test/index.cfm file:

1
2
3
4
5
<cfmail from="me@mydomain.com"

    to="me@mydomain.com"

    subject="Test Message">

  This is a test

</cfmail>

If this won’t work, then it’s your server configuration, not Wheels. You may have to specify your server name or login information. That’s pretty easy, too. Just put the following in your config/settings:

1
2
3
4
5
6
<cfset

  set(functionName="sendEmail",

  server="yourServer",

  username="yourUsername",

  password="yourPassword")

>

I hope this helps!

“Does exactly what it says on the tin.”

I love it. All of our method and function names should do exactly the same.

During a discussion with the ColdFusion on Wheels core team about the valid() and beforeValidation() methods, Andy Bellenie made this remark:

My point is that a callback called beforeValidation should run, well, before validation – not during it. This seems self-evident to me and I’d have a hard time explaining to anyone why it should work differently.

Then he pointed to “the Ronseal test, the holy grail of method naming.”

Thanks Andy for the inspiration.

Technorati Tags: best practices, cfwheels, chris peters, clear crystal media, ColdFusion, coldfusion on wheels, development, polymorphism, Programming, web development

For the DonorUp website, I used CFWheels and the Splash CMS. Once I knew the tricks, it turned out to be really easy to make this work. So, I decided to write a post to explain what you need to know.

Typically, in ColdFusion, you add an onError() method to your Application.cfc file. Wheels gives you various hooks into Application.cfc, but Wheels already has an onError() method. So, you can’t add another one! Fortunately, Wheels has an easy way to handle most errors.

How to send error messages from CFWheels

All you have to do to get Wheels to send error message emails is add the following into your /config/settings.cfm file:

<cfset set(sendEmailOnError = true)>
<cfset set(errorEmailAddress = “you@yourServer.com”)>

Now, whenever there’s an error, you’ll get a really nice email with all the troubleshooting info you’ll need. Easy!

How to setup a custom error page in CFWheels or Splash

As part of its built-in error handling, Wheels runs the file at /events/onerror.cfm. Just put a redirect to your error page at the top of onerror.cfm and you’re done:

<cfset redirectTo(route=”viewer”, slug=”error-page”)>

In my case, I went into the Splash CMS admin and added a page called Error Page. This way, the page is automatically styled to match the rest of the site. The error page apologizes to the user for the error, and let’s them know I am going to fix it!

When Wheels does its error handling, it will run /events/onerror.cfm, and the redirectTo() will send them to my error page! If you aren’t running Splash, you could just use the other arguments of redirectTo() to send them to any controller and action.

You can also put your own HTML or CFML code in onerror.cfm, but I like doing it this way better as it uses all the layouts and styling of my site!

Please leave me a comment if you like this approach or have other ideas!

Thanks Chris!

http://gaclabs.com/projects/wheels-plugins/ym_gravatar

* <http://cfwheels.org/plugins/listing/23>
* <http://github.com/illuminerdi/DefaultScope>

The DefaultScope plugin adds the ability to set defaults for the findAll() method on a per-Model basis.

Changes:

### 0.6.2 / 2009.12.19

* 1 minor enhancement:

* fix for DefaultScope causing issues with the calculations methods (andybellenie)

Big thanks to Andy for identifying this issue and supplying patches for it.

http://cfwheels.org/plugins/listing/23
http://github.com/illuminerdi/DefaultScope

The DefaultScope plugin adds the same functionality to Wheels found in Rails’ ActiveRecord::Base#default_scope. Go ahead and check the documentation on either the Github or CFWheels plugin pages.

CfWheels is a full-stack framework with some quite strong opinions on code organisation and layout. This is not a bad thing at all, if you do things the wheels way, it makes your life easier.

Built into the concept of the framework are 3 core pieces of ideology that will make your life easier. When i say built in, i really mean baked in as the level of thought these interactions have had is quite surprising. These features are:

ORM – Object Relational Management

URL Rewriting

MVC – the Model View Controller ideology for code separation

Wheels is based on the Ruby on Rails framework, which is widely considered to be a great tool for RAD. Most people who seem to love ruby on rails do so for its speed and ease of use, and there are countless books on this subject. Coldfusion is already a fantastic RAD language, and CfWheels when combined with tools such as Scaffolding can give you a very swift boost into a project.

Scaffolding allows you to generate controller and views for a table that contain all of the basic functionality you will generally require.

A quick and dirty example:

Step 1. Install CfWheels on either Adobe’s own CF8/9, Railo or BlueDragon.

Step 2. install the scaffolding plugin by dropping the zip file into the cfwheels plugin folder

Step 3. Write a simple database table containing the data set you wish to use

Step 4. Click the scaffolding link at the top of the cfwheels debug information panel

Step 5. Enter the name of the table

Step 6. Navigate to the controller (/tablename) and you will see that all the fields are now generated into an input for you, and also basic add/edit/remove functionality exists.

wow, you just built a fully functional application! While clearly this might not suit every project, it can certainly be a good place to start, and a great introduction into cfwheels.

Then came the process of installing Git on Snow Leopard so that my computer can talk to the repository. In my opinion, the Git website could do a better job with their Mac OS X installer (or at least the instructions).

Fortunately, Hivelogic has a great step-by-step on installing Git on Snow Leopard. If you’re running Snow Leopard, I highly recommend doing everything that they say in the post. If they ask you to touch your nose while spinning in circles, do it.

Now on to figuring out how to get my reCAPTCHA on Wheels plugin into my new repo.

Technorati Tags: ccm, cfwheels, chris peters, clear crystal media, coldfusion on wheels, Git, github, install, installation, polymorphism, scm, version control, web development

Look at this example for the autoLink() view helper:

<cffunction name="autoLink" returntype="string" access="public" output="false" hint="Turns all URLs and e-mail addresses into clickable links."
 examples=
 '
 ##autoLink("Download Wheels from http://cfwheels.org/download")##
 -> Download Wheels from <a href="http://cfwheels.org/download">http://cfwheels.org/download</a>
 
 ##autoLink("Email us at info@cfwheels.org")##
 -> Email us at <a href="mailto:info@cfwheels.org">info@cfwheels.org</a>
 '
 categories="view-helper,text" functions="excerpt,highlight,simpleFormat,titleize,truncate"
> <cfargument name="text" type="string" required="true" hint="The text to create links in."> <cfargument name="link" type="string" required="false" default="all" hint="Whether to link URLs, email addresses or both. Possible values are: `all` (default), `URLs` and `emailAddresses`.">
  <cfscript> var loc = {}; loc.urlRegex = "(?ix)([^(url=)|(href=)'""])(((https?)://([^:]+\:[^@]*@)?)([\d\w\-]+\.)?[\w\d\-\.]+\.(com|net|org|info|biz|tv|co\.uk|de|ro|it)(( / [\w\d\.\-@%\\\/:]* )+)?(\?[\w\d\?%,\.\/\##!@:=\+~_\-&amp;]*(?<![\.]))?)";
 loc.mailRegex = "(([^@\s]+)@((?:[-a-z0-9]+\.)+[a-z]{2,}))";
 loc.returnValue = arguments.text;
 if (arguments.link != "emailAddresses")
 loc.returnValue = loc.returnValue.ReplaceAll(loc.urlRegex, "$1<a href=""$2"">$2</a>"); if (arguments.link != "URLs") loc.returnValue = REReplaceNoCase(loc.returnValue, loc.mailRegex, "<a href=""mailto:\1"">\1</a>", "all"); </cfscript> <cfreturn loc.returnValue>
 
</cffunction>

It makes the function declarations a little beefier, but the documentation is right there with the code. As you can see, we added examples, categories, and functions attributes to the <cffunction> declaration.

Writing a parser took a little over a week, but it was fairly simple with CFML ’s GetMetaData() function and some extra business rules.

Here’s a link to the autoLink() documentation on CFWheels.org so you can see what the output looks like. Everything on that page is generated based on the code above.

Technorati Tags: adobe, ccm, cfml, cfwheels, chris peters, clear crystal media, ColdFusion, coldfusion on wheels, polymorphism, railo, web development

plugins/**/*

What that does is essentially tells git to ignore any subdirectories off the main plugin directory.

If there was one thing that always bugged me about github is the lack of support of CFML syntax highlighting. It seems that CFML never gets any love, but that is about to change! The Pygments project is an open source generic syntax highlighter written in python that has support for a ton of different languages. Now it seems the Pygments is working on CFML syntax highlighting for their next release!

What does this all have to do with Wheels you might ask? Well it seems that the CFML code they are using as a test bed for the highlighting is none other then the Wheels repo!

Think about this scenario in ColdFusion on Wheels:

• Controllers in script syntax
• Models in script syntax
• Views in tag syntax

I like the idea of this, though I’ll admit that I haven’t tried it yet. The more data- and logic-heavy parts of the app can be script-driven, while the tag-based syntax can be used with HTML .

Imagine this scenario for a Wheels model class:

component extends="Model" {
  /** @hint Initializes associations and validations */ public function init() { // Associations hasMany("chirps"); // Validations validatesPresenceOf("firstName,lastName,email,gender,urlId"); validatesUniquenessOf("email,urlId"); validatesLengthOf(properties="firstName,lastName", maximum=50); }
 
}

And this for a Wheels controller:

component extends="Controller" {
  /** @hint Shows form for registering for social network. */ public function register() { user = model("user").new(); }
  /** @hint Saves registration submission. */ public function create() { user = model("user").new(params.user); user.save();
  if(user.hasErrors()) { renderPage(action="register"); } else { flashInsert(success="Thank you for registering for Social Network."); redirectTo(controller="home"); } }
 
}

And then any view logic can be mixed in via tags with all the other HTML tags (right where it belongs).

<cfsetting enablecfoutputonly="true">
 
<cfparam name="user">
 
<cfoutput>
 
<h1>Register for Social Network</h1>
 
#startFormTag(action="create")#
 
#textField(label="First Name", objectName="user", property="firstName")#
#textField(label="Last Name", objectName="user", property="lastName")#
#textField(label="Email", objectName="user", property="email")#
 
<fieldset> <legend>Gender</legend> #radioButton(label="Male", objectName="user", property="gender", tagValue="M")# #radioButton(label="Female", objectName="user", property="gender", tagValue="F")#
</fieldset>
 
<fieldset> <legend>Profile Address</legend> #textField(label="http://#cgi.script_name#/profile/", objectName="user", property="urlId")#
</fieldset>
 
<div> #submitTag(value="Register Now")#
</div>
 
#endFormTag()#
 
</cfoutput>
 
<cfsetting enablecfoutputonly="false">

This makes me excited for Railo adoption of script-based CFC s and for time to warp 5 years into the future when script-based CFC s are more widely used in general.

Technorati Tags: ccm, cf, cf9, cfc, cfml, cfscript, cfwheels, chris peters, clear crystal media, ColdFusion, coldfusion 9, coldfusion on wheels, mvc, polymorphism, railo

Stephen came up with a much nicer jQuery-only solution for setting form focus:

$(document).ready(function(){ $(”.focus”).focus();
});

So now you can set form focus on load by setting that element’s class to focus. No need to create a Wheels partial and set a variable in your CFML .

In my newbness, I wasn’t thinking that you could have that $(".focus") hanging there without it applying to something on every page. Now I am schooled.

Thanks Stephen!

Technorati Tags: cfml, cfwheels, ColdFusion, coldfusion on wheels, html, javascript, jQuery

Keep up the great work everyone!

Just like Rails, CFWheels supports layouts to create a master template and to avoid repeating yourself.

For our simple app, we could just work with the default layout located at /views/layout.cfm. But, to follow the book, let’s create a controller-specific layout at: /views/ads/layout.cfm. So, this layout.cfm in the /view/ads/ subdirectory will only be used for views associated with the ads controller.

[cf]
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<cfoutput>
<title>Ads: #params.action#</title>
#stylesheetLinkTag("default")#
</cfoutput>
</head>
<body>
<cfoutput>
<div id="wrapper">
<div id="header">
<div>
<h1>MeBay</h1>
<ul id="nav">
<li>#linkTo(text="All Ads", route="adsNoKey")#</li>
</ul>
</div>
</div>

<div id="content">
#contentForLayout()#
</div>
<div id="clearfooter"></div>
</div>
<div id="footer"></div>
</cfoutput>
</body>
</html>
[/cf]

Most of this code is HTML boilerplate. #params.action# inserts the name of the current action in the Title tag. The params structure is always passed from the controller to the view. It includes the name of the action, variables, etc. You can always cfdump it out if you want to see what all is in there.

#stylesheetLinkTag(”default”)# uses another CFWheels helper function. By convention, stylesheets are located in the /stylesheets directory. So this function builds the link to our stylesheet named default.css. Download the code for Chapter 2 from the Head First Rails website, and get default.css from the /public/stylesheets/ folder. In CFWheels, put default.css in your /stylesheets folder. If you have trouble with the stylesheet, make sure all the images references are correct. If your web server configuration is different, you might need to adjust the paths.

On line 16, we’ve setup a link to our index action.

On line 22, you see #contentForLayout()#. This is where CFWheels puts the content from the other view pages — show.cfm and index.cfm. It’s the equivalent of <%= yield %> in Rails.

That’s it! Now we have a pretty, styled meBay application. Visit http://localhost/index.cfm/ads/ and see how pretty things look.

Next, it’s on to Chapter 3. In software development, things always change. And, now meBay wants to let people post ads online!

First, let’s add a new route so that http://localhost/index.cfm/ads/ goes to the new index action we’ll add in a minute.

Open up /config/routes.cfm, and change it to:

[cf]
<cfset addRoute(name="ads", pattern="/ads/[key]", controller="ads", action="show")>
<cfset addRoute(name="adsNoKey", pattern="/ads/", controller="ads", action="index")>
<cfset addRoute(name="catchall", pattern="[path]", controller="redirect", action="index")>
<cfset addRoute(name="home", pattern="", controller="redirect", action="index")>
[/cf]

Notice the new route on line 2: <cfset addRoute(name=”adsNoKey”, pattern=”/ads/”, controller=”ads”, action=”index”)>. CFWheels checks the routes in order. So, if the URL pattern matches /ads/[key], it will go to the show action. But, if the key isn’t there, it matches the /ads/ pattern and goes to the new index action.

Now, we need to add an index action to the controller and then an index.cfm view. Open up /controllers/Ads.cfc and add the new index function. Leave the show function alone.

[cf]
<!— ads/index —>
<cffunction name="index">
<cfset ads = model("Ad").findAll()>
<cfdump var="#ads#"><cfabort>
</cffunction>
[/cf]

Notice the that we set ads = model(”Ad”).findAll(). This tells Wheels, to go get the Ad model, and findAll the data — Pretty Powerful! The data comes back as a ColdFusion query object.

For testing, put the <cfdump>line in your controller, and send your browser to: http://localhost/index.cfm/ads/. You’ll see the query dumped out in all its glory! This is a pretty good debugging trick. Add a <cfdump> to your controller to see what variables and data the controller is passing to the view. Remove the <cfdump> line, and let’s go create the view.

Go create /views/ads/index.cfm:

[cf]
<h1>All Ads</h1>
<ul>
<cfoutput query="ads">
<li>#linkTo(text="#ads.name#", route="ads", key="#ads.id#")#</li>
</cfoutput>
</ul>
[/cf]

Pretty simple! Specifying the query attribute in <cfoutput> makes this just like a <cfloop>. You end up with a bunch of List Items (<li>) — One for each record in the query we got from the controller.

linkTo() is another cool Wheels helper function. You could just use an <a> tag. However, using the linkTo() function is a best practice because it makes your application more portable. We specified the “ads” route in the function. If, later on, we changed our subfolders or URL rewriting, everything would still work.

That’s it. Send your browser to: http://localhost/index.cfm/ads/ and you should see a list of ads. Each ad will have a link that takes you to the show action and displays the ad.

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

[cf]
<cffunction name="show">
<!— Find the record —>
<cfset ad = model("Ad").findByKey(params.key)>
</cffunction>
[/cf]

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:

[cf]
<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>
[/cf]

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.

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:

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

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!

[cf]
<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")>
[/cf]

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!

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:

[cf]
<cfcomponent extends="Controller">

<cffunction name="index">

</cffunction>

<cffunction name="show">

</cffunction>

</cfcomponent>
[/cf]

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:

[cf]
<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>
[/cf]

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.

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.

[sql]

CREATE TABLE `ads` (
`id` INTEGER PRIMARY KEY NOT NULL auto_increment,
`name` varchar(255),
`description` text,
`price` decimal,
`seller_id` integer,
`email` varchar(255),
`img_url` varchar(255),
`created_at` datetime,
`updated_at` datetime
);
[/sql]

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:

[sql]
DROP TABLE IF EXISTS `ads` ;
CREATE TABLE `ads` (
`id` INTEGER PRIMARY KEY NOT NULL auto_increment,
`name` varchar(255),
`description` text,
`price` decimal,
`seller_id` integer,
`email` varchar(255),
`img_url` varchar(255),
`created_at` datetime,
`updated_at` datetime
);
INSERT INTO `ads` VALUES(1,’Typewriter’,'Old manual typewriter. Many years useful service. Works best with a bottle next to it.’,71.95,54,’dhammett@email.com’,'http://homepage.mac.com/david_griffiths/typewriter.png’,”,”);
INSERT INTO `ads` VALUES(2,’Football’,'Some strings frayed.’,74.02,45,’marty@googlemail.com’,'http://www.freefever.com/freeclipart/clipart/football2.gif’,”,”);
INSERT INTO `ads` VALUES(3,’Moosehead’,'Slightly moth-eaten. One of the antlers is broken and there’’s a strange buzzing sound behind the eyes…’,2978.25,56,’kathy@hotmail.com’,'http://saloon.javaranch.com/ubb/moosefly.gif’,”,”);
INSERT INTO `ads` VALUES(4,’Desk’,'Milk desk - go…’,4800,123,’andy@allmail….’,'http://picasaweb.goog…’,”,”);
INSERT INTO `ads` VALUES(5,’Door curtain’,'Beaded door cu…’,11,773,’dawn@hotmail….’,'http://www.freewebsit…’,”,”);
INSERT INTO `ads` VALUES(6,’Apple Newton’,'Still works! M…’,25,2,’ahertz@differ…’,'http://www.differnet….’,”,”);
INSERT INTO `ads` VALUES(7,’Sinclair C5′,’Battery flat t…’,372.06,346,’clive@sinclai…’,'http://www.ebay.com/w…’,”,”);
INSERT INTO `ads` VALUES(8,’Edsel’,'Never used aut…’,355,755,’bing@badabing…’,'http://pages.google.c…’,”,”);
INSERT INTO `ads` VALUES(37,’Diamond’,'203.4 carats, grade D pear cut diamond. Low price for quick sale. Owner leaving the country.’,1000000,5234,’pink@panther.com’,'http://’,”,”);
[/sql]

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:

[cf]
<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>
[/cf]

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!

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:

CREATE TABLE `events` (
`id` int(11) NOT NULL auto_increment,
`artist` varchar(255) NOT NULL,
`description` text,
`price_low` decimal NOT NULL,
`price_high` decimal NOT NULL,
`event_date` date NOT NULL,
PRIMARY KEY (`id`)
)

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.

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’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!

On top of all that, while I was just sitting down to type this out, I saw that the two commits to trunk that I made today weren’t the smartest changes either and I was asked to revert them, which I did.

I think I’m going to take a break tomorrow from testing and trying to find bugs since I basically creating my own

Wheels was donated some migration code quite a while ago from Ryan. One of my goals this weeks was to try to get migrations working. I figured tomorrow I fork the my local repo and see what I can do to get this in.

The entire day was spent revamping the testing framework for the last time (I hope) as I think I finally got it to where I want it to be. I did a bunch of optimizations to the testrunner and the output display. In doing so I discover the beauty of getComponentMetaData().

When running the tests, I had some logic in place that basically would inspect the meta data of the component you wanted to test to see if it is extending the wheels.test base component. There’s no reason to even waste the time searching for tests to run if the component won’t even have any and the only way it’s going to have tests is if it extends the wheels.test base component.

In order to do the check I would use createobject to create an instance of the component and then use getMetaData() to inspect the meta data. To me this seemed kinda dumb and it bothered me that I knew there had to be a better way and that’s when I found getCompoentMetaData(). Basically this does the same thing as getMetaData() but you don’t have to waste your time instantiating the component. All you have to do is pass the component path to getComponentMetaData() and it does the work for you and returns the exact same meta data that getMetaData() would. Very handy function indeed.

The other thing that was bothering me was the hackery way I was altering the application.wheels.modelPath and the application.wheels.modelComponentPath so that I could call test models with the model() function. Before I was performing my half ass hack inside the test cases themselves in the setup(), but I knew that this was going to get messy. It finally dawned on me to just add them into the testing framework itself for now. Later on we’ll think of a better way to pass a component path to model(), but as for right now this prevents me from having to do the hack manually and even though it’s still a hack, it’s a bit cleaner.

After finally getting the testing framework ironed out, I moved on to refactoring all the tests to get more output and separate the multiple calls to assert() I was doing in each test. All and all, Wheels not has 61 tests in 19 cases. Not bad for a start. It’s definitely NOT where I wanted to be at this point, but there’s no sense in rushing either.

Tonight I ‘m going to do some research into designing a testing database that I can use to properly test the model layer. I’m sure I’ll be totally OCD about the way it’s designed and will spend most of the day second guessing myself over and over. One of the ideas to get around this was was to look at maybe using the blogCFC database since it’s already been ported to like EVERY RDBMS engine out there (go Ray!). We’ll have to see.

Will update again tomorrow.

Well first off, I updated my cygwin install with the latest version of git and subervion-perl a couple of weeks ago and when I went to rebase with the CFWheels repo, it would die. Only one commit at a time would be pulled down and then errors all over the place. After searching on google I found out that this is a known problem with the latest subversion-perl so I had to downgrade. That took me about an hour to figure out. I could have applied a patch to the version that I had already installed, but I wasn’t in the mood to be jerking around like that and I figured I’d leave that stuff to the experts.

After that I was finally able to sync with the svn repo and get everything up and running.

With my confidence in the toliet, I started writing tests and finding bugs that needed to be fixed. When I found my first bug, I decided to use trusty old tortoisesvn to write the patch and get it into trunk since I had local checkout already. That went well, but it wasn’t the best way to do it. I should be using git and git-svn to do this stuff and by using tortise I had to litterally duplicate the patch that I already had in git. NOT SMART!

Anyhow, I continued coding and soon found another bug that needed some attention. “WHAT LUCK!” I thought because now I could submit the patch through git-svn like I should have been doing all along. BIG MISTAKE! Let’s just say that I fought with this for almost two hours, because I kept screwing up the workflow left and right and having to git reset –hard. Thank God that stackoverflow.com exists and after reading carefully, the solution that I found, and some playing around, I finally got the workflow down and was able to commit the patch.

All and all, I’m having a rough time. Maybe I’m just off my game today since I have a lot of other things in my head right now and my mental state isn’t in sync. No matter, tomorrow is another day and more coding.

Tomorrow I’m planning on completing the creation of a test database so that I can test out all the functions that depend on models and cleanning up the tests.

About the tests. Right now, the way I’m writing tests, I’ll have more then one assert in each test. From what I’ve seen and researched how other people write tests, this is the wrong way. You should have one assert for each test. After writing a bunch of them, this makes sense. Reason being is because if you have 5 asserts in one test and one of the asserts fails, the whole test fails. Now currently this isn’t a problem because I know it’s the last assert I wrote that failed. However, down the road I can see this becoming a problem when we’re trying to figure out where the test is failing. It’s not like I want the rest of the team to be commenting out asserts until they find the one thats failing. I come to the conclusion at this point that I’m going to have to rewrite all the tests I’ve created into this new format. Oh well it’s what learning is all about and the reason I love doing open source stuff.

I’ll update again tomorrow.

Again, if you want to help in anyway, either use google code or github to check out the code.