nestedProperties()

Signature

nestedProperties() — returns void

Available in: model Category: Miscellaneous Functions

Description

Allows nested objects, arrays, or structs associated with a model to be automatically set from incoming params or other generated data. This is particularly useful when you have hasMany or belongsTo associations and want to manage them directly when saving the parent object.

Parameters

Name	Type	Required	Default	Description
association	string	no	—	The association (or list of associations) you want to allow to be set through the params. This argument is also aliased as associations.
autoSave	boolean	no	true	Whether to save the association(s) when the parent object is saved.
allowDelete	boolean	no	false	Set this to true to tell Wheels to look for the property _delete in your model. If present and set to a value that evaluates to true, the model will be deleted when saving the parent.
sortProperty	string	no	—	Set this to a property on the object that you would like to sort by. The property should be numeric, should start with 1, and should be consecutive. Only valid with hasMany associations.
rejectIfBlank	string	no	—	A list of properties that should not be blank. If any of the properties are blank, any CRUD operations will be rejected.

Examples

1. Basic nested association with auto-save
// app/models/User.cfc
function config(){
    hasMany("groupEntitlements");

    // Allow nested save of `groupEntitlements` when user is saved
    nestedProperties(association="groupEntitlements");
}

// Controller code
user = model("User").findByKey(1);
user.groupEntitlements = [
    {groupId=1, role="admin"},
    {groupId=2, role="editor"}
];
user.save(); 
// Both the user and nested groupEntitlements are saved automatically

2. Allow deletion of nested objects
function config(){
    hasMany("groupEntitlements");

    // Enable deletion via `_delete` flag
    nestedProperties(association="groupEntitlements", allowDelete=true);
}

// Example params
params.user.groupEntitlements = [
    {id=10, _delete=true},
    {groupId=3, role="viewer"}
];

user = model("User").findByKey(params.user.id);
user.setProperties(params.user);
user.save();
// The first nested object (id=10) is deleted, the second is saved