ColdBox HMVC Documentation
DocsSourceSupportTraining
7.x
7.x
  • Introduction
    • Contributing Guide
    • Release History
      • What's New With 7.4.0
      • What's New With 7.3.x
      • What's New With 7.2.0
      • What's New With 7.1.0
      • What's New With 7.0.0
        • Release Notes
    • Upgrading to ColdBox 7
    • What is ColdBox
    • What is MVC
    • About This Book
      • Author
  • For Newbies
    • 60 Minute Quick Start
      • Installing ColdBox
      • My First ColdBox Application
      • My First Handler & View
      • Linking Events Together
      • Working with Events
      • Adding A Layout
      • Adding A Model
      • RESTFul Data
      • Next Steps
    • Getting Started Guide
  • Getting Started
    • Installation
    • Application Templates
    • Conventions
    • Configuration
      • ColdBox.cfc
        • Configuration Directives
          • CacheBox
          • ColdBox
          • Conventions
          • Environments
          • Flash
          • InterceptorSettings
          • Interceptors
          • Layouts
          • LayoutSettings
          • LogBox
          • Modules
          • ModuleSettings
          • Settings
          • WireBox
        • System Settings (Java Properties and Environment Variables)
      • Using Settings
      • Bootstrapper - Application.cfc
  • The Basics
    • Request Context
    • Routing
      • Requirements
        • Rewrite Rules
      • Application Router
      • Routing DSL
        • Routing By Convention
        • Pattern Placeholders
        • Routing Methods
        • Resourceful Routes
        • Named Routes
        • Routing Groups
        • Routing Namespaces
      • Building Routable Links
      • RESTFul Extension Detection
      • HTTP Method Spoofing
      • HTML Base Tag
      • Pathinfo Providers
    • Event Handlers
      • How are events called?
      • Getting & Setting Values
      • Setting Views
      • Relocating
      • Rendering Data
      • Sending Files
      • Interception Methods
        • Pre Advices
        • Post Advices
        • Around Advices
      • Model Integration
        • Model Data Binding
      • HTTP Method Security
      • Implicit Methods
      • Executing Events
      • Executing Routes
      • Viewlets - Reusable Events
      • Event Caching
      • Validation
    • Layouts & Views
      • Views
        • Rendering Views
        • Rendering External Views
        • Rendering With Local Variables
        • Rendering Collections
        • View Caching
        • View Helpers
        • View Events
      • Layouts
        • Basic Layouts
        • Default Layout
        • Nested Layouts
        • Overriding Layouts
        • Layouts From A Module
        • Layout Helpers
        • Layout Events
      • Implicit Layout-View Declarations
      • Helpers UDF's
      • ColdBox Elixir
    • Models
      • Domain Modeling
        • Service Layer
        • Data Layers
        • Book
      • Conventions Location
      • WireBox Binder
      • Super Type Usage Methods
      • Injection DSL
        • ColdBox Namespace
        • CacheBox Namespace
        • EntityService Namespace
        • Executor Namespace
        • Java Namespace
        • LogBox Namespace
        • Models Namespace
        • Provider Namespace
        • WireBox Namespace
      • Object Scopes
      • Coding: Solo Style
        • Datasource
        • Contact.cfc
        • ContactDAO.cfc
        • ContactService.cfc
        • Contacts Handler
      • Coding: ActiveEntity Style
        • ORM
        • Contact.cfc
        • Contacts Handler
        • Views
      • Coding: Virtual Service Layer
        • ORM
        • Contacts.cfc
        • Contacts Handler
        • Views
      • Coding: ORM Scaffolding
        • ORM
        • Contacts.cfc
        • Scaffold
    • Interceptors
      • How do they work?
        • Conventions
      • Interceptor Declaration
      • Interceptor Registration
      • Dynamic Registration
      • Core Interception Points
        • Application Life Cycle Events
        • Object Creating Events
        • Layout-View Events
        • Module Events
        • CacheBox Events
      • Restricting Execution
      • Interceptor Output Buffer
      • Custom Events
        • Configuration Registration
        • Programmatic Registration
        • Listening
        • Announcing Interceptions
      • Unregistering Interceptors
      • Reporting Methods
      • Interceptor Asynchronicity
        • Async Announcements
        • Async Listeners With Join
        • Async Listeners No Join
        • Asynchronous Annotations
  • HMVC
    • Modules
      • Core Modules
      • Locations
      • Parent Configuration
      • Module Layout
        • Changing The Module Layout
      • Module Service
        • Module Lifecycle
        • Module Registration
        • Module Activation
        • Module Unloading
        • Common Methods
        • Loading New Modules
        • Loading A-la-carte Modules
        • Module Events
      • ModuleConfig
        • Public Module Properties
        • The Decorated Variables
        • The configure() Method
        • Module Settings
        • Environment Control
        • Interceptor Events
      • Module Event Executions
      • URL Routing
        • Default Route Execution
        • Module Routes Files
      • Module Async Scheduling
      • Request Context Module Methods
      • Layout and View Renderings
        • Layout/View Discovery
        • Overriding Views
        • Overriding Layouts
        • Default Module Layout
        • Explicit Module Renderings
      • Models
      • Module CF Mappings
      • Module Dependencies
      • Module Helpers
      • Module Bundles
      • Module Inception
  • Testing
    • Testing Quick Start
    • Testing ColdBox Applications
      • Test Harness
      • ColdBox Testing Classes
      • Testing Methods
      • Integration Testing
        • Test Annotations
        • Life-Cycle Events
        • Request Setup()
        • The execute() Method
        • HTTP Testing Methods
        • Testing Without Virtual Application
      • Interceptor Testing
      • Model Object Testing
      • Tips & Tricks
  • Digging Deeper
    • Async Programming
      • Async Pipelines & Futures
      • Parallel Computations
      • Executors
      • Scheduled Tasks
    • ColdBox Proxy
      • Getting Started
      • The Base Proxy Object
      • The Event Handlers
        • Distinguishing Request Types
        • RenderData()
      • Proxy Events
      • Standard Return Types
      • Caveats & Gotchas
    • Controller Decorator
    • ColdBox Scheduled Tasks
    • Flash RAM
      • Flash Storage
      • Using Flash RAM
      • Creating Your Own Flash Scope
    • HTML Helper
    • REST Handler
    • Request Context Decorator
    • Recipes
      • Building REST APIs
      • ColdBox Exception Handling
      • Debugging ColdBox Apps
      • Clearing the View Cache
      • Basic HTTP Authentication Interceptor
  • Architecture Concepts
    • How ColdBox Works
