Program Drop-down

Deprecated feature notice

Important! Only Rally customers that are currently using program mode will be able to access this functionality. Program mode is being phased out of Rally Software. If you are currently using programs, please contact rpm-usability@rallydev.com so we may help with your transition.

Program mode was created early in the Rally application's evolution, and at that time provided users with the ability to view the status of coordinated releases between multiple projects. This feature was used primarily before project scoping and data roll-ups were available.

Since that time, Rally has released other features that replace programs with enhanced functionality. Now you may view the cumulative data and status of several projects at once, using project scoping with a common parent project. You may also use Rally Portfolio Manager to manage high-level initiatives and themes associated with user stories in a project. Rally Portfolio Manager should not be used with programs.

This help page is available for those users that have created programs in the past and have not yet taken advantage of newer functionality.

The Program Drop-down component allows you to easily create a drop-down populated with program data from Rally.

program

Program Drop-down includes the following topics:

Create a Program Drop-down

First include the App SDK javascript:

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

Instantiate a new ProgramDropdown:

var dropdown = new rally.sdk.ui.ProgramDropdown(config, rallyDataSource);

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

Parameter Description Example
config* A Program Drop-down configuration object { label: "Select a program: " }
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 Program Drop-down configuration object supports the following properties:

Parameter Description Example
showLabel
If showLabel is true then the label will be shown
(defaults to true if label is specified, false otherwise).
true
label
The text for the description that will be placed next to the drop-down.
"Label Text"
labelPosition
Where the label will be displayed. Either before or after.
"before"
rememberSelection
Whether to persist the current selection as the default for future sessions. If false the default selection will be the first program with active releases (default = true).
false
defaultDisplayValue
The first display value the drop-down will be set to.
If rememberSelection is true, the remembered value is given priority over this default.
"Program 1"
defaultValue
The first value the drop-down will be set to.
If rememberSelection is true, the remembered value is given priority over this default.
"/program/12345"
width Specify the drop-down's width in pixels.
By default the drop-down will be sized according to its contents.
200
fetch A comma-separated list of additional fields to include in the query
(Defaults to Name,ObjectID,ReleaseStartDate,ReleaseEndDate).
"Description"

Display a Program Drop-down

Once created, use the display method to query Rally for the program data and then show the drop-down:

dropdown.display(domElement, onChangedCallback);

Parameter Description Example
domElement* The element in which to display the drop-down.
This may be either an element or an element ID.
"dropdownDiv",
document.getElementById("dropdownDiv")
onProgramSelected A function which will be called when the value of the drop-down has changed.
The function will be invoked passing the source drop-down as the sender parameter and an object containing
information about the currently selected item as the eventArgs parameter.
function onProgramSelected(sender,
eventArgs) {
   var selectedValue = args.value;
   var selectedDisplayValue = args.displayedValue;
}
  * = required parameter

Public methods

Method Name Parameters Description Example
display See above - See above
destroy - Removes this component. dropdown.destroy();
getSelectedName - Returns the name of the program currently selected in the drop-down. "Product Dev 2010"
getSelectedStart - Returns the start date of the earliest release within the program currently selected in the drop-down. "2010-09-01"
getSelectedEnd - Returns the end date of the latest release within the program currently selected in the drop-down. "2010-09-15"
getSelectedOids - Returns an array of the release object IDs for the program currently selected in the drop-down. ["111111", "2222222", "3333333"]
getQueryFromSelected - Returns a Query object to be used with Rally Data Source queryObj.query =
dropdown.getQueryFromSelected();
rallyDataSource.findAll(queryObj);
getItems - Returns an array containing all the programs in the drop-down. var programs = dropdown.getItems();
getSelectedItem - The currently selected program var program =
dropdown.getSelectedItem();
setDisplayedValue displayedValue* Set the selected item of the drop-down based on the specified display value. dropdown.setDisplayedValue("Package Tracking");
setValue value* Set the selected item of the drop-down based on the specified value. dropdown.setValue("Package Tracking");
  * = 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 Drop-down component supports the following events:

Event Name Description Event Arguments Example
onChange Fired when a new value is selected The eventArgs object passed to any event listeners
contains the following properties:

value: Returns the underlying value for the drop-downs current selection.
displayedValue: Returns the underlying displayed text for the drop-downs current selection.
item: Returns the object value that was used for the current selection.
dropdown.addEventListener("onChange", onChangeEventListener);
onLoad Fired when the component is loaded The eventArgs object passed to any event listeners contains the following properties:

value: Returns the underlying value for the drop-downs current selection.
displayedValue: Returns the underlying displayed text for the drop-downs current selection.
items: Returns all the items used to display this component.
item: Returns the object value that was used for the current selection.
dropdown.addEventListener("onLoad", onLoaded);
onDataRetrieved Fired when the drop-down data has been retrieved but before it is bound (useful for adding or removing items, sorting them, and so on) The eventArgs object passed to any event listeners contains the following properties:

items: An array of the retrieved items.
displayValueProperty: The property name corresponding to the display value of each item.
valueProperty: The property name corresponding to the value of each item.
function onDataRetrieved(a, eventArgs) {
   //Add an "All" option
   var all = {};
   all[eventArgs.displayValueProperty] = "All";
   all[eventArgs.valueProperty] = "All";
   eventArgs.items.unshift(all);
}
dropdown.addEventListener("onDataRetrieved",
   onDataRetrieved);

Example

Copy and paste the following into a Rally custom app page.

<!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>Program Dropdown Example</title>
    <meta name="Name" content="Component Example: Program Dropdown" />
    <meta name="Version" content="1.26" />
    <meta name="Vendor" content="Rally Software" />

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

       function programSelected(dropdown, eventArgs) {
          var selectedItem = eventArgs.item;
          var selectedValue = eventArgs.value;
}

      function onLoad() {
          var rallyDataSource = new rally.sdk.data.RallyDataSource('__WORKSPACE_OID__',
                                     '__PROJECT_OID__',
                                     '__PROJECT_SCOPING_UP__',
                                     '__PROJECT_SCOPING_DOWN__')
;
          var config = { label : "Select a program " };
         var programDropdown = new rally.sdk.ui.ProgramDropdown(config, rallyDataSource);
          programDropdown.display("aDiv", programSelected);
       }

       rally.addOnLoad(onLoad);

    </script>
</head>
 <body>
    <div id="aDiv"></div>
</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.