• Fusebox Core Files
  • Fusebox XML Files
  • Circuit.xml
  • Circuit XML Grammar
  • Built-in Verbs
• Extending Fusebox
  • Lexicons
  • Plugins
  • Frameworks
• Search Fuseboxwiki

Transfer ORM

When developing an Object Oriented web based application, it is normal to have a database with relational tables and a series of objects that represent that data. Often, the amount of time and effort it takes to manually map these objects back and forth from a database is large, and can be very costly.

Object Relational Mappers (ORM) were developed to cut down the amount of time this process takes, and automate the translation between a relational database and an Object Oriented system.

Transfer ORM's main focus is to automate the repetitive tasks of creating the SQL and custom CFCs that are often required when developing a ColdFusion application. Through a central configuration file Transfer knows how to generate objects, and how to manage them and their relationships back to the database.

Setting up Fusebox for Transfer

To get Transfer setup you need to initilise the Transfer factory, you do this using the initialize verb. The best place to do this is in the appinit section of fusebox.xml.cfm as this is called when you start your app (it's like the onApplicationStart function in application.cfm). Within this function I call a fuseaction in my model circuit:

Then inside the model circuit I have this fuseaction

What we have just done:

1. We're declaring the namespace for the transfer lexicons
2. tr:init - this calls the initialize verb from the transfer lexicon folder to get Transfer setup.
3. datasource="/config/datasource.xml.cfm" - this is telling Transfer where to find the datasource config file.
4. configuration="/config/transfer.xml.cfm" - this is telling Transfer where to find the Transfer config file.
5. definitions="/model/transferData" - this tells transfer where to put it's generated code

One you run this code Transfer is up and running. Thats it, nothing else left to do. You now have access to all of Transfers features.

Transfer Configuration

Next you'll want to configure Transfer to tell it how all the tables are setup and related (we'll take a simple example here):

What we have just done:

1. <objectDefinitions> - this just declares that you're starting you object definitions
2. <package name="user"> - this is a neat way to group your objects together (you don't require this)
3. <object name="user" table="tblUser"> - this setup your object and gives it its name and tells it what table it refers to
4. <id ...- this is your primary key on the table
5. <property ... - we use property to list the table columns you want to return. Note you can use any name as long as you tell the property what column to use i.e. <property name="email" type="string" column="emailAddress" />
6. <onetomany name="address"> - this is telling Transfer that I want to join my user table to my address table, where the I have One user and Many Address
7. <link column="userID" to="address.address" /> - this is what I join the tables on. I'm telling transfer to look at the address object in the address package and join on userID.

Fusebox Transfer Verbs

Okay so you now have you Transfer factory created and you have Transfer set up, next you'll want to get data from Transfer.

Lets start with looking at what you can do with the fusebox lexicons:

• init - self explanitory
• parameter - Allows you to pass in variables to the read verb
• read - Allows you to get a single record
• list - Allows you to get a list of records
• save - Saves records
• delete - Deletes records
• populate - Populates a Transfer object with query data

For more details on Fusebox Transfer Verbs, click here

Now we know what lexicons we can use fusebox lets look at a fuseaction (in our model) using the read verb:

In this fuseaction we are asking Transfer to get the user object from the user package setup in the Transfer configuration file. We pass in a email address and password form a form this read. We then reference the result using the bean name, in this case 'checkLogin'.

So let say we call the checkLogin fuseaction from our controller:

Here we have called our checkLogin fuseaction from our model circuit, we then look at the returned bean 'checkLogin'. If it can find a userID then Transfer has found a record. We're happy with this so we setup the session variables and relocate to the user to the account area.

If the userID can't be found then there has been an error with the login so we redirect the user back to the login page.

But, where did getUserID() come from?

Well as Transfer knows that my table has a userID field, it cleverly goes of and creates getters and setters for that field (as well as any other table field you setup in the config file). We then simple call these getters and setters prefixing the tableField with get or set. How cool is that. Now we've got that clear did you notice we've not written one line of SQL?

TQL in Fusebox

With Transfer setup and working inside your Fusebox application, you can use its built in TQL query language. For more information, click here

External Links

• Setting Up Transfer for Fusebox - Original Blog post by Nick Tong
• Transfer Code - Transfer.Riaforge.org
• Transfer Presentation Recording and Sample Application
• Transfer ORM Breeze Presentation by Brian Rinaldi
• Transfer Documentation

FuseboxWiki Version 0.1.0 Developed by Josh Carrico. Please contact me with any questions/comments. Josh Carrico | FuseboxWiki.com | Fusebox Framework

FuseboxWiki by Josh Carrico is licensed under a Creative Commons Attribution-Share Alike 3.0 License.