Nested Properties
Save data in associated model objects through the parent.
When you're starting out as a Wheels developer, you are probably amazed at the simplicity of a model's CRUD methods. But then it all gets quite a bit more complex when you need to update records in multiple database tables in a single transaction.
Nested properties in Wheels makes this scenario dead simple. With a configuration using the nestedProperties()function in your model's
config()
method, you can save changes to that model and its associated models in a single call with save(), create(), or update().Consider a
user
model that has one profile
:models/User.cfc
component extends="Model" {
function config() {
hasOne("profile");
nestedProperties(associations="profile");
}
}
By adding the call to nestedProperties() in the model, you can create both the
user
object and the profile
object in a single call to create().First, in our controller, let's set the data needed for our form:
controllers/User.cfc
// In controllers/User.cfc
function new() {
var newProfile = model("profile").new();
user = model("user").new(profile=newProfile);
}
Because our form will also expect an object called
profile
nested within the user
object, we must create a new instance of it and set it as a property in the call to user.new()
.Also, because we don't intend on using the particular
newProfile
object set in the first line of the action, we can var
scope it to clearly mark our intentions for its use.If this were an
edit
action calling an existing object, our call would need to look similar to this:controllers/User.cfc
function edit() {
user = model("user").findByKey(key=params.key, include="profile");
}
Because the form will also expect data set in the
profile
property, you must include that association in the finder call with the include
argument.For this example, our form at
views/users/new.cfm
will end up looking like this:views/users/new.cfm
#startFormTag(action="create")#
<!--- Data for user model --->
#textField(label="First Name", objectName="user", property="firstName")#
#textField(label="Last Name", objectName="user", property="lastName")#
<!--- Data for associated profile model --->
#textField(
label="Twitter Handle",
objectName="user",
association="profile",
property="twitterHandle"
)#
#textArea(
label="Biography",
objectName="user",
association="profile",
property="bio"
)#
<div>#submitTag(value="Create")#</div>
#endFormTag()#
Of note are the calls to form helpers for the
profile
model, which contain an extra argument for association
. This argument is available for all object-based form helpers. By using the association
argument, Wheels will name the form field in such a way that the properties for the profile will be nested within an object in the user
model.Take a minute to read that last statement again. OK, let's move on to the action that handles the form submission.
You may be surprised to find out that our standard
create
action does not change at all from what you're used to.controllers/Users.cfc
function create() {
user = model("user").new(params.user);
if ( user.save() ) {
flashInsert(success="The user was created successfully.");
redirectTo(controller=params.controller);
} else {
renderView(action="new");
}
}
When calling
user.save()
in the example above, Wheels takes care of the following:- Saves the data passed into the
user
model. - Sets a property on
user
called profile with theprofile
data stored in an object. - Saves the data passed into that
profile
model. - Wraps all calls in a transaction in case validations on any of the objects fail or something wrong happens with the database.
For the
edit
scenario, this is what our update
action would look like (which is very similar to create
):controllers/Users.cfc
function update() {
user = model("user").findByKey(params.user.id);
if ( user.update(params.user) ) {
flashInsert(success="The user was updated successfully.");
redirectTo(action="edit");
} else {
renderView(action="edit");
}
}
Nested properties work with one-to-many associations as well, except now the nested properties will contain an array of objects instead of a single one. We know that one
user
can have many addresses
. Furthermore, we know that each user
has only one profile
. In the
user
model, let's add an association called addresses
and also enable it as nested properties.models/User.cfc
component extends="Model" {
function config() {
hasOne("profile");
hasMany("addresses");
nestedProperties(
associations="profile,addresses",
allowDelete=true
);
}
}
The
addresses
table contains a foreign key to the Users
table called userid
, Now in the addresses
model, let's associate it with its parent User
and also enable it as nested properties.models/Address.cfc
component extends="Model" {
function config() {
belongsTo("User");
nestedProperties(
associations="User",
allowDelete=true
);
}
}
Setting up data for the form is similar to the one-to-one scenario, but this time the form will expect an array of objects for the nested properties instead of a single object.
In this example, we'll just put one new
address
in the array.controllers/Users.cfc
function new() {
var newAddresses = [ model("address").new() ];
user = model("user").new(addresses=newAddresses);
}
In the
edit
scenario, we just need to remember to call the include
argument to include the array of addresses saved for the particular user
:controllers/Users.cfc
function edit() {
user = model("user").findByKey(key=params.key, include="addresses");
}
This time, we'll add a section for addresses on our form:
views/users/_form.cfm
#startFormTag(action="create")#
<!--- Data for `user` model --->
<fieldset>
<legend>User</legend>
#textField(label="First Name", objectName="user", property="firstName")#
#textField(label="Last Name", objectName="user", property="lastName")#
</fieldset>
<!--- Data for `address` models --->
<fieldset>
<legend>Addresses</legend>
<div id="addresses">
#includePartial(user.addresses)#
</div>
</fieldset>
<div>#submitTag(value="Create")#</div>
#endFormTag()#
In this case, you'll see that the form for addresses is broken into a partial. (See the chapter on Partials for more details.) Let's take a look at that partial.
Here is the code for the partial at
views/users/_address.cfm
. Wheels will loop through each address
in your nested properties and display this piece of code for each one.views/users/_address.cfm
<div class="address">
#textField(
label="Street",
objectName="user",
association="addresses",
position=arguments.current,
property="address1"
)#
#textField(
label="City",
objectName="user",
association="addresses",
position=arguments.current,
property="city"
)#
#textField(
label="State",
objectName="user",
association="addresses",
position=arguments.current,
property="state"
)#
#textField(
label="Zip",
objectName="user",
association="addresses",
position=arguments.current,
property="zip"
)#
</div>
Because there can be multiple addresses on the form, the form helpers require an additional argument for
position
. Without having a unique position identifier for each address
, Wheels would have no way of understanding which state
field matches with which particular address
, for example.Here, we're passing a value of
arguments.current
for position
. This value is set automatically by Wheels for each iteration through the loop of addresses
.Basically, your typical code to save the
user
and its addresses
is exactly the same as the code demonstrated in the Saving the Object and Its Nested Properties section earlier in this chapter.Writing the action to save the data is clearly the easiest part of this process!
As mentioned earlier, Wheels will automatically wrap your database operations for nested properties in a transaction. That way if something goes wrong with any of the operations, the transaction will rollback, and you won't end up with incomplete saves.
We all enter the scenario where we have "join tables" where we need to associate models in a many-to-many fashion. Wheels makes this pairing of entities simple with some form helpers.
Consider the many-to-many associations related to
customers, publications
, and subscriptions
, straight from the Associations chapter.// models/Customer.cfc
component extends="Model" {
public function config() {
hasMany(name="subscriptions", shortcut="publications");
}
}
// models/Publication.cfc
component extends="Model" {
public function config() {
hasMany("subscriptions");
}
}
// models/Subscription.cfc
component extends="Model" {
public function config() {
belongsTo("customer");
belongsTo("publication");
}
}
When it's time to save
customer
s' subscriptions in the subscriptions
join table, one approach is to loop through data submitted by checkBoxTag()s from your form, populate subscription
model objects with the data, and call save(). This approach is valid, but it is quite cumbersome. Fortunately, there is a simpler way.Here is how we would set up the nested properties in the
customer
model for this example:models/Customer.cfc
component extends="Model" {
public function config() {
// Associations
hasMany(name="subscriptions", shortcut="publications");
// Nested properties
nestedProperties(
associations="subscriptions",
allowDelete=true
);
}
}
Let's define the data needed in an
edit
action in the controller at controllers/Customers.cfc
.controllers/Customers.cfc
function edit() {
customer = model("customer").findByKey(
key=params.key,
include="subscriptions"
);
publications = model("publication").findAll(order="title");
}
For the view, we need to pull the
customer
with its associated subscriptions
included with the include
argument. We also need all of the publication
s in the system for the user to choose from.We can now build a series of check boxes that will allow the end user choose which
publications
to assign to the customer
.The view template at
views/customers/edit.cfm
is where the magic happens. In this view, we will have a form for editing the customer
and check boxes for selecting the customer
's subscriptions
.views/customers/edit.cfm
<cfparam name="customer">
<cfparam name="publications" type="query">
<cfoutput>
#startFormTag(action="update")#
<fieldset>
<legend>Customer</legend>
#textField(
label="First Name",
objectName="customer",
property="firstName"
)#
#textField(
label="Last Name",
objectName="customer",
property="lastName"
)#
</fieldset>
<fieldset>
<legend>Subscriptions</legend>
<cfloop query="publications">
#hasManyCheckBox(
label=publications.title,
objectName="customer",
association="subscriptions",
keys="#customer.key()#,#publications.id#"
)#
</cfloop>
</fieldset>
<div>
#hiddenField(objectName="customer", value="id")#
#submitTag()#
</div>
#endFormTag()#
</cfoutput>
The main point of interest in this example is the
<fieldset>
for Subscriptions, which loops through the query of publications
and uses the hasManyCheckBox() form helper. This helper is similar to checkBox() and checkBoxTag(), but it is specifically designed for building form data related by associations. (Note that checkBox() is primarily designed for columns in your table that store a single true/false
value, so that is the big difference.)Notice that the
objectName
argument passed to hasManyCheckBox() is the parent customer
object and the associations
argument contains the name of the related association. Wheels will build a form variable named in a way that the customer
object is automatically bound to the subscriptions
association.The
keys
argument accepts the foreign keys that should be associated together in the subscriptions
join table. Note that these keys should be listed in the order that they appear in the database table. In this example, the subscriptions
table in the database contains a composite primary key with columns called customerid
and publicationid
, in that order.Handling the form submission is the most powerful part of the process, but like all other nested properties scenarios, it involves no extra effort on your part.
You'll notice that this example
update
action is fairly standard for a Wheels application:controllers/Customers.cfc
function update() {
// Load customer object
customer = model("customer").findByKey(params.customer.id);
/* If update is successful, generate success message
and redirect back to edit screen */
if ( customer.update(params.customer) ) {
redirectTo(
action="edit",
key=customer.id,
success="#customer.firstName# #customer.lastName# record updated successfully."
);
// If update fails, show form with errors
} else {
renderView(action="edit");
}
}
In fact, there is nothing special about this. But with the nested properties defined in the model, Wheels handles quite a bit when you save the
parent
customer object:- Wheels will update the
customers
table with any changes submitted in the Customers<fieldset>
. - Wheels will add and remove records in the
subscriptions
table depending on which check boxes are selected by the user in the Subscriptions<fieldset>
. - All of these database queries will be wrapped in a Transaction . If any of the above updates don't pass validation or if the database queries fail, the transaction will roll back.