Pie Chart

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 Pie Chart component allows you to easily create a pie chart within an app. The component can either query for and display Rally data or display user-supplied data.

pie

Create a pie chart

First include the App SDK javascript:

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

Instantiate a new PieChart:

var pie = new rally.sdk.ui.PieChart(config, rallyDataSource);

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

Parameter Description Example
config* A pie chart 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 pie chart configuration object supports the following properties:

Parameter Description Example
type^ The Rally object type. "defect", "hierarchicalrequirement", "task"
attribute^ The object field used for grouping.
Note: This field must be limited to a list of allowed values.
"State", "ScheduleState"
query A filter clause to be applied to the data query.
May be a string or a Query object (default = "").
'ScheduleState = "In-Progress"'
height The height of the chart in pixels (default = 300). 400
width The width of the chart in pixels (default = 300). 400
title The title of the chart (default = ""). "My Pie Chart"
subtitle The subtitle of the chart (default = ""). "My Subtitle"
colors An object which maps values to colors to be used for the chart.
If not specified, Rally standard colors will be used.
{ "Accepted" : "#5C9ACB",
"In-Progress" : "rgb(0, 255, 0)",
"Backlog" : "#6AB17D" }
noDataMessage The message to display if there is no chart data
(default = "No data").
"No data"
values* An object which maps values to labels for each slice to be shown in the chart. {"/release/12345": "Release 1", "/release/23456", "Release 2"}
data* An object which maps values to slice counts to be shown in the chart. {"/release/12345": 5, "/release/23456", 8}
  * = required for non-querying
  ^ = required for querying

Display a pie chart

Once created, use the display method to query Rally for the specified data and then show the chart:

pie.display(domElement, onPieCompletedCallback);

Parameter Description Example
domElement* The element in which to display the chart.
This may be either an element or an element ID.
"chartDiv",
document.getElementById("chartDiv")
onPieCompletedCallback A function which will be called when the pie chart has completed rendering. function onPieCompletedCallback(sender,
args) {
   var values = args.values;
   var data = args.data;
}
  * = required parameter

Methods

The pie chart component defines the following methods:

Method Name Parameters Description Example
display element*, onLoad Display the chart in the specified element. pie.display("aDiv");
destroy - Removes this component. pie.destroy();
* = required parameter

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

Event Name Description Event Arguments Example
onValuesRetrieved Fired when the allowed slice values have been retrieved. The eventArgs object passed to any event listeners contains the following property:
  • values: An array of the values represented in the chart
  • function onPieValuesRetrieved(p,
    eventArgs) {
       //Remove the last value from the chart eventArgs.values.pop();
    }
    pie.addEventListener("onValuesRetrieved",
       onPieValuesRetrieved);
    onDataRetrieved Fired when the chart data has been retrieved. The eventArgs object passed to any event listeners contains the following property:
  • data: An object containing the counts each slice in the chart
  • function onPieDataRetrieved(p, eventArgs)
    {
       var data = eventArgs.data;
    }
    pie.addEventListener("onDataRetrieved",
       onPieDataRetrieved);
    onLoad Fired when the chart has finished rendering. The eventArgs object passed to any event listeners
    contains the following properties:
  • values: An array of the values represented in the chart
  • data: An object containing the counts each slice in the chart
  • function onPieLoaded(p, eventArgs) {
       var values = eventArgs.values;
       var data = eventArgs.data;
    }
    pie.addEventListener("onLoad",
       onPieLoaded);
    onSliceClick Fired when a chart slice is clicked. The eventArgs object passed to any event listeners contains the following properties:
  • color: The color of the clicked slice
  • label: The label of the clicked slice
  • value: The value of the clicked slice
  • size: The number of items represented by the clicked slice
  • function onPieSliceClicked(p, eventArgs) {
       var color = eventArgs.color;
       var label = eventArgs.label;
       var size = eventArgs.size;
       var value = eventArgs.value;
    }
    pie.addEventListener("onSliceClick",
       onPieSliceClicked);

    Example

    Copy and paste the following into a Rally Custom app page.
    More examples: Defects by Severity and Defect Dashboard

    <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
    <html>
    <head>
       <title>Pie Chart Example</title>
       <meta name="Name" content="Component Example: Pie Chart" />
       <meta name="Version" content="1.32" />
       <meta name="Vendor" content="Rally Software" />
       <script type="text/javascript" src="/apps/1.32/sdk.js"></script>
       <script type="text/javascript">

         function showPie() {

           var rallyDataSource = new rally.sdk.data.RallyDataSource('__WORKSPACE_OID__',
                                   '__PROJECT_OID__',
                                   '__PROJECT_SCOPING_UP__',
                                   '__PROJECT_SCOPING_DOWN__'
    );
           var pieConfig = {
                type : "Defect",
               attribute: "Priority",
               title : "Defects by Priority",
               height : 200,
               width : 200
             };
           var pieChart = new rally.sdk.ui.PieChart(pieConfig, rallyDataSource);
           pieChart.display("pieChartDiv");
         }

         rally.addOnLoad(showPie);
         </script>
    </head>
    <body>
       <div id="pieChartDiv" style="height:225px; width:250px"></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.