CheckBox

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 checkbox component provides an easy way to create a stateful checkbox and label.

checkbox

Checkbox includes the following topics:

Create a checkbox

First include the App SDK JavaScript:

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

Instantiate a new checkbox:

var checkbox = new rally.sdk.ui.basic.CheckBox(config);

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

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

The checkbox configuration object supports the following properties:

Parameter Description
checked Whether the checkbox should be checked by default
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 checkbox
labelPosition Where the label will be displayed
Valid positions: "before", "after"
Default = "before"
value A value to be associated with the checkbox
rememberChecked Whether to persist the checked status as the default for future sessions (default = true)
  * = required parameter

Display a checkbox

Once created, use the display method to display the checkbox:

checkbox.display(domElement, onChanged);

Parameter Description Example
domElement* The element in which to display the checkbox.
This may be either an element or an element ID.
"checkboxSpan", document.getElementById("checkboxSpan")
onChanged A callback function that will be executed each time the checkbox is checked or unchecked. function onChanged(sender, eventArgs) {
   var checkboxValue = eventArgs.value;
   var checked = eventArgs.checked;
}
  * = required parameter

Public methods

Method Name Parameters Description Example
display See above - See above
destroy - Removes the component from the app. checkbox.destroy();
getChecked - Returns whether the checkbox is checked. var checked = checkbox.getChecked();
getComponentValue - Same as getChecked.
Provides a consistent interface for retrieving the value of basic components.
var checked = checkbox.getComponentValue();
setChecked checked Set whether the checkbox is checked. checkbox.setChecked(true);
setComponentValue checked Same as setChecked.
Provides a consistent interface for setting the value of basic components.
checkbox.setComponentValue(true);
getValue - Returns the value as specified in the constructor config. var value = checkbox.getValue();
getValidEvents - Returns an object containing the valid events for checkbox. var events = checkbox.getValidEvents();

Events

Events are used to notify users 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 checkbox component supports the following events:

Event Name Description Event Arguments Example
onChange Fired when the checkbox is checked or unchecked The eventArgs object passed to any event listeners
contains the following properties:
  • value: The value of the checkbox as specified in its constructor config

  • checked: true if the checkbox is checked, false otherwise
  • function onCheckboxChanged(checkbox, eventArgs)
       var value = eventArgs.value;
       var checked = eventArgs.checked;
    }
    checkbox.addEventListener("onChange",
       onCheckboxChanged);

    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>CheckBox Example</title>
        <meta name="Name" content="Component Example: CheckBox" />
        <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 checkBoxChanged(cb, args) {
                var value = args.value;
                var checked = args.checked;
           }

           function onLoad() {
                var config = {
                    label : "Blocked",
                    value : "isBlocked",
                    showLabel: true,
                   labelPosition: "after"
       };

            var checkBox = new rally.sdk.ui.basic.CheckBox(config);
            checkBox.display("checkbox", checkBoxChanged);    }

        rally.addOnLoad(onLoad);
       </script>
    </head>
    <body>
    <span id="checkbox"></span>
    </body>
    </html>