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 varscope 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
usermodel. - Sets a property on
usercalled profile with theprofiledata stored in an object. - Saves the data passed into that
profilemodel. - 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
customers' 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 publications 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
customerstable with any changes submitted in the Customers<fieldset>. - Wheels will add and remove records in the
subscriptionstable 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.