Drop-down

Deprecation Warning! The content below is only applicable for use within deprecated 1.x versions of CA Agile Central'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 drop-down component provides an easy way to display data in a drop-down list.

dropdown

Drop-down includes the following topics:

Create a drop-down

First include the App SDK JavaScript:

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

Instantiate a new drop-down:

var dropdown = new rally.sdk.ui.basic.Dropdown(config);

The parameters for rally.sdk.ui.basic.Dropdown are as follows:

Parameter Description Example
config* A configuration object. { label: "Select one", showLabel: true }
  * = required parameter

The drop-down configuration object supports the following properties:

Parameter Description
showLabel If showLabel is true, then the label will be shown
(defaults to true if label is specified, false otherwise)
label The text for the description that will be placed next to the drop-down
labelPosition Where the label will be displayed, either before or after
valueProperty The key to use to get the value property out of the specified items in the drop-down
(default = "value")
displayValueProperty The key to use to get the displayValue property out of the specified items in the drop-down
(default = "label")
rememberSelection Whether to persist the current selection as the default for future sessions
(default = true)
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)
defaultValue The first value the drop-down will be set to
(if rememberSelection is true the remembered value is given priority over this default)
items The items to include in the drop-down, equivalent to calling setItems.
width Specify the drop-down's width in pixels
(by default the drop-down will be sized according to its contents)
  * = required parameter

Displaying a drop-down

Once created, use the display method to display the drop-down:

dropdown.display(domElement, onChanged);

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") <
onSelectionChanged A callback function that will be executed each time the user changes the components value.
This callback will also be called once when the component is finished rendering.
function onSelectionChanged(sender,
eventArgs) {
  var selectedDisplayValue = eventArgs.displayedValue;
   var selectedValue = eventArgs.value; }
  * = required parameter

Public methods

Method Name Parameters Returned Data Example
display See above - See above
getDisplayedValue - The displayed value of the currently selected item in the drop-down. "Selection1"
getValue - The value of the currently selected item in the drop-down. var value = dropdown.getValue();
getComponentValue - Same as getValue.
Provides a consistent interface for retrieving the value of basic components.
var value = dropdown.getComponentValue();
getDefaultValue - The default value of the drop-down.
Order of precedence: previous selection (if rememberSelection=true),
value determined by defaultDisplayValue config parameter.
"Selection1"
getItems - An array of the raw data contained in the drop-down. [ { label: "Selection1", value: "Selection1" }, ... ]
getSelectedItem - The currently selected item. {label: "Selection1", value: "Selection1"}
getValidEvents - Returns an object containing all the valid events drop-down can emit. { onChange: "onChange", onLoad:"onLoad" }
setItems - Adds the list of objects into the drop-down to be displayed. setItems([ {label:"Tim",
value:"/user/1234"} ]);
or { uniqueValue:"displayText" }
setDisplayedValue displayedValue* Set the selected item of the drop-down based on the specified display value. dropdown.setDisplayedValue("Selection 1");
setValue value* Set the selected item of the drop-down based on the specified value. dropdown.setValue("1");
setComponentValue value* Same as setValue.
Provides a consistent interface for setting the value of basic components.
dropdown.setComponentValue("1");
destroy - Removes this component. dropdown.destroy();
  * = 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 (such as 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("onChange", onChangeEventListener);

Example

Copy and paste the following into a CA Agile Central 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) 2010-2011 CA Agile Central Software Development Corp. All rights reserved -->
<html>
<head>
    <title>Dropdown Example</title>
    <meta name="Name" content="Component Example: Dropdown"/>
    <meta name="Version" content="2010.4"/>
    <meta name="Vendor" content="CA Agile Central Software"/>
    <script type="text/javascript" src="/apps/1.26/sdk.js"></script>
    <script type="text/javascript">
       function dropdownSelectionChanged(sender, eventArgs) {
          var selectedItem = eventArgs.item;
          var selectedValue = eventArgs.value;
       }

       function onLoad() {

          var data = [
             { label: "Selection 1", value: 1 },
             { label: "Selection 2", value: 2 },
             { label: "Selection 3", value: 3 },
             { label: "Selection 4", value: 4 },
             { label: "Selection 5", value: 5 },
             { label: "Selection 6", value: 6 },
             { label: "Selection 7", value: 7 }
          ];

          var dropdown = new rally.sdk.ui.basic.Dropdown({ items : data });
          dropdown.display("dropdown", dropdownSelectionChanged);        }

       rally.addOnLoad(onLoad);
   
</script>
</head>
<body>
    <span id="dropdown"></span>
</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.