XGrid

XGrid is an AJAX toolkit library (API) that can be used to display tabular data. It can be used to construct multi-functional, high-performance grids. XML data is the basis of the content in an XGrid.
XGrid enables the following functionality in a table:

Support for multiple field types in an Xgrid, such that the fields in a column can be of the type input, output, checkbox, password, textarea, or image (as a thumbnail or composite icon).
Support for the zoom feature for column cells of the type input, output, textarea, and image. The lookup button appears when focus is set on the cell associated with the zoom feature.
Support for the calendar control feature for column fields of the type input, for which the data type specified is date.
Availability of context menu on the column header that offers additional options.
Availability of column chooser for hiding and displaying columns at runtime.
Resizing of columns by dragging the edge of the header cells.
Repositioning of columns by dragging the header cells.
Freezing of one or more columns such that the columns remain fixed when the horizontal scroll bar is used. Frozen columns are always positioned in front of other non-frozen columns.
Freezing of one or more rows such that the rows remain fixed when the vertical scroll bar is used. Frozen rows are always positioned on top of other non-frozen rows.
Sorting of rows according to the data type of the columns in the table.
Navigation through cells in the table using keyboard keys such as the arrow keys and the Home, End, and Tab keys.
Selection of multiple rows using the Checkrow column.

The XGrid library can handle large amounts of data, and decreasing startup time and providing a smoother scrolling behavior. To achieve and maintain its superior performance, observe the following guidelines:

Avoid a combination of large number of rows (more than 250) and columns for smoother scrolling. Also, avoid frozen columns if possible.
Use images only where necessary to decrease startup time. Also, if you want to use images larger than the standard row height and do not want to display them as thumbnails, set the fixedRowHeight property of the XGrid to False.
Avoid adding complex scripts for the onbeforedatabind event (fired for each cell when rendered) or the onbeforerowdatabind event (fired for each row when rendered), as it reduces the startup time and affects scrolling behavior.
Avoid selecting a large number of rows (more than 10,000) using the onrowcheck event and sorting a column containing a large number of rows (more than 5000) as it also affects the performance.

Syntax

HTML	< div cordysType="wcp.library.ui.XGrid" id=xGridId xpathRowData = "" xpathBusinessObject = ""> <div id=columnId ref="project">Project</div> <div id=columnId ref="description">Description</div> ... </div>
Scripting	application.addType(xgridId, "wcp.library.ui.XGrid")

To dynamically add and initialize this component, you can use the initializeHTMLElements or addType methods of the Application object.

Properties, Methods, and Events in XGrid

The various properties, methods, and events that are defined for the XGrid component are as follows.
The following table describes the attributes that are available at the XGrid level.

Table 1. Attributes used for XGrid
Attribute	Property	Description
fixedRowHeight	n/a	Boolean with default value as true. If not specified, it is automatically set by the XGrid. If you need to display images of variable height in rows, the XGrid must be enabled to show rows of variable heights. In such cases, you can set this attribute to False. If all images have the same height (like composite images), you can set this attribute to True. This will also increase the startup performance of XGrids that have large numbers of rows.
freezableColumns	n/a	Boolean with default value as true. Defines whether columns can be frozen.
freezableRows	n/a	Boolean with default value as true. Defines whether rows can be frozen.
hideableColumns	n/a	Boolean with default value as true. Defines whether columns can be hidden.
id	id	String; required, read only. Unique identifier of the XGrid.
movableColumns	n/a	Boolean with default value as true. Defines whether columns can be moved.
resizableColumns	n/a	Boolean with default value as true. Defines whether columns can be resized.
shadeClasses	shadeClasses	String that defines the classes to be used to shading the Xgrid. The classes must be separated by spaces. For example, shadeClasses='light lightmedium'.
sortable	n/a	Boolean with default value as true. Defines whether rows can be sorted.
useCheckboxes	n/a	Boolean with default value as true. Shows or hides the Checkbox column, which can be used to select multiple rows.
useRowCache	n/a	Boolean with default value as true. By default, the HTML of a row is cached, for optimal performance. This makes scrolling of large datasets smoother. However, if you have a table that contains time dependent data, you might want to set this to false. For example, say when the data is older than 15 minutes, the cell should appear in red. An auto refresh of the data can handle this, but the row cache prevents the display of new data. In this situation, set useRowCache=false.
xpathBusinessObject	xpathBusinessObject	Required, read only. Sets the XPath from the rowData to the businessObject.
xpathRowData	xpathRowData	Required, read only. Sets the XPath from the dataNode to the row data elements. The rowData, the top node of a row, is the repeating level in the XML data.

