Tables

Print this topicEmail this topicSave as PDF

The table component allows you to display data in a tabular format. The table has clickable headers that will re-order the display of the rows in the table according to the header column that has been clicked. Various appearance characteristics of the table are configurable, including the height and width of the table, the width of specific columns, and the content of the column header labels.

The table can either query for and display Rally data or user-supplied data. Basic components can also display in table cells.

table

Creating a table

Include the following JavaScript file when you want to use a Rally Table component in your App.

<script type="text/javascript" src="/apps/[version]/sdk.js"></script>

Instantiate a new table:

var table = new rally.sdk.ui.Table(tableConfig, rallyDataSource);

The parameters for rally.sdk.ui.Table are as follows:

Parameter Description Example
config* A table configuration object. { type: "defect", attribute: "priority" }
rallyDataSource^ An instance of rally.sdk.data.RallyDataSource new rally.sdk.data.RallyDataSource (  "__WORKSPACE_OID__",
   "__PROJECT_OID__",
   "__PROJECT_SCOPING_UP__",
   "__PROJECT_SCOPING_DOWN__")
  * = required parameter
  ^ = required for querying

The config object parameters are as follows:

Parameter Description Example
columns* An array of objects describing the columns to be displayed in the table. [{key: "col1", header: "Column 1", width:
100},
{key: "col2", header: "Column 2", width:
"30%"}]
height Size in pixels of the total height of the table. 500, "500px"
width Size in pixels of the total width of the table. 600, "600px"
sortingEnabled Boolean to turn sorting on/off on the table (Default = true). true
noDataMessage Message to display when the table contains no data.
(Default = "There is nothing to display.") 		"No data!"
items An array of objects from which to create table rows.
Equivalent to calling addRows(items); 		[{col1: "val1", col2: "val2", col3: "val3"}, {col1: "val4", col2: "val5", col3: "val6"}]
type^ The Rally object type to be queried. "defect", "hierarchicalrequirement"
fetch A comma separated list of additional fields to include in the query.
If not specified the values in columnKeys will be used. 		"Name,FormattedID,ScheduleState"
order An order by clause to be applied to the query. (Default = "") "CreationDate"
query A filter clause to be applied to the object query.
May be a string or a Query object. (Default = "") 		'(ScheduleState = "In-Progress")'
  * = required parameter
  ^ = required for querying

Displaying a table

Once created, use the display method to display it:

table.display(domElement, onTableCompletedCallback);

Parameter Description Example
domElement* The element in which to display the table.
This may be either an element or an element id. 		"tableDiv",
document.getElementById("tableDiv")
onTableCompletedCallback A function which will be called when the table has completed rendering. function onTableCompletedCallback(sender,
args) {
   var items = args.items;
}
  * = required parameter

Methods

The table component defines the following methods:

Method Name Parameters Description Example
getHeaders - Returns an array of objects containing information about key, header, width and specifiedWidth. table.getHeaders();
getColumnKeys - Returns an array of Table column attribute names. colKeys = table.getColumnKeys();
getColumnHeaders - Returns an array of Table column header labels. hdrLabels = table.getColumnHeaders();
setCell row, column, content Set the text content of the specified cell. table.setCell(0,2, "blue"); or table.setCell(1, "age", 27);
getCell row, column Get the text content of the specified cell. content = table.getCell(1,3);
addRow rowContent Add the specified row to the table. rowInfo = {'name' : 'Betty', 'age' : 31, 'favcolor' : 'aqua'}; table.addRow(rowInfo);
addRows rowContents Add a row to the table with each element in the specified array. table.addRows(queryResults.stuff);
display element Display the table in the specified element. table.display("aDiv");
destroy - Removes this component. table.destroy();

Events

Events are used to notify consumers of a component when actions occur.

The following methods are provided in order to interact with this component's events:

Method Parameters Description Example
addEventListener eventName*, listener*, scope Registers the specified listener with the component's queue for the specified event and returns an object which can be used to remove the event listener later. The listener parameter should be a function with two parameters: 1) the component that fired the event; 2) an eventArgs object with properties specific to the event being fired. This function will be called by the component when the event occurs. If the optional scope parameter was specified the function will be called on that object (like scope.listener(sender, args);) function listener(sender, eventArgs) {
   //Respond to event
}
var eventObj = component.addEventListener(eventName, listener);
removeEventListener eventObj* Unregisters the specified event from the component.
The eventObj parameter should be the return value of addEventListener() when the listener was originally registered. 		var eventObj = component.addEventListener(...); component.removeEventListener(eventObj);
getValidEvents - Returns an object with a property for each event name supported by the component. This is useful for passing as the first parameter to addEventListener(). var eventName = component.getValidEvents().onClick;
  * = required parameter

The table component supports the following events:

