Chooser

Deprecation Warning! The content below is only applicable for use within deprecated 1.x versions of Rally's App SDK. Use of the component(s) and/or code on this page is not supported. To develop custom apps within our current environments, please see App SDK 2.0 documentation.

The Chooser component displays a dialog with a list of artifacts from which to choose.

The list can be filtered based on text found in the Name, Description, or Notes of the artifact through an input field. You can configure the chooser to display any type of artifact (like user stories, defects, or projects).

chooser

Create a chooser

First include the App SDK javascript:

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

Instantiate a new chooser:

var chooser = new rally.sdk.ui.Chooser(config, rallyDataSource);

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

Parameter Description Example
config* A chooser configuration object { type: "defect", title: "Choose a Defect" }
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

The Chooser configuration object supports the following properties:

Parameter Description Example
type* A Rally artifact type "HierarchicalRequirement"
title* The title of the dialog "Choose a User Story"
fetch A comma-delimited list of additional properties on the artifacts to fetch; by default, will fetch Name and FormattedID (if available) "FormattedID,Name,Description"
draggable Allow the dialog to be draggable true
closeable Show the x icon to close the dialog true
query A filter clause to be applied to the object query, may be a string or a Query object 'ScheduleState = "In-Progress"'
width The width of the dialog (defaults to 400) 500
height The height of the chooser (defaults to 300) 200
  * = required parameter

Display a chooser

Once created, use the display method to show the chooser:

chooser.display(onCloseCallback);

Parameter Description Examples
onCloseCallback An optional function that will be called when a user selects an item and clicks OK function(chooser, eventArgs){
   console.log(eventArgs.selectedItem);
};
  * = required parameter

Methods

The Chooser component defines the following methods:

Method Name Parameters Description Example
display callback Displays the chooser.
The callback function is called when a user chooses OK and is past the selected item. May also use addEventListener to attach callback.
chooser.display(function(chooser, args){
   var selectedItem =
args.selectedItem;
});
destroy - Removes this component chooser.destroy();
getValidEvents - Returns a map of events this component supports chooser.getValidEvents();
  * = required parameter

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 Chooser component supports the following events:

Event Name Description Event Arguments Example
onClose Fired when the chooser is closed. The eventArgs object contains a single property:
selectedItem: the item the user selected from the chooser.
function onCloseCallback(chooser, eventArgs) {
   var selectedItem = eventArgs.selectedItem;
}
chooser.addEventListener("onClose",onCloseCallback);
onDataRetrieved Fired when the data query
has returned, but before it has been rendered. Useful for modifying data before it is bound into the table of the chooser.
The eventArgs object contains the following property:
items: The array of Rally objects returned from the data query.
function onChooserDataRetrieved(chooser, eventArgs){
   var items = eventArgs.items;
}
chooser.addEventListener("onDataRetrieved", onChooserDataRetrieved);
onLoad Fired when the chooser's data has been fully rendered. Called only once. No args passed to the function. function onChooserLoad(chooser) {
   //chooser loaded
}
chooser.addEventListener("onLoad",
   onChooserLoad);

Example

Copy and paste the following into a Rally custom app.

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

     function chooserOnClose(chooser, args) {
       var selectedItem = args.selectedItem;
     }

     function onLoad() {

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

       var chooserConfig = {
         type : "HierarchicalRequirement",
         title : "Choose a User Story"
       };

       var chooser = new rally.sdk.ui.Chooser(chooserConfig, rallyDataSource);

       chooser.display(chooserOnClose);
     }

     rally.addOnLoad(onLoad);

   </script>
</head>
<body>
</body>
</html>

Feedback

Need more help? The CA Agile Central Community is your one-stop shop for self-service and support. To submit feedback or cases to CA Agile Central Support, find answers, and collaborate with others, please join us in the CA Agile Central Community.