Grid |
Enables an HTML table to be represented as a multi-functional grid.
Syntax
HTML |
<table id=tableID class="grid">...</table> |
Scripting |
application.addLibrary("/cordys/wcp/library/ui/grid.htm",tableID) |
This library enables grid functionality of the table such as resizing, swapping, hiding/showing, sorting of columns and also persisting the table properties for a select duration of time. The table properties can be made persistent by using buslocalstore component. With this, the state of the table will be maintained whenever the table is re-loaded.
By default, the header row is attached to a context menu, through which columns can be sorted, hidden, shown or brought back to default position.
Process Platform Ajax Toolkit comes with options of cutting, copying and inserting the rows of the grid. This is made possible by attaching a shortcut menu to each column in the grid. To have the shortcut menu, an attributecopiableneeds to be set on the header rows of the corresponding cells. A Cut will cut the corresponding row, Copy will copy the row and Insert will insert the cut and copied rows above the row on which the insert option is selected.
To dynamically add and initialize this component, you can use the initializeHTMLElements or addType methods of the Application object.
Sorting Columns
Grid columns, by default, support sorting of data by integers and string. To sort columns based on other parameters,
- In the application, create an algorithm for sorting data based on your parameters.
- In the sortAlgorithm property of the column's header, include a reference to the algorithm.
Properties, Methods, and Events in Grid
The properties, methods and events defined for the Grid component are as follows:
Table 1. List of Attributes
Attribute |
Property |
Description |
|---|---|---|
contextmenu |
contextmenu |
Returns a handle to the contextmenu object that is displayed while doing a right-click the header of the grid. This is a runtime property. All runtime properties, methods and events supported by the contextmenu, are supported. |
copiable |
copiable |
Boolean that defines whether the row is copiable or not. This property is to be set on the corresponding header rows of the column. Once set, the columns display a shortcut menu with options to cut, copy and insert a row. |
isSubTotalRow |
isSubTotalRow |
Boolean that defines whether the row has to be treated as a subtotal row or as a subheading row. The rows around this row will be considered as a single group for sorting. This is available for each of the rows in the body of the table. |
movableColumns |
movableColumns |
Boolean that defines whether the columns of the grid can be moved at runtime. |
shadeClasses |
shadeClasses |
String specifying the classes that must be applied for shading the grid. The classes should be separated by spaces. For example, shadeClasses="light lightmedium". Also note that you have to invoke the redraw() method after you have added or removed one or more rows. |
saveState |
saveState |
Boolean that indicates whether grid state (sizes, places, and hidden columns) can be stored for the next visit of the page. The saveState property will work only if the persistence object functionality is enabled by the browser. As such, IE 5.0 and IE 5.5 have problems with persistence of data, and hence IE 6.0 is recommended. |
displayContextMenu |
N/A |
Sets the displayContextMenu property that defines whether shortcut menu will be displayed or hidden when user right-clicks on the table header. This takes a Boolean value. |
expiryDuration |
N/A |
Sets the expiryDuration property that defines the duration in days up to which table properties will be persisted. By default, the table properties will be persisted for a period of 7 days. |
resizable |
N/A |
Sets the resizable property of the column. |
resizeColumns |
N/A |
Sets the resizeColumns property of the grid. |
sortable |
N/A |
Sets the boolean sortable property that defines whether sorting is allowed on the table columns.
|
selectType |
N/A |
Sets the variant that specifies the type of row selection that the grid allows.
|
toggleColumns |
N/A |
Sets the Boolean toggleColumns property that defines whether columns of the table can be hidden at run time. |
fixedWidth |
N/A |
Boolean. The Default value is True. If True, the width of the grid remains constant when the columns are resized. If False, the grid is resized when its columns are resized. |
Table 2. List of Methods
Method |
Description |
|---|---|
Returns a collection of rows selected in the grid. |
|
Hides the column from the grid displayed. |
|
redraw([bkeepUserSelection]) |
Redraws the grid with the specified shadeClasses and also sorted on the last sorted column. The bkeepUserSelection parameter can be set to True for keeping the user selections within the grid when calling this method. The default value of the parameter is False. |
getColumnResizable(nIndex) |
Gets the resizable property for the column of a given index. Returns True if the given column is resizable, else returns False. |
getDisplayContextMenu |
Gets the value of the displayContextMenu property. |
getExpiryDuration |
Gets the value of the expiryDuration property. |
getResizeColumns() |
Gets the resizeColumns property of grid. |
setColumnResizable(nIndex, bResizable) |
Sets the givenbResizable(a boolean) value of theresizableproperty for a column of a given index. IfbResizableis True then the column is resizable. IfbResizableis False, the column cannot be resized. |
setDisplayContextMenu |
Sets thedisplayContextMenuproperty that defines whether shortcut menu will be displayed or hidden when user right-clicks on the table header. This returns a Boolean value. |
setResizeColumns(bResize) |
Sets theresizeColumnsproperty of grid with givenbResizable(a boolean) value. IfbResizableis True, all the columns in the grid are resizable. IfbResizableis False, the columns in the grid cannot be resized. It is set to True, by default. |
setExpiryDuration |
Sets the expiryDuration property that defines the duration in days up to which table properties will be persisted. By default, the table properties will be persisted for a period of 7 days. |
setSelectType |
Sets the variant that specifies the type of row selection that the grid allows.
|
getSortable |
Gets the value of the sortable property |
setSortable |
Sets the Boolean sortable property that defines whether sorting is allowed on the table columns. |
getSortedColumn |
Gets the integer that returns the index of the column that was lastly sorted. If no columns are sorted, then this value points to null. |
getToggleColumns |
Gets the value of thetoggleColumnsproperty. |
setToggleColumns |
Sets the BooleantoggleColumnsproperty that defines whether columns of the table can be hidden at run time. |
selectAll(bSelect) |
Selects or deselects all the rows in the grid. The parameter bSelect indicates whether the rows are selected or deselected. |
selectRow(oRow, bSelect) |
Selects or deselects a particular row in the grid. The parameter oRow indicates the row element that is to be selected and bSelect indicates whether the row is selected or deselected. |
showColumn(nIndex) |
Displays a column that was previously hidden. If the parameter nIndex is not specified, the current source element is considered. If the current source element is a column, then the index of that column is taken as thenIndexvalue. |
Sorts the cells of a column in the grid in ascending/descending order. |
Table 3. List of Events
Event |
Description |
|---|---|
Fires when a row is inserted into the table, as a result of a Cut or a Copy operation. |
|
Fires before a row is inserted into the table, as a result of a Cut or a Copy operation. |
|
Fires when the columns in the grid are swapped. |
|
Fires when the columns in the grid are hidden or shown. |
|
Fires after the row is copied using the Copy menu item from shortcut menu. |
|
Fires after the row is copied using the Cut menu item from shortcut menu. |
|
Fires when a row in the grid is selected. |
|
onsetdefault |
Fires when the user sets the grid to the default state. This happens when the user clicks on "Set Grid Default" in the grid header context menu. |
To provide easy navigation to the users using the grid, the following keyboard navigations are supported :
- [arrow up]: Go to previous row.
- [arrow down]: Go to next row.
- [Ctrl and arrow down]: Multiple rows selected (selectType property should be set to "multiple").
However, to use the keyboard navigation, the user is expected to click any row initially, and then navigate through the keyboard.
Remarks
To implement horizontal and vertical scrollbars to a grid table, the table should be enclosed inside a DIV element, whose overflow properties are set to auto and width is set to 100%. In such cases, the width of the table is expected to be in pixels and should be larger than the width of the DIV element in which it is enclosed. Following is an example of how this could be achieved:
HTML |
<DIV style="width:100%;overflow-x:auto;overflow-y:auto"> <TABLE id="sampleTable" class="grid" border=0 cellspacing=0 cellpadding=0 width="1500px"> <THEAD> <!-- Header Declaration --> </THEAD> <TBODY> <!-- Content of the Table --> </TBODY> </TABLE> </DIV> |
Note:
- Events performed on the grid such as deletion of rows etc., cannot be caught by the grid. In such cases, the header of the grid gets dislocated. The following line of code is written to avoid such situations.
HTML
<grid-id>.rows(0).style.pixelTop = <grid-id>.parentNode.scrollTop;
- It is possible to cut or copy only one row at a time from the grid, irrespective of the number of rows selected. The same case holds true when multiple rows are selected using the Ctrl or Shift keys.
Example
This sample shows the implementation and use of the grid behavior.
<!DOCTYPE HTML PUBLIC"-//W3C//DTD HTML 4.01 Transitional//EN""http://www.w3.org/TR/html4/loose.dtd"> <html> <head> <script type="text/javascript" src="/cordys/wcp/application.js"></script> <title>Grid with sizable and movable columns</title> <style type="text/css"> .header { font:12px menu;width:100%;height:20px } .cell { font:12px menu;border:1px solid darkgray } </style> </head> <body margin="20"> <h3>Table with grid/listview functionality.</h3> This is IE5+ only. <br/><br/> You can <LI>resize the columns</LI> <LI>move the columns</LI> <LI>hide the columns</LI> <LI>sort ascending or descending on a column</LI> <br/><br/> And, the state is saved, so when you come back again, you see exactly the same as when you left. <br/><br/> <div style="overflow:auto;height:100%;width:100%"> <table id="sampleTable" class="grid" border=0 cellspacing=1 cellpadding=0> <thead> <tr> <td><button class="medium header">Column 1</button></td> <td><button class="medium header">Column 2</button></td> <td><button class="medium header">Column 3</button></td> <td><button class="medium header">Column 4</button></td> <td><button class="medium header">Column 5</button></td> <td><button class="medium header">Column 6</button></td> <td><button class="medium header">Empty Column</button></td> </tr> </thead> <tbody> <tr> <td class="cell">This</td> <td class="cell">is</td> <td class="cell">some</td> <td class="cell">test</td> <td class="cell">data</td> <td class="cell">1.123</td> <td class="cell"></td> </tr> <tr> <td class="cell">data</td> <td class="cell">from</td> <td class="cell">second</td> <td class="cell">table</td> <td class="cell">row</td> <td class="cell">1</td> <td class="cell"></td> </tr> <tr> <td class="cell">hello</td> <td class="cell">this</td> <td class="cell">is</td> <td class="cell">really</td> <td class="cell">cool</td> <td class="cell">100</td> <td class="cell"></td> </tr> <tr> <td class="cell">resize columns</td> <td class="cell">move columns</td> <td class="cell">hide columns</td> <td class="cell">save/restore state</td> <td class="cell">scrolling</td> <td class="cell">24</td> <td class="cell"></td> </tr> <tr> <td class="cell">This</td> <td class="cell">is</td> <td class="cell">some</td> <td class="cell">test</td> <td class="cell">data</td> <td class="cell">256</td> <td class="cell"></td> </tr> <tr> <td class="cell">data</td> <td class="cell">from</td> <td class="cell">second</td> <td class="cell">table</td> <td class="cell">row</td> <td class="cell">127</td> <td class="cell"></td> </tr> <tr> <td class="cell">hello</td> <td class="cell">this</td> <td class="cell">is</td> <td class="cell">really</td> <td class="cell">cool</td> <td class="cell">1.1389</td> <td class="cell"></td> </tr> <tr> <td class="cell">resize columns</td> <td class="cell">move columns</td> <td class="cell">hide columns</td> <td class="cell">save/restore state</td> <td class="cell">scrolling</td> <td class="cell">10.99</td> <td class="cell"></td> </tr> </tbody> <tfoot> <th class="cell">I am</th> <th class="cell">Table Footer</th> <th class="cell">No Sorting</th> <th class="cell">Static</th> <th class="cell">Bold because</th> <th class="cell">in </th> <th class="cell"></th> </tfoot> </table> </div> <br/> The only thing you have to set on your html table is: class="grid" !!! </body> </html>