Configuration Options – Column Formatting

So far, we have seen how to enable filters, footers, paging, print, preferences and more. In this section let’s look at a very common requirement, one that of formatting column values. Depending on your situation, there are numerous ways to customize the content of the cells. We provide you with a rich API that allows you to pretty much customize every single grid cell.

There are a number of options that the grid exposes to let you control the content of each cell:

The Header cells:

The default text of the header cell maps to the headerText of the column configuration. If nothing is specified, it uses the dataField of the column.
If you want to customize the content of the header cell, you can use a custom headerRenderer.

The Footer Cells:

The default text of the footer is calculated on basis of the following logic:

First we check to see if a footerLabelFunction2 is specified on the column. If so, we use it.
Second, we check to see if there is a footerLabelFunction specified on the column. If so, we use it.
Finally, if neither of these is specified, we use a default footer label function, which performs the following logic:

Checks to see the value of the columns footerOperation. The valid values for this property are sum, min, max, count and average. On basis of this, it computes the value.
It calls toFixed method passing in the footerOperationPrecision value to give it the appropriate number of decimal places
If there is a footerFormater specified, it calls the format method of the footerFormatter passing in the value and displays the result.
If there is a footerLabel specified, it will concatenate the value of the footer label to the result of the calculated value in step 3.

If the above customization logic is not enough, there is always a mechanism to specify a custom footer renderer.

The Data Cells: For the most part, this is where most of the requirements come in for customization. Based upon your needs, there are several different methods that the grid exposes for you to achieve customization of your data cells

If there is a linktext property specified on the column, this function returns that.
If the DataGridColumn or its DataGrid control has a non-null <code>labelFunction</code> property, it applies the function to the data object.
If the DataGridColumn or its DataGrid control has a non-null <code>labelFunction2</code>property, it applies the function to the data object.
Otherwise, the method extracts the contents of the field specified by the

<code>dataField</code> property, or gets the string value of the data object.

If the method cannot convert the parameter to a String, it returns a single space
Finally, if none of the above works for you, you can use what we call a custom item renderer. This is especially useful when there is custom functionality that you want to associate with each cell in the grid.

Now that all of this is said, let’s look at what the typical markup for each of the above options looks like:

configuration: '<grid id="grid" enablePrint="true" enablePreferencePersistence="true" enableExport="true" forcePagerRow="true" pageSize="50" enableFilters="true" enableFooters="true" >' +

' <level>' +

' <columns>' +

' <column dataField="id" headerText="ID" filterControl="TextInput" filterOperation="Contains" footerLabel="Sum: " footerOperation="sum" footerOperationPrecision="2"/>' +

' <column dataField="type" headerText="Type" filterControl="TextInput" filterOperation="Contains" footerLabelFunction="myCompanyNameSpace.customFooterFunction"/>' +

' <column dataField="" headerText="Label Function Example" filterControl="TextInput" filterOperation="Contains" labelFunction="myCompanyNameSpace.labelFunctionExample"/>' +

' <column dataField="" headerText="Label Function 2 Example" filterControl="TextInput" filterOperation="Contains" labelFunction2="myCompanyNameSpace.labelFunction2Example"/>' +

' <column dataField="active" headerText="Item Renderer Example" headerRenderer="myCompanyNameSpace.CheckBoxHeaderRenderer" filterControl="TextInput" filterOperation="Contains" itemRenderer="myCompanyNameSpace.CheckBoxRenderer"/>' +

' </columns>' +

' </level>' +

' ' +

' </grid>',

You will notice that we have highlighted a few important items here:

For labelFunction="myCompanyNameSpace.labelFunctionExample", let’s look at the actual label function. In this method, we get the item being rendered, and the column being renderered.

myCompanyNameSpace.labelFunctionExample = function (item, column) {

var html = "<b> Column:"+column.getHeaderText()+" : </b> Item: " + item.type ;

return html;

};

For labelFunction2="myCompanyNameSpace.labelFunction2Example", let’s look at the actual label function – the key difference here is that we also get the cell being rendered. Each cell has a rowInfo object. The rowInfo object associated with this cell. This cell should be within the cells collection of this rowInfo object. Each cell has a corresponding rowinfo object. The rowInfo, in turn has a rowPositionInfo object. The key difference between these two objects is that there are only as many rowInfo objects as there visible rows on the page. RowPositionInfo objects on the other hand, there are as many of these as there are total items in the data provider.

