com.sebtools Build 12 Documentation: RecordObject

RecordObject

RecordObject is a lightweight object that uses Records internally and can be created and accessed via the Records component.

Create a RecordObject

A RecordObject can either be instantiated by calling the "RecordObject" method of your Records component. This takes a "Record" argument and a fields argument.

"Record" Argument

The "Records" argument can actually take several different data types:

"Fields" Argument

The "Fields" argument (optional) is simply a list of fields that you want to ensure are available in your object. Don't worry if you need more later, RecordObject can always get the values it needs from the Records component at any time. this can just save a bit of performance to get all of the ones that you know you need up front.

Examples:

<cfset oEmployee = Application.Employees.RecordObject(1)>
<cfset oEmployee = Application.Employees.RecordObject(1,"EmployeeID,Region")>
<cfset oEmployee = Application.Employees.RecordObject(qEmployee)>
<cfset oEmployee = Application.Employees.RecordObject(oEmployee)>

Instantiating RecordObject Directly

RecordObject can either be instantiated directly by calling the "init" method of com.sebtools.RecordObject. The only difference in the arguments here is that the first argument must be "Service" (The Records component for this object), and the rest of the arguments will match those of the "RecordObject" method of the Records component.

Getting Data

To get data from the RecordObject, simply call the "get" method and pass in the name of the field for which you want data.

You can also call the "getInstance" method to see all of the data currently loaded into the object.

<cfset FirstName = oEmployee.get("FirstName")>

If that field is not available within the object, then it will get the data from the Records component.

Determining if Object is New

RecordObject has a "isNewRecord" to determine if the RecordObject is representing a new record or one that already exists. If the record is new, then it will return "true". If the record already exists, then it will return "false".

This is a very efficient way to determine if a record is new or existing.

Validating Data

RecordObject has two methods available for data validation.

isValidRecord

The isValidRecord method will return a boolean to indicate if the arguments passed in are valid. It will also use the existing data in the check.

<cfset isOK = oEmployee.isValidRecord(BirthDate="2001-01-01",Position="Manager")>

validate

The isValidRecord method internally calls the "validate" method, which itself simply calls the appropriate "validate" method of the Records component ("validateEmployee" for example), which return a structure of data if all went well and an exception if the validation had an unresolvable problem.

Saving

The "save" method of RecordObject will alter the data in the object itself as well as write the data changes back to the database.

<cfset oEmployee.save(BirthDate="2001-01-01",Position="Manager")>

Load Fields

If at any time you want to make sure that some field values are available within RecordObject, you can call the "loadFields" method and pass in a list of fields that you want available. This isn't necessary as the "get" method will get them if they are unavailable, but it can be good for performance if you know several fields that will be needed. This will allow them all to be gotten from one query instead of needing a separate query for each field.

Method Returns

Most methods will return the RecordObject itself, but some will not. Here is a detailing of the public methods of RecordObject and what they return.

Using RecordObject

Though RecordObject likely has many uses, there is one scenario in particular that is worth pointing out. That is the ability to use RecordObject on an incoming value. For example, this "getEmployeeRegions" method:

<cffunction name="getEmployeeRegions" access="public" returntype="query" output="no">
	<cfargument name="EmployeeID" type="string" required="true">
	
	<cfset var qEmployee = getEmployee(EmployeeID=Arguments.EmployeeID,fieldlist="EmployeeID,Zones,RegionExceptions,Permissions")>
	
	<!--- Some logic here using qEmployee --->
	
	<cfreturn qRegions>
</cffunction>

This approach works very well. The only problem is that if the code that calls "getEmployeeRegions" already called "getEmployee" then your are running that query twice when perhaps you didn't need to and you are making it harder to test as any tests need to have the data for the employee in the database before the test can be executed. Here is the method again using RecordObject:

<cffunction name="getEmployeeRegions" access="public" returntype="query" output="no">
	<cfargument name="EmployeeID" type="any" required="true">
	
	<cfset var oEmployee = RecordObject(Record=Arguments.EmployeeID,fields="EmployeeID,Zones,RegionExceptions,Permissions")>
	
	<!--- Some logic here using qEmployee --->
	
	<cfreturn qRegions>
</cffunction>

The remainder of the code in your method will have to get values using oEmployee.get("MyFieldName") instead of qEmployee.MyFieldName. For this, however, the calling code can pass in an EmployeeID value as before or it can pass in an already created RecordObject (or a query or a structure) instead. The RecordObject could even have been populated with fake data that never went to the database for testing.