The following table describes the attributes that are applicable to columns in an XGrid.

Table 2. Attributes used for columns in XGrid
Attribute	Description
class	String. Optional. Refers to the className of a column. The className applies to all cells in the column. You can use this attribute to modify all cells in a column; for example, you can specify the alignment of cells in a column.
dataType	String. Optional attribute with default value as string. Defines the data type of a column. Possible values are string, integer, float, double, decimal, amount, date, hexbinary, base64binary, and anyuri. The data type is useful for sorting rows. The data type does not need to be set for a column that has "image" as the fieldType.
dropdownId	String. A column can be of the dropdown fieldType. In that case this attribute is mandatory and links to the id of the dropdown to be shown in the cells of this column. The dropdown is of the type: <div cordysType="wcp.library.ui.Dopdown"id="dropdownId">...</div>.
falseValue	String. The default value is false. A column can be of the checkbox fieldType, in which case this field is mandatory and contains a value for an unchecked checkbox. Often this is 0 or false.
fieldType	String. Optional attribute with default value as input. Defines the field type for cells in a column. Possible values are input, output, checkbox, password, dropdown, textarea, and image.
id	String. Optional. Unique identifier of a column.
<label>	String. Optional. Not an attribute, but the innerHTML of the <div> of the column. This text is displayed in the header cell of the column.
ref	String. Required. XPath to the business element in the XML node with respect to the business object. This data node populates the data in the cell.
thumbnail	Boolean. Optional attribute with default value as false. This attribute is applicable when the fieldType is image. It denotes whether an image will be displayed full-sized or as a thumbnail. Set to True to display images as thumbnails, in which case images are resized to standard row height. This attribute can be used only for non-composite images. If composite images are used, the iconSize property must also be set.
iconSize	Optional. String that denotes the size of icons in a Column. Possible values are: small: Default. Size of column icons is set to small. mid: Size of column icons is set to medium. big: Size of column icons is set to big.
title	String. Optional. This string is shown as a tooltip in the header cell of the column.
trueValue	String. The default value is true. This attribute is applicable when the fieldType of a column is checkbox. In this case, the field is mandatory and is set to true for a selected check box. Generally, the value is 1 or true.
width	Integer. Optional. Sets the default width of a column in pixels (px) only.
zoomField	String. Applicable to cells that have a zoom option. The zoomField is available as a parameter in the onzoom event. The zoom field usually has the id of the field on the zoom page that has the data to be returned.
zoomUrl	String. Applicable to cells that have a zoom option. The zoomUrl is available as a parameter in the onzoom event. The zoom URL usually has the URL of the page you zoom to.
Table 3. Methods used with XGrid
Method	Description
addColumn(id, ref, label, fieldType, dataType, misc1, misc2, bApplyPreferenceState)	Dynamically creates an extra column.
bindData(dataNode)	Binds the passed data node, resulting in the rendering of this data in the XGrid.
blur()	Removes the focus from the selected cell and row.
checkAllRows(bSelect)	Checks or clears all rows. To be able to use this method, you must set the useCheckboxes property to true. For each row an onrowcheck event is fired.
clearData()	Clears all data from an XGrid.
deleteCheckedRows()	Removes all checked rows and deletes the corresponding rowData. This method should be used only for non-transactional data. This method is DEPRECATED. Use xgrid.getCheckedRows().remove() instead.
disable()	Disables the entire XGrid.
enable()	Enables the entire XGrid.
freezeCheckedRows(bSelect)	Freezes or unfreezes the selected rows depending on bSelect. bSelect: Required. Boolean. Thie method is DEPRECATED. Use xgrid.getCheckedRows().freeze() to freeze all checked rows and xgrid.getCheckedRows().unfreeze() to unfreeze them.
getCell(column, iRow)	Returns the cell object for the specified column and row. column: Required. Refers to the id (string) or index (index) of the column. The index of the first column is 0. iRow: Refers to the rowData, HTML of the row, or the row index. The index of the first row is 1.
getCheckedRows()	Returns an array containing row objects of all checked rows. The remove(), freeze(), and unfreeze() methods can be used to handle all objects in the array.
getColumn(column)	Returns the column object of the specified column. column: Required. Refers to the id (string) or index (index) of the column. The index of the first column is 0.
getData()	Returns the XML data associated with the XGrid. This data is linked to the XGrid using the bindData() method.
getFirstRow()	Returns a rowObject of the first row of the XGrid.
getFreezableColumns()	Returns the freezableColumns property, which determines whether columns can be frozen or not.
getFreezableRows()	Returns the freezableRows property, which determines whether rows can be frozen or not.
getHideableColumns()	Returns the hideableColumns property, which determines whether columns can be hidden or not.
getLastRow()	Returns the rowObject of the last row of the XGrid.
getMovableColumns()	Returns the movableColumns property, which determines whether columns can be moved or swapped, or not.
getNextRow(oRow)	Returns the next row object with respect to the passed row object.
getNumberOf Rows()	Returns an integer, which gives the total number of rows in the XGrid.
getNumberOfVisibleRows()	Returns an integer, which gives the number of rows visible to the user (without scrolling).
getPreviousRow(oRow)	Returns the previous row object with respect to the passed row object.
getResizableColumns()	Returns the resizableColumns property, which determines whether columns can be resized or not.
getRow(iRow)	Returns the row object of the passed row. iRow can be the rowData, the HTML of the row or the row index. The index of the first row is 1.
getSelectedRow()	Returns a rowObject from the highlighted row selected by the user.
getSortable()	Returns the sortable property, which determines whether rows can be sorted or not.
getSortedColumn()	Returns an object of the last sorted column. The object has two properties: id: String. The identifier of the column. sortOrder: ascending or descending. Both are null when no column is sorted.
getUseCheckboxes()	Returns boolean that refers to the useCheckboxes property.
getUseRowCache()	Boolean that indicates if the rendered row data is cached.
hide()	Hides the entire XGrid.
hideFooter()	Hides the footer area of the XGrid.
hideHeader()	Hides the header area of the XGrid.
insertRow(newRowData)	Prepares a node for the XGrid. The node itself is not automatically added to the XML of the XGrid. The rowData must have the same parent as all the other rowData nodes.
refresh()	Refreshes the rows of the XGrid. The rows are recreated based on the available data. The scroll position is retained.
setFreezableColumns(bSelect)	Sets the freezableColumns property, which determines whether columns can be frozen or not. bSelect: Required. Boolean.
setFreezableRows(bSelect)	Sets the freezeableRows property, which determines whether rows can be frozen or not. bSelect: Required. Boolean.
setHideableColumns(bSelect)	Sets the hideableColumns property, which determines whether columns can be hidden or not. bSelect: Boolean.
setMovableColumns(bSelect)	Sets the movableColumns property, which determines whether columns can be moved or swapped, or not. bSelect: Required. Boolean.
setResizableColumns(bSelect)	Sets the resizableColumns property, which determines whether columns can be resized or not. bSelect: Required. Boolean.
setShadeClasses(sShadeClasses)	Sets the shadeClasses. sShadeClasses: String that specifies the classes that must be applied to shade the Xgrid. The classes must be separated by spaces. For example, shadeClasses='light lightmedium'.
setSortable(bSelect)	Sets the sortable property, which determines whether rows can be sorted or not. bSelect: Required. Boolean.
setUseCheckboxes(bSelect)	Sets the useCheckboxes property. Adds or removes the check boxes column. bSelect: Required. Boolean.
setUseRowCache(bSelect)	Boolean that indicates if the rendered row data must be cached. bSelect: Required. Boolean.
show()	Shows a (hidden) XGrid.
showFooter()	Displays (the previously hidden) footer area of the XGrid.
showHeader()	Displays (the previously hidden) header of the XGrid.

