Creating Records

How to create new objects and save them to the database.

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 your new author to the database right away, you can use the create() method instead.

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


Primary Key Conventions

Note that we never have to set a value for the primary key property. This is because we use the Wheels convention of having an auto-incrementing integer field named id as the primary key.

After saving the object to the database, the id property will be added to the object so you can read the value by doing something like this:

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


You don't need to follow these conventions at all though. You can name your primary key something other than id, 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.