Event Name Description Event Arguments Example
onCellClick Fired when a table cell is clicked. The eventArgs object passed to any event listeners contains the following properties:

  • columnIndex: The zero based column index of the clicked cell
  • rowIndex: The zero based row index of the clicked cell
  • columnHeader: The header text of the clicked cell's column
  • columnKey: The data field key of the clicked cell's column
  • data: The displayed value of the clicked cell
    		•  function onTableCellClicked(table, eventArgs) {
       var cellData = eventArgs.data;
       var rowIndex = eventArgs.rowIndex;
       var columnIndex = eventArgs.columnIndex;
       var columnHeader = eventArgs.columnHeader;
       var columnKey = eventArgs.columnKey;
    }
    table.addEventListener("onCellClick",
       onTableCellClicked);
    onDataRetrieved If type specified in constructor config, fired when the data query
    has returned. This event is useful for modifying data before it is bound into the table.     		The eventArgs object passed to any event listeners contains the following property:

  • items: The array of Rally objects returned from the data query
    		•  function onTableDataRetrieved(table,
    eventArgs) {
       var items = eventArgs.items;
    }
    table.addEventListener("onDataRetrieved",
       onTableDataRetrieved);
    onLoad Fired when the table has been fully rendered. The eventArgs object passed to any event listeners contains the following property:

  • items: The array of objects displayed in the table
    		•  function onTableLoad(table,
    eventArgs) {
       var items = eventArgs.items;
    }
    table.addEventListener("onLoad",    onTableLoad);

    Example

    Copy and paste the following into a Rally Custom App Tab to see it in action!
    Another example: Defects by State

    <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
    <!-- Copyright (c) 2010 Rally Software Development Corp. All rights reserved -->
    <html>
    <head>
       <title>Table Component Example</title>
       <meta name="Name" content="App Example: Table" />
       <meta name="Version" content="2010.4" />
       <meta name="Vendor" content="Rally Software" />
       <script type="text/javascript" src="/apps/1.24/sdk.js"></script>
       <script type="text/javascript">

         function tableExample() {
           var rallyDataSource = new rally.sdk.data.RallyDataSource('__WORKSPACE_OID__', '__PROJECT_OID__',       '__PROJECT_SCOPING_UP__', '__PROJECT_SCOPING_DOWN__');
          function itemQuery() {
             var queryObject = {
               key: 'stories',
               type: 'HierarchicalRequirement',
               fetch: 'FormattedID,Name,ScheduleState,Parent,Project'
             };
             rallyDataSource.findAll(queryObject, populateTable);
          }

          function populateTable(results) {
             var tableDiv = document.getElementById('aDiv');
             var config = { columns:
                 [{key: 'FormattedID', header: 'Formatted ID', width: 100},
                 {key: 'Name'},
                 {key: 'ScheduleState', header: 'Schedule State'},
                 {key: 'Parent.Project.Name'}] };
            var table = new rally.sdk.ui.Table(config);
             table.addRows(results.stories);
             table.display(tableDiv);

          };
          itemQuery();
         }

         rally.addOnLoad(tableExample);
       </script>
    </head>
    <body>
       <div id="aDiv"></div>
    </body>
    </html>

    Displaying components in cells

    The Table supports displaying any of the Basic Components in its cells. One common usage would be including a column of radio buttons to allow row selection. See the RadioButton component for an example of this.

    The following example demonstrates creating a table using multiple types of components in each row:

    components

    Example

    Copy and paste the following into a Rally Custom App Tab to see it in action!

    <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
    <!-- Copyright (c) 2010 Rally Software Development Corp. All rights reserved -->
    <html>
    <head>
       <title>Components in Table Cells Example</title>
       <meta name="Name" content="App Example: Components in Table Cells" />
       <meta name="Version" content="2011.05.23" />
       <meta name="Vendor" content="Rally Software" />

       <script type="text/javascript" src="/apps/1.24/sdk.js"></script>
       <script type="text/javascript">

          function tableExample() {

             var rallyDataSource = new rally.sdk.data.RallyDataSource('__WORKSPACE_OID__',
                                       '__PROJECT_OID__',
                                       '__PROJECT_SCOPING_UP__',
                                       '__PROJECT_SCOPING_DOWN__'    );

             var config = {
                columns: [ {key: 'FormattedIDLink', header: 'FormattedID'},
                   {key: 'NameTextBox', header: 'Name'},
                   {key: 'OwnerName', header: 'Owner'},
                   {key: 'ScheduleStateDropdown', header: 'Schedule State'},
                   {key: 'BlockedCheckBox', header: 'Blocked'}],
                type: "defect",
                fetch: "Name,FormattedID,Owner,ScheduleState,Blocked",
                query: "(State < Closed)"
             };

             var table = new rally.sdk.ui.Table(config, rallyDataSource);
             table.addEventListener(table.getValidEvents().onDataRetrieved, function(t, args) {
                rally.forEach(args.items, function(item) {
                   item.FormattedIDLink = new rally.sdk.ui.basic.Link({"item":item});
                   item.OwnerName = item.Owner ? item.Owner._refObjectName : "";
                   item.BlockedCheckBox = new rally.sdk.ui.basic.CheckBox(
                      {checked: item.Blocked, rememberChecked:false});
                   item.NameTextBox = new rally.sdk.ui.basic.TextBox(
                      {value:item.Name, rememberValue:false});
                   item.ScheduleStateDropdown = new rally.sdk.ui.basic.Dropdown(
                      {items: {Backlog:"Backlog", Defined:"Defined",
                         "In-Progress":"In-Progress",Completed:"Completed", Accepted:"Accepted"},
                         defaultValue: item.ScheduleState, rememberSelection:false})
                      });
             });
             table.display("div1");
          }

          rally.addOnLoad(tableExample);
       </script>
    </head>
    <body>
       <div id="div1"></div>
    </body>
    </html>
    © 2012 Rally Software Development Corp | Legal