com.sebtools Build 12 Documentation: Managing Records

Managing Records

Components that extend Records.cfc have built-in methods for managing data. This is easiest to see by example.

<table name="Contacts" labelField="ContactName" labelSingular="Contact" labelPlural="Contacts">
	<field name="ContactID" type="pk:integer" />
	<field name="ContactName" Label="Contact" type="text" Length="120" />
	<field name="ContactType" Label="Type" type="text" Length="20" />

Using the "labelSingular" and "labelPlural" attributes of the table, Records.cfc will build the following methods:

Note that these methods are created using labelSingular and labelPlural and removing and characters other than letters or numbers. So, a labelSingular of "Horse Trader" would create a "saveHorseTrader" method.

Get Record

Here is what the "getContact" method would look like if the code were actually written to file:

<cffunction name="getContact" access="public" returntype="query" output="no">
	<cfargument name="ContactID" type="numeric" required="true">
	<cfreturn variables.Manager.getRecord(variables.table,arguments)>

Note that the "ContactID" argument is already included as it is the primary key field for the table.

Get Records

<cffunction name="getContacts" access="public" returntype="query" output="no">
	<cfreturn variables.Manager.getRecords(variables.table,arguments)>

As this code passes any arguments into the "data" argument of Manager.cfc:getRecords(), each argument acts like a filter.

So, to get all contacts with a "ContactName" of "Fred Jones", you could use the following code:

<cfset qContacts = Application.Contacts.getContacts(ContactName="Fred Jones")>

Remove Record

The removeRecord method will delete a record (using a logical delete if a "DeletionMark" or "DeletionDate" field is present).

<cffunction name="removeContact" access="public" returntype="void" output="no">
	<cfargument name="ContactID" type="numeric" required="true">
	<cfset variables.Manager.removeRecord(variables.table,arguments)>

Save Record

The saveRecord method will save (insert or update) a record.

<cffunction name="saveContact" access="public" returntype="string" output="no">
	<cfinvoke method="validate#variables.methodSingular#" argumentCollection="#Arguments#" returnvariable="Arguments">
	<cfreturn variables.Manager.saveRecord(variables.table,Arguments)>

Sort Records

Sorting records only works if the table has a "Sorter" field. This will change the values of the "Sorter" field to put them in the order of list of primary key values passed in to the method.

<cffunction name="sortContacts" access="public" returntype="void" output="no">
	<cfset variables.DataMgr.saveSortOrder(variables.table,sortfield,arguments[1])>

Validate Record

Every saveRecord method internally calls a named "validate" record ("validateContact" for example). This public validation method takes the same arguments as the "saveRecord" method and returns the arguments structure. It can also change any Argument values as needed or throw an exception (via the built-in "throwError" method).

<cffunction name="validateContact" access="public" returntype="struct" output="no">
	<cfreturn Arguments>

It is recommended that the public "validateContact" method call a private validation method for each rule that it validates. So, for example, it could call a private "validatePhoneNumberAreaCode" if you wanted to verify that the area code of a phone number was valid.

Copy Record

Records has a built-in copyRecord ("copyContacts" for our current example) method. This takes the same arguments as the saveRecord method. The difference is that it will copy a record based on the primary key values passed in and only change values based on the other arguments passed in.

The copyRecord method will also create copies of any files referenced by the copied record and store those values appropriately.

<cffunction name="copyContact" access="public" returntype="void" output="no">
	<cfset variables.Manager.copyContact(variables.table,arguments)>