In Wheels, one way to create objects that represent records in our table is by calling the new() class-level method.

<cfset newAuthor = model("author").new()>

We now have an empty author object that we can start filling in properties for. These properties correspond with the columns in the authors database table, unless you have mapped them specifically to columns with other names (or mapped to an entirely different table).

<cfset newAuthor.firstName = "John">
<cfset newAuthor.lastName = "Doe">

At this point, the newAuthor object only exists in memory. We save it to the database by calling its save() method.

<cfset newAuthor.save()>

Creating Based on a Struct

If you want to create a new object based on parameters sent in from a form request, the new() method conveniently accepts a struct as well. As we'll see later, when you use the Wheels form helpers, they automatically turn your form variables into a struct that you can pass into new() and other methods.

Given that params.newAuthor is a struct containing the firstName and lastName variables, the code below does the same as the code above (without saving it though).

<cfset newAuthor = model("author").new(params.newAuthor)>

Saving Straight to the Database

If you want to save a new author to the database right away, you can use the create() method instead.

<cfset model("author").create(params.newAuthor)>

The Primary Key

Note that if we have opted to have the database create the primary key for us (which is usually done by auto-incrementing it) it will be available automatically after the object has been saved.

This means you can read the value by doing something like this (this example assumes you have an auto-incrementing integer column named id as the primary key):

<cfset newAuthor = model("author").new()>
<cfset newAuthor.firstName = "Joe">
<cfset newAuthor.lastName = "Jones">
<cfset newAuthor.save()>
<cfoutput>#newAuthor.id#</cfoutput>

Don't forget that you can name your primary key whatever you want and you can even use composite keys, natural keys, non auto-incrementing and so on.

No matter which method you prefer, Wheels will use database introspection to see how your table is structured and act accordingly.

Setting Default Values

If you're the kind of person who likes to give the database responsibility, you may have set your tables to create default values for new records. Wouldn't it be nice if you could also set these values automatically when creating new objects? Well, you can (surprise!), and it's dead simple too. Just pass in defaults=true to the new() method, and it will return the object with all the default values set on it. In the background, Wheels uses the excellent <cfdbinfo> tag on application start-up, so no extra database calls are required to use this functionality.

If you find that you end up passing in defaults=true all the time to new(), then you may consider overriding this Wheels convention and simply set defaults to true globally. This is done by adding the following line to your config/setting.cfm file:

<cfset set(functionName="new", defaults=true)>

You can also set the default values after the object has been saved to the database if you prefer (i.e. after create() or save() has been called). In fact, Wheels does this for you out of the box. If you don't like this convention, you can turn it off with the following line in config.cfm:

<cfset set(functionName="save", defaults=false)>