myCompanyNameSpace.labelFunction2Example = function (item, column, cell) {

var html = "<b> Column:"+column.getHeaderText()+" : </b> Item: " + item.type + ", cell: " + cell.rowInfo.rowPositionInfo.getRowIndex();

return html;

};

Finally, if specifying custom html is not enough for your needs, you can use itemRenderers, which is a very powerful concept. Item Renderers are basically custom JavaScript classes, that wrap regular dom elements and sit inside the various cells of the grid. Every UI Element in the HTMLTreeGrid extends from flexiciousNmsp.UIComponent class. This is nothing but a thin wrapper that encapsulates a domElement, and provides various utility methods that allow for things like sizing, positioning, validation and invalidation, event management and display list hierarchy. In fact, even the HTMLTreeGrid class (FlexDataGrid) class eventually inherits from UIComponent. When you define your own item renderer, you have to inherit it from the flexiciousNmsp.UIComponent class. We use prototype based inheritance. The key about item renderers is that they should expose a method called setData. This method is called when the grid instantiates an itemRenderer and prepares it for display. Finally, another important thing to keep in mind is that each item renderer gets a parent property. This points to the parent FlexDataGridCell object. The actual type is FlexDataGridDataCell for itemRenderers, FlexDataGridHeaderCell for headerRenders, FlexDataGridFilterCell for filterRenderers, and FlexDataGridFooterCell for footerRenderers. Let’s take a look at what a simple item renderer looks like:

/**

* Flexicious

(function(window)

{

"use strict";

var CheckBoxRenderer, uiUtil = flexiciousNmsp.UIUtils, flxConstants = flexiciousNmsp.Constants;

/**

* A CheckBoxRenderer is a custom item renderer, that defines how to use custom cells with logic that you can control

* @constructor

* @namespace flexiciousNmsp

* @extends UIComponent

CheckBoxRenderer=function(){

//make sure to call constructor

flexiciousNmsp.UIComponent.apply(this,["input"]);//second parameter is the tag name for the dom element.

this.domElement.type = "checkbox"; //so our input element becomes a checkbox;

/**

* This is a getter/setter for the data property. When the cell is created, it belongs to a row

* The data property points to the item in the grids dataprovider that is being rendered by this cell.

* @type {*}

this.data=null;

//the add evt listener will basically proxy all DomEvents to your code to handle.

this.addEventListener(this,flxConstants.EVENT_CHANGE,this.onChange);

};

myCompanyNameSpace.CheckBoxRenderer = CheckBoxRenderer; //add to name space

CheckBoxRenderer.prototype = new flexiciousNmsp.UIComponent(); //setup hierarchy

CheckBoxRenderer.prototype.typeName = CheckBoxRenderer.typeName = 'CheckBoxRenderer';//for quick inspection

CheckBoxRenderer.prototype.getClassNames=function(){

return ["CheckBoxRenderer","UIComponent"]; //this is a mechanism to replicate the "is" and "as" keywords of most other OO programming languages

};

/**

* This is important, because the grid looks for a "setData" method on the renderer.

* In here, we intercept the call to setData, and inject our logic to populate the text input.

* @param val

CheckBoxRenderer.prototype.setData=function(val){

flexiciousNmsp.UIComponent.prototype.setData.apply(this,[val]);

var cell = this.parent; //this is an instance of FlexDataGridDataCell (For data rows)

var column = cell.getColumn();//this is an instance of FlexDataGridColumn.

this.domElement.checked=this.data[column.getDataField()];

};

/**

* This event is dispatched when the user clicks on the icon. The event is actually a flexicious event, and has a trigger event

* property that points back to the original domEvent.

* @param event

CheckBoxRenderer.prototype.onChange=function(evt){

//in the renderer, you have the handle to the cell that the renderer belongs to, via the this.parent property that you inherit from flexiciousNmsp.UIComponent.

var cell = this.parent; //this is an instance of FlexDataGridDataCell (For data rows)

var column = cell.getColumn();//this is an instance of FlexDataGridColumn.

this.data[column.getDataField()]=this.domElement.checked;//we use the dom element to wire back the value to the data object.

};

//This sets the inner html, and grid will try to set it. Since we are an input field, IE 8 will complain. So we ignore it since we dont need it anyway.

CheckBoxRenderer.prototype.setText=function(val){

};

}(window));

Similar to the above, the same concept is extended to header renderers (and footer, filter, pager as well as nextLevelRenderers). So, now that all of that is done, let’s take a quick look at the final markup for this page, and generated output:

<!doctype html>

<head>

<title>Simple</title>

var myCompanyNameSpace = {};

myCompanyNameSpace.labelFunctionExample = function (item, column) {

var html = "<b> Column:"+column.getHeaderText()+" : </b> Item: " + item.type ;

return html;

};

myCompanyNameSpace.labelFunction2Example = function (item, column, cell) {

var html = "<b> Column:"+column.getHeaderText()+" : </b> Item: " + item.type + ", cell: " + cell.rowInfo.rowPositionInfo.getRowIndex();

return html;

};

myCompanyNameSpace.customFooterFunction = function () {

var html = "<div> Look Mommy, custom footer!</div>";

return html;

};

/**

* Flexicious

(function(window)

{

"use strict";

var CheckBoxRenderer, uiUtil = flexiciousNmsp.UIUtils, flxConstants = flexiciousNmsp.Constants;

/**

* A CheckBoxRenderer is a custom item renderer, that defines how to use custom cells with logic that you can control

* @constructor

* @namespace flexiciousNmsp

* @extends UIComponent

CheckBoxRenderer=function(){

//make sure to call constructor

flexiciousNmsp.UIComponent.apply(this,["input"]);//second parameter is the tag name for the dom element.

this.domElement.type = "checkbox"; //so our input element becomes a checkbox;

/**

* This is a getter/setter for the data property. When the cell is created, it belongs to a row

* The data property points to the item in the grids dataprovider that is being rendered by this cell.

* @type {*}

this.data=null;

//the add evt listener will basically proxy all DomEvents to your code to handle.

this.addEventListener(this,flxConstants.EVENT_CHANGE,this.onChange);

};

myCompanyNameSpace.CheckBoxRenderer = CheckBoxRenderer; //add to name space

CheckBoxRenderer.prototype = new flexiciousNmsp.UIComponent(); //setup hierarchy

CheckBoxRenderer.prototype.typeName = CheckBoxRenderer.typeName = 'CheckBoxRenderer';//for quick inspection

CheckBoxRenderer.prototype.getClassNames=function(){

return ["CheckBoxRenderer","UIComponent"]; //this is a mechanism to replicate the "is" and "as" keywords of most other OO programming languages

};

/**

* This is important, because the grid looks for a "setData" method on the renderer.

* In here, we intercept the call to setData, and inject our logic to populate the text input.

* @param val

CheckBoxRenderer.prototype.setData=function(val){

flexiciousNmsp.UIComponent.prototype.setData.apply(this,[val]);

var cell = this.parent; //this is an instance of FlexDataGridDataCell (For data rows)

var column = cell.getColumn();//this is an instance of FlexDataGridColumn.

this.domElement.checked=this.data[column.getDataField()];

};

/**

* This event is dispatched when the user clicks on the icon. The event is actually a flexicious event, and has a trigger event

* property that points back to the original domEvent.

* @param event

CheckBoxRenderer.prototype.onChange=function(evt){

//in the renderer, you have the handle to the cell that the renderer belongs to, via the this.parent property that you inherit from flexiciousNmsp.UIComponent.

var cell = this.parent; //this is an instance of FlexDataGridDataCell (For data rows)

var column = cell.getColumn();//this is an instance of FlexDataGridColumn.

this.data[column.getDataField()]=this.domElement.checked;//we use the dom element to wire back the value to the data object.

};

//This sets the inner html, and grid will try to set it. Since we are an input field, IE 8 will complain. So we ignore it since we dont need it anyway.

CheckBoxRenderer.prototype.setText=function(val){

};

}(window));

/**

* Flexicious

(function(window)

{

"use strict";

var CheckBoxHeaderRenderer, uiUtil = flexiciousNmsp.UIUtils, flxConstants = flexiciousNmsp.Constants;

/**

* A CheckBoxHeaderRenderer is a custom item renderer, that you can use in a header cell. In this case, we customize the header

* so that instead of showing a header label, we show a checkbox that switches the dataField flag on all items.

* @constructor

* @namespace flexiciousNmsp

* @extends UIComponent

CheckBoxHeaderRenderer=function(){

//make sure to call constructor

flexiciousNmsp.UIComponent.apply(this,["input"]);//second parameter is the tag name for the dom element.

this.domElement.type = "checkbox"; //so our input element becomes a checkbox;

this.domElement.checked=true;

//the add event listener will basically proxy all DomEvents to your code to handle.

this.addEventListener(this,flxConstants.EVENT_CHANGE,this.onChange);

};

myCompanyNameSpace.CheckBoxHeaderRenderer = CheckBoxHeaderRenderer; //add to name space

CheckBoxHeaderRenderer.prototype = new flexiciousNmsp.UIComponent(); //setup hierarchy

CheckBoxHeaderRenderer.prototype.typeName = CheckBoxHeaderRenderer.typeName = 'CheckBoxHeaderRenderer';//for quick inspection

CheckBoxHeaderRenderer.prototype.getClassNames=function(){

return ["CheckBoxHeaderRenderer","UIComponent"]; //this is a mechanism to replicate the "is" and "as" keywords of most other OO programming languages

};

/**

* This event is dispatched when the user clicks on the icon. The event is actually a flexicious event, and has a trigger event

* property that points back to the original domEvent.

* @param event

CheckBoxHeaderRenderer.prototype.onChange=function(event){

//in the renderer, you have the handle to the cell that the renderer belongs to, via the this.parent property that you inherit from flexiciousNmsp.UIComponent.

var cell = this.parent; //this is an instance of FlexDataGridDataCell (For data rows)

var column = cell.getColumn();//this is an instance of FlexDataGridColumn.

//var dp = cell.level.getGrid().getDataProvider();//this is a pointer back to the grid and its dataprovider.

var dp=this.data;//for header cells, specifically in case of nested grids, the data property is a pointer back to the top level array, or the children array

if(this.data.hasOwnProperty("deals")){

//this means we are at a inner level checkbox header

dp=this.data.deals;

}

//based upon which level this renderer appears.

for (var i=0;i<dp.length;i++){

dp[i][column.getDataField()] = this.domElement.checked;

}

column.level.grid.refreshCells();//this will re-render the cells.

};

//This sets the inner html, and grid will try to set it. Since we are an input field, IE 8 will complain. So we ignore it since we dont need it anyway.

CheckBoxHeaderRenderer.prototype.setText=function(val){

};

}(window));

$(document).ready(function(){

var grid = new flexiciousNmsp.FlexDataGrid(document.getElementById("gridContainer"),

{

configuration: '<grid id="grid" enablePrint="true" enablePreferencePersistence="true" enableExport="true" forcePagerRow="true" pageSize="50" enableFilters="true" enableFooters="true" >' +

' <level>' +

' <columns>' +

' <column dataField="id" headerText="ID" filterControl="TextInput" filterOperation="Contains" footerLabel="Sum: " footerOperation="sum" footerOperationPrecision="2"/>' +

' <column dataField="type" headerText="Type" filterControl="TextInput" filterOperation="Contains" footerLabelFunction="myCompanyNameSpace.customFooterFunction"/>' +

' <column dataField="" headerText="Label Function Example" filterControl="TextInput" filterOperation="Contains" labelFunction="myCompanyNameSpace.labelFunctionExample"/>' +

' <column dataField="" headerText="Label Function 2 Example" filterControl="TextInput" filterOperation="Contains" labelFunction2="myCompanyNameSpace.labelFunction2Example"/>' +

' </columns>' +

' </level>' +

' ' +

' </grid>',

dataProvider: [

{ "id": "5001", "type": "None", "active" : true },

{ "id": "5002", "type": "Glazed" , "active" : true},

{ "id": "5005", "type": "Sugar" , "active" : true},

{ "id": "5007", "type": "Powdered Sugar" , "active" : false},

{ "id": "5006", "type": "Chocolate with Sprinkles" , "active" : true},

{ "id": "5003", "type": "Chocolate" , "active" : false},

{ "id": "5004", "type": "Maple" , "active" : true}

]

});

</script>

</head>

<body>

</div>

</body>

</html>