Powered by GitBook
On this page
  • populate()
  • Examples
  • ORM Integration
  • Mass Population Control: this.population

Was this helpful?

Edit on GitHub
Export as PDF
  1. The Basics
  2. Event Handlers
  3. Model Integration

Model Data Binding

Easily bind incoming data into your models.

Last updated 1 year ago

Was this helpful?

ColdBox allows you to populate data from FORM/URL/REMOTE/XML/JSON/Struct into your model objects by convention. This is done via capabilities.

populate()

The super type has a method called populate which you will use to trigger the data binding. The supported incoming data sources are:

  • request collection RC

  • structs

  • json

  • xml

  • query

The method will try to match the incoming variables names in the data packet to a setter or property in the target model object. If there is a match, then it will inject that data into the model or call it's setter for you.

Let's explore the API


/**
 * Populate an object from the incoming request collection
 *
 * @model                The name of the model to get and populate or the acutal model object. If you already have an instance of a model, then use the populateBean() method
 * @scope                Use scope injection instead of setters population. Ex: scope=variables.instance.
 * @trustedSetter        If set to true, the setter method will be called even if it does not exist in the object
 * @include              A list of keys to include in the population
 * @exclude              A list of keys to exclude in the population
 * @ignoreEmpty          Ignore empty values on populations, great for ORM population
 * @nullEmptyInclude     A list of keys to NULL when empty
 * @nullEmptyExclude     A list of keys to NOT NULL when empty
 * @composeRelationships Automatically attempt to compose relationships from memento
 * @memento              A structure to populate the model, if not passed it defaults to the request collection
 * @jsonstring           If you pass a json string, we will populate your model with it
 * @xml                  If you pass an xml string, we will populate your model with it
 * @qry                  If you pass a query, we will populate your model with it
 * @rowNumber            The row of the qry parameter to populate your model with
 * @ignoreTargetLists    If this is true, then the populator will ignore the target's population include/exclude metadata lists. By default this is false.
 *
 * @return The instance populated
 */
function populate(
	required model,
	scope                        = "",
	boolean trustedSetter        = false,
	include                      = "",
	exclude                      = "",
	boolean ignoreEmpty          = false,
	nullEmptyInclude             = "",
	nullEmptyExclude             = "",
	boolean composeRelationships = false,
	struct memento               = getRequestCollection(),
	string jsonstring,
	string xml,
	query qry,
	boolean ignoreTargetLists = false
)

Examples

Let's do a quick example. Here is a Person.cfc that has two properties with automatic getters/setters.

Person.cfc

models/Person.cfc
component accessors="true"{

    property name="name";
    property name="email";

    function init(){
        setName('');
        setEmail('');
    }
}

editor.cfm

Here is an editor to submit a form to create the person.

views/person/editor.cfm
<cfoutput>
<h1>Funky Person Form</h1>
#html.startForm( action='person.save' )#

    #html.textfield( label="Your Name:", name="name", wrapper="div")#
    #html.textfield( label="Your Email:", name="email", wrapper="div")#

    #html.submitButton( value="Save" )#

#html.endForm()#
</cfoutput>

Event Handler -> person.cfc

Here is an event handler to do the saving

handlers/person.cfc
component{

    function editor(event,rc,prc){
        event.setView( "person/editor" );        
    }

    function save(event,rc,prc){

        var person = populateModel( "Person" );

        writeDump( person );
        abort;
    }

}

Run the code, and you will see that the populator matched the incoming variables into the model and thus binding it.

ORM Integration

The populator can also bind ORM objects natively. However, it can also build out relationships via the composeRelationships argument. This allows you to create the objects from simple identifiers for the following relationships:

  • one-to-one : The id of the relationship

  • many-to-one : The id of the parent relationship

  • one-to-many : A list of identifiers to link to the target object which ends up being an array of objects

  • many-to-many : A list of identifiers to link to the target object which ends up being an array of objects

So if we have a User object with a many-to-one of Role and a many-to-many of Permissions, we could populate the User with all of it's data graph:

user.json
{
   "fname" : "luis",
   "lname" : "coldbox",
   "role" : 123,
   "permissions" : "123,456,789"
}

This packet has the two relationships role and permissions as an incoming list. The list can be a simple string or an actual JSON array. To populate we can do this:

populate( model : "User", composeRelationships : true )

That's it. ColdBox will take care of matching and building out the relationships.

You can also use the nullEmptyInclude and nullEmptyExclude properties to include and exclude null value population.

You can also use ignoreEmpty to ignore all the empty values on population so the ORM treats them as null

Mass Population Control: this.population

ColdBox also supports the ability for target objects to dictate how they will be populated. This convention allows for objects to encapsulate the way the mass population of data is treated. This way, you don’t have to scrub or pass include excludes lists via population arguments; it can all be nicely encapsulated in the targeted objects. Just declare a this.population in your object's pseudo constructor:

this.population = {
    include : [ "firstName", "lastName", "username", "role" ],
    exclude : [ "id", "password", "lastLogin" ]
};

The populator will look for a this.population struct with the following keys:

  • include : an array of property names to allow population ONLY

  • exclude : an array of property names to NEVER allow population

Ignoring Mass Population

The population methods also have an argument called: ignoreTargetLists which defaults to false, meaning it inspects the objects for these population markers. If you pass it as true then the markers will be ignored. This is great for the population of objects from queries or an array of structs or mementos that YOU have control of. Great in DAOs or service layers.`

populateFromStruct(
    target : userService.newUser(),
    memento : record,
    ignoreTargetLists : true
}

WireBox's object population