The framework also offers you the capability to bind incoming FORM/URL/REMOTE/XML/JSON/Structure data into your model objects by convention. This is done via WireBox's object population capabilities. The easiest approach is to use our populateModel() function which will populate the object from many incoming sources:
request collection RC
Structure
json
xml
query
This will try to match incoming variable names to setters or properties in your domain objects and then populate them for you. It can even do ORM entities with ALL of their respective relationships. Here is a snapshot of the method:
Let's do a quick example:
Person.cfc
editor.cfm
Event Handler -> person.cfc
In the dump you will see that the name and email properties have been bound.
component accessors="true"{
property name="name";
property name="email";
function init(){
setName('');
setEmail('');
}
}<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>/**
* Populate a model object from the request Collection or a passed in memento structure
* @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
*/
function populateModel(
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
){component{
function editor(event,rc,prc){
event.setView("person/editor");
}
function save(event,rc,prc){
var person = populateModel( "Person" );
writeDump( person );abort;
}
}We have a complete section dedicated to the Model Layer, but we wanted to review a little here since event handlers need to talk to the model layer all the time. By default, you can interact with your models from your event handlers in two ways:
Dependency Injection (Aggregation)
Request, use and discard model objects (Association)
ColdBox offers its own dependency injection framework, WireBox, which allows you, by convention, to talk to your model objects. However, ColdBox also allows you to connect to third-party dependency injection frameworks via the IOC module: http://forgebox.io/view/cbioc
Your event handlers can be autowired with dependencies from by convention. By autowiring dependencies into event handlers, they will become part of the life span of the event handlers (singletons), since their references will be injected into the handler's variables scope. This is a huge performance benefit since event handlers are wired with all necessary dependencies upon creation instead of requesting dependencies (usage) at runtime. We encourage you to use injection whenever possible.
Warning As a rule of thumb, inject only singletons into singletons. If not you can create unnecessary issues and memory leaks.
You will achieve this in your handlers via property injection, which is the concept of defining properties in the component with a special annotation called inject, which tells WireBox what reference to retrieve via the . Let's say we have a users handler that needs to talk to a model called UserService. Here is the directory layout so we can see the conventions
Here is the event handler code to leverage the injection:
Notice that we define a cfproperty with a name and inject attribute. The name becomes the name of the variable in the variables scope and the inject annotation tells WireBox what to retrieve. By default it retrieves model objects by name and path.
Tip: The is vast and elegant. Please refer to it. Also note that you can create object aliases and references in your : config/WireBox.cfc
The other approach to integrating with model objects is to request and use them as via the framework super type method: getInstance(), which in turn delegates to WireBox's getInstance() method. We would recommend requesting objects if they are transient (have state) objects or stored in some other volatile storage scope (session, request, application, cache, etc). Retrieving of objects is okay, but if you will be dealing with mostly singleton objects or objects that are created only once, you will gain much more performance by using injection.
In this practical example we will see how to integrate with our model layer via WireBox, injections, and also requesting the objects. Let's say that we have a service object we have built called FunkyService.cfc and by convention we will place it in our applications models folder.
FunkyService.cfc
Our funky service is not that funky after all, but it is simple. How do we interact with it? Let's build a Funky event handler and work with it.
By convention, I can create a property and annotate it with an inject attribute. ColdBox will look for that model object by the given name in the models folder, create it, persist it, wire it, and return it. If you execute it, you will get something like this:
Great! Just like that we can interact with our model layer without worrying about creating the objects, persisting them, and even wiring them. Those are all the benefits that dependency injection and model integration bring to the table.
You can use the value of the inject annotation in several ways. Below is our recommendation.
Let's look at the requesting approach. We can either use the following approaches:
Via Facade Method
Directly via WireBox:
Both approaches do exactly the same thing. In reality getInstance() does a wirebox.getInstance() callback (Uncle Bob), but it is a facade method that is easier to remember. If you run this, you will also see that it works and everything is fine and dandy. However, the biggest difference between injection and usage can be seen with some practical math:
As you can see, the best performance is due to injection as the handler object was wired and ready to roll, while the requested approach needed the dependency to be requested. Again, there are cases where you need to request objects such as transient or volatile stored objects.
+ handlers
+ users.cfc
+ models
+ UserService.cfccomponent name="MyHandler"{
// Dependency injection of the model: UserService -> variables.userService
property name="userService" inject="UserService";
function index( event, rc, prc ){
prc.data = userService.list()
event.setView( "users/index" );
}
}component{
function index( event, rc, prc ){
// Request to use the user service, this would be best to inject instead
// of requesting it.
prc.data = getInstance( "UserService" ).list();
event.setView( "users/index" );
}
function save( event, rc, prc ){
// request a user transient object, populate it and save it.
prc.oUser = populateModel( getInstance( "User" ) );
userService.save( prc.oUser );
relocate( "users/index" );
}
} + application
+ models
+ FunkyService.cfccomponent singleton{
function init(){
return this;
}
function add(a,b){
return a+b;
}
function getFunkyData(){
var data = [
{name="Luis", age="33"},
{name="Jim", age="99"},
{name="Alex", age="1"},
{name="Joe", age="23"}
];
return data;
}
}component{
// Injection via property
property name="funkyService" inject="FunkyService";
function index(event,rc,prc){
prc.data = funkyService.getFunkyData();
event.renderData( data=prc.data, type="xml" );
}
}<array>
<item>
<struct>
<name>Luis</name>
<age>33</age>
</struct>
</item>
<item>
<struct>
<name>Jim</name>
<age>99</age>
</struct>
</item>
<item>
<struct>
<name>Alex</name>
<age>1</age>
</struct>
</item>
<item>
<struct>
<name>Joe</name>
<age>23</age>
</struct>
</item>
</array>// Injection using the DSL by default name/id lookup
property name="funkyService" inject="FunkyService";
// Injection using the DSL id namespace
property name="funkyService" inject="id:FunkyService";
// Injection using the DSL model namespace
property name="funkyService" inject="model:FunkyService";component{
function index(event,rc,prc){
prc.data = getInstance( "FunkyService" ).getFunkyData();
event.renderData( data=prc.data, type="xml" );
}
}component{
function index(event,rc,prc){
prc.data = wirebox.getInstance( "FunkyService" ).getFunkyData();
event.renderData( data=prc.data, type="xml" );
}
}1000 Requests made to users.index
- Injection: 1000 handler calls + 1 model creation and wiring call = 1001 calls
- Requesting: 1000 handler calls + 1000 model retrieval + 1 model creation call = 2002 calls