The following table describes the events that are applicable to the XGrid.

Table 4. Events used with XGrid
Event	Description
onaftersort	Executed after rows have been sorted.
onbeforesort	Executed before rows have been sorted.
onbeforerowdatabind	Executed before a row is rendered.
ondblclick	Executed when you double-click a row.
oncontextmenu	Executed when you right-click a cell.
onrowcheck	Executed when a row is (un)checked. A row can be checked by selecting its corresponding check row checkbox, selecting the check all rows checkbox in the header, or using the checkAllRows() method.
onrowhover	Executed when you hover on (mouse over) a row. The event properties of this event are similar to those of the ondblclick event.
onrowselect	Executed when a row is selected.
onrowunhover	Executed when you stop the mouse over action on a row. The event properties of this event are similar to those of the ondblclick event.

The following table describes the events that are applicable to cells in an XGrid.

Table 5. Events used for cells in XGrid
Event	Description
onbeforedatabind	Executed just before the value of a cell is written.
onblur	Executed when a cell loses focus.
oncalendarselect	Executed when you click the calendar icon in a column of the date dataType. Here a calendar control can be displayed. The calendar icon is displayed only when the oncalendarselect event has been defined.
onchange	Executed when the content of a cell is changed. The value of the dataNode corresponding to the edited cell, is also updated by the XGrid. If the dataNode does not exist, it is created and its value updated after the onchange event has been executed. This allows you to create a dataNode.
onfocus	Executed when a cell receives focus.
onzoom	Executed when you click the zoom icon in a cell. The zoom icon is displayed only when a zoom event is defined.

