Formatting/Changing Data before Loading

Basic formatting methods

APPLICABLE TO: Grid, TreeGrid, Tree, Combo, Scheduler, DataView, Chart, Form

When you need to update values which were returned from a database table or set some specific formatting before sending data to the client side, you should use the beforeRender event handler.

Common usage

<cfinclude template="../config.cfm">
<cffunction name="color_rows">
    <cfargument name="row">
    <cfif ARGUMENTS.row.get_index() mod 2>
        <cfset ARGUMENTS.row.set_row_color("red")>
    </cfif>     
</cffunction>
<cfset grid = CreateObject(
    "component",
    "dhtmlxConnectors.GridConnector").init("#datasource#","MySQL")>
<cfset grid.event.attach("beforeRender",color_rows)>
<cfset grid.render_table("grid50000","item_id","item_nm,item_cd")>

color_rows function sets colors for rows subject to their indices
during the data generation, for each record outputted for the client side the beforeRender event will be executed, i.e. color_rows function will be called for each record
row is an instance of GridDataItem object related to the current record

Data formatting

APPLICABLE TO: Grid, TreeGrid, Tree, Combo, Scheduler, DataView, Chart, Form

<!--- render field as details link --->
<cffunction name="formatting"> 
  <cfargument name="row">
  <cfset var data = ARGUMENTS.row.get_value("some_field")>
  <cfset ARGUMENTS.row.set_value(
    "some_field",
    "<a href='details.cfm?id=#data#'>Details</a>"
  )>
  <!--- formatting date field --->      
  <cfset data = ARGUMENTS.row.get_value("other_field")>
  <cfset ARGUMENTS.row.set_value(
    "other_field",
    DateFormat(lsParseDateTime(data),
    "mm-dd-yyyy")
  )>    
</cffunction>
<cfset grid = CreateObject(
"component",
"dhtmlxConnectors.GridConnector").init("#datasource#","MySQL"
)>
<cfset grid.event.attach("beforeRender",formatting)>

the get_value and set_value methods allow you to get or set value of any field related to the record (it doesn't affect actual values in DB)
if an alias was used during data configuration, you need to use it instead of real db field name as the first parameter of the get/set command.

Using extra fields

APPLICABLE TO: Grid, TreeGrid, Tree, Combo, Scheduler, DataView, Chart, Form

More complex formatting rules can be defined by using extra fields during the configuration.

<cffunction name="formatting"> 
    <cfargument name="row">
    <!--- set row color --->
    <cfset ARGUMENTS.row.set_row_color(ARGUMENTS.row.get_value("color"))>
    <!--- save in userdata --->
    <cfset ARGUMENTS.row.set_userdata("some_data",ARGUMENTS.row.get_value("count"))>
</cffunction>
<cfset grid = CreateObject(
"component",
"dhtmlxConnectors.GridConnector").init("#datasource#","MySQL"
)>
<cfset grid.event.attach("beforeRender",formatting)>
<cfset grid.render_table("some_table","id","name,price","color,count")>

field color isn't outputted to the client side, but used to define the property of a row.
during the update/insert operation only the 'name' and 'price' columns can be changed, the 'color' one will stay untouched.
the 'count' field will be sent to the client side as userdata of the row, and it will be possible to access it on the client side through the related data.

Tree/TreeGrid specificity

APPLICABLE TO: Tree, TreeGrid

TreeGrid provides TreeGridDataItem and Tree provides TreeDataItem as the input parameter of the beforeRender event handler. Both of them support base operations and a few specific ones.

<cffunction name="custom_format"> 
    <cfargument name="item">
        <cfif ARGUMENTS.item.get_value("complete") gt 75>
        <cfset ARGUMENTS.item.set_check_state(1)>
    </cfif>   
        <cfif ARGUMENTS.item.get_value("duration") gt 10>
        <cfset ARGUMENTS.item.set_image("true.gif")>
        <cfelse>
                <cfset ARGUMENTS.item.set_image("false.gif")>
    </cfif>      
</cffunction>
 
<cfset tree.event.attach("beforeRender",custom_format)>

the set_image method allows setting an image of a tree element (for treegrid it accepts the only parameter, while for tree it can be 3 different images for 3 states of a tree's item)
the set_check method exists only in TreeDataItem object and allows setting the state of the related checkbox (tree needs having checkboxes enabled in js. configuration code as well)
the beforeRender event can be used in dynamic Tree and TreeGrid to define which elements of hierarchy are branches and which ones are leafs (see details here).