Hello Database Tutorial

[rob_parkhill]

Good Day,

Just wanted to make a quick suggestion for the 'Hello Database'
tutorial, having just worked through it.

I was stuck for quite a while on two things, one of which was my own
fault, but the other isn't clear.

For both, I think adding a small new section would be helpful. There
is no discussion of creating the controller for the User object at
all. There is the code (<cfset user = model("user").new()>) and you
are told to use it to start a new user, but with no indication of
where to put it. Does it go on the add.cfm page (which I thought
would be wrong as you would want to initialize that in the controller,
right?) so I created a controller (User) and created an Add function
in there. I then went merrily along with the rest of the tutorial,
and well, nothing worked.... I found, after a bit of frustration,
that my controller was named User, not Users. Anyways, perhaps the
following added to the documentation wouldn't be bad.
//
Supplying the form with data:
We need to supply our view code with an object called user. Because
the controller is responsible for providing the views with data, we'll
set it there.

As it turns out, our controller needs to provide the view with a blank
user object (whose instance variable will also be called user in this
case). In our add action, we will use the model() function to generate
a new instance of the user model.

To get a blank set of properties in the model, we'll also call the
generated model's new() method.

Create the Controller

Create a new controller (using the convention over configuration
method) named Users.cfc (same as the database table name) in the
controllers directory and add the following to it:

<cfcomponent extends="Controller">

<cffunction name="add">
<cfset user = model("user").new()>
</cffunction>
</cfcomponent>

This controller will then be the basis for all additional functions
that you want to perform on the user, as outlined below.

Note: Wheels will automatically know that we're talking about the
users database table when we instantiate a user model. The convention:
database tables are plural and their corresponding Wheels models are
singular.
//

Judging by the comments on that page, I am not the first person to be
confused by this at all. I mean it was a 'good' learning experience I
think for me, but some people tend to get frustrated and give up, and
a simple change would make it clearer and easier to understand.

And I'll ask if anyone is interested in me sharing my experiences/
suggestions for changes/improvements to the documentation as I learn
CFWheels? (Yeah, probably should've asked first, but too bad)

Cheers,

Rob

[Mike Henke]

Clarifying the Database tutorial sounds great. One thing, I noticed
when quickly reading through your clarification text: Controllers
don't have to match the db table name, though in this case it does.
Remember folders names in the views folder match to controllers and in
turn controller names are folders in the views folder.

So in the tutorial at this point, it determines your controller name:

Creating the Form
Now create a new file in views/users called add.cfm. This will contain
the view code for our simple form.

[Mike Henke]

Keep your suggestions coming. I added your idea here
http://cfwheelsorg.uservoice.com/forums/38297-website/suggestions/462726-clarify-database-tutorial?ref=title