Remarks

You can observe from the syntax that columns are defined using the <div> nodes at design time. At runtime, these are replaced by the actual XGrid HTML structure and therefore references made to these nodes are lost. The XGrid is a <div> table and does not use the standard <table> tag of HTML, due to which the HTML table functions cannot be used.
XGrids provide high performance and low memory usage, and can handle large amounts of data. To enable working with large amounts of data, the amount of HTML rendered is minimal and is not made available for each row. Therefore, instead of editing the HTML structure, you must use the available API to perform any required data manipulations.
XML data is the basis for creating rows. The XML nodes that represent rows in an XGrid are associated with an attribute, which is used for identification and for facilitating quick search. The following is an example of a typical XML structure:

<data>
<GetEmployeesResponse
xmlns="http://schemas.cordys.com/1.0/demo/northwind">
<tuple _xgrid_rowDataId="0">
<old>
<Employees>
<EmployeeID>1</EmployeeID>
<FirstName>Nancy</FirstName>
<LastName>Davolio</LastName>
</Employees>
</old>
</tuple>
<tuple _xgrid_rowDataId="1">
<old>
<Employees>
<EmployeeID>2</EmployeeID>
<FirstName>Andrew</FirstName>
<LastName>Fuller</LastName>
</Employees>
</old>
</tuple>
</GetEmployeesResponse>
</data>

In this example, the <tuple> represents the basis for a row (rowData node), the _xgrid_rowDataId is added by XGrid. The order of the rowData elements (<tuple>) is altered by XGrid when sorting and freezing rows.
The width of the columns and the width of the XGrid are not related. Resizing columns has no influence on the size of the XGrid, and resizing the XGrid has no influence on the width of the columns. This allows you maximum control over the table dimensions.

Example

This sample demonstrates the implementation and use of the XGrid component.

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html onapplicationready="getData()">
<head>
<title>xpath demo</title>
<script src="/cordys/wcp/application.js"></script>
<script>
function getData()
{
//collects data from busdataIsland and bind to xgrid
bdiEmployees.reset();
employeesGrid.bindData( bdiEmployees.data );
}
</script>
<script type="cordys/xml" id="requestGetEmployees">
<SOAP:Envelope xmlns:SOAP="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP:Body>
<GetEmployeesObjects xmlns="http://schemas.cordys.com/DemoWebServices">
<fromEmployeeID>1</fromEmployeeID>
<toEmployeeID>10</toEmployeeID>
</GetEmployeesObjects>
</SOAP:Body>
</SOAP:Envelope>
</script>
</head>
<body scroll="no" leftmargin="0" topmargin="0">
<div cordysType="wcp.library.data.BusDataIsland" async="false" id="bdiEmployees" automatic="false" request="requestGetEmployees.XMLDocument"></div>
<div style="width:100%;height:100%;overflow:hidden">
<div cordysType="wcp.library.ui.XGrid" id="employeesGrid"
xpathRowData = ".//*[local-name()='data']/*[local-name()='GetEmployeesObjectsResponse']/*[local-name()='tuple']"
xpathBusinessObject = ".//*[local-name()='Employees']"
style="width:95%;height:70%">
<div id="EmployeeID" ref=".//*[local-name()='EmployeeID']" dataType="integer">EmployeeID</div>
<div id="FirstName" ref=".//*[local-name()='FirstName']">FirstName</div>
<div id="LastName" ref=".//*[local-name()='LastName']">LastName</div>
</div>
</div>
</body>
</html>

pp108 : XGrid

XGrid

Syntax

Properties, Methods, and Events in XGrid

Remarks

Example