Using the Chart Class

Understanding How Charts Represent Data

PeopleSoft charts are an alternative means of visualizing tabular data.

For example, here is an example data table (with column headings):

* Numeric data

Some of the columns carry numeric measures (in our example, Units, Revenue, and Chart Height in Inches) and other columns have values that describe the data (for example, Product, Color, Month, Year, and Salesperson). Some of the data columns are numeric; others are not.

To create a chart you need to determine which fields you want to see in the chart. Then, you pass those into certain Chart class methods:

• SetDataXAxis.

• SetDataYAxis.

• SetDataSeries.

• SetDataZAxis

• SetFunnelDataActual (for funnel charts only).

• SetFunnelDataTarget (for funnel charts only).

Each of these methods takes RECORD.FIELD as a parameter. In addition, SetDataYAxis can take multiple RECORD.FIELD parameters.

Charting Numeric Data Sets

These sections discuss:

• Charting one set of numeric data.

• Charting two sets of numeric data.

• Charting three sets of numeric data.

Charting One Set of Numeric Data

In general, you pass a field with numeric data to SetDataYAxis and a field with non-numeric data to SetDataXAxis. These two methods are required.

Here’s a simple example. Suppose you want to show revenue by product as a chart. Essentially, this is the rowset that you’ll be working with, a subset of the rowset introduced previously:

* Numeric data

In this case, choose the Revenue field to be passed to SetDataYAxis and the Product field to be passed to SetDataXAxis.

Image: A pie chart showing product sales data

If you choose to display this as a pie chart, you end up with this:

Image: A bar chart showing product sales data

Or, you could display the data as a bar chart:

Alternatively, you could display the data with any chart type that can display one dimension of data, such as a horizontal bar, a line, a histogram, or other chart type.

What if you also wanted to show the same information but with additional month information? The table of data that you would be interested in is:

* Numeric data

In that case, choose the Revenue field to be passed to SetDataYAxis , the Product field to be passed to SetDataXAxis , and the month field to be passed to SetDataSeries.

Image: A bar chart showing product sales data by month

You would need to use a chart type that can display two dimensions along with the data. This rules out the pie chart, but you can still use a bar chart:

Image: A bar chart showing monthly sales data by product

To get a different view of the same data, you can change the method assignments, so that Month is passed in SetDataXAxis and Product is passed in SetDataSeries . The chart that results is this:

Charting Two Sets of Numeric Data

The following chart types allow you to plot two sets of numeric data:

• Scatter chart

• Line chart

• Histogram

• Funnel chart

• Overlay chart

The scatter and line charts let you plot one set of numeric data vertically along the y-axis and one set of data horizontally along the x-axis.

The funnel chart lets you plot both sets of numeric data vertically on the y-axis.

Here’s an example of a scatter chart representing the following table of data:

* Numeric data

Image: Scatter chart

This example illustrates the scatter chart for the preceding data:

You can also use a line chart to represent the same data. Whereas the scatter chart requires both x- and y-axes to be numeric, the line chart x-axis can be either numeric or non-numeric.

In a funnel chart one set of data is specified using the SetFunnelDataActual method and the other set of data is specified using the SetFunnelDataTarget method.

Image: Funnel chart

Here’s an example of a funnel chart that graphs two sets of data, a target amount and an actual amount:

For funnel charts, these additional considerations apply:

• SetData and SetDataXAxis are required.

• SetFunnelChartDataActual can be used instead of SetDataYAxis; either are valid.

• SetFunnelChartDataTarget is optional. When used, SetFunnelChartDataTarget must specify the same record as SetFunnelChartDataActual.

Charting Three Sets of Numeric Data

You can use the bubble chart to display three sets of numeric data. The first two sets are along the x- and y-axes just as if you were plotting two sets of numeric data. The third set of numeric data is displayed as the size of the bubble positioned at the (x,y) coordinate in the chart and is set by passing the field in the SetDataZAxis method.

Using the same data as the previous scatter chart example, a third column of numeric data (Age) is included:

* Numeric data

Image: Bubble chart

This example illustrates the bubble chart for the preceding data:

Determining the Appropriate Chart Type

Use the following procedures to determine the chart types that are appropriate for your data set:

• One set of numeric data.

• Two sets of numeric data.

• Three sets of numeric data.

Care should be taken when using the line chart with non-numeric data on the x-axis. You should only use it when the data along the x-axis suggests some sort of progression. For example, using a line chart when the x-axis represents a sequence of months is appropriate; using a line chart when the x-axis represents a list of people in alphabetical order probably is not.

Image: Flowchart for determining the appropriate chart types

Use the following flowchart to determine which chart types are appropriate to your data. In addition, the flowchart visually presents the methods and properties to use with your chart:

Determining the Chart Type for One Set of Numeric Data

Use the following procedure to determine the chart type and methods and properties to use for one set of numeric data:

1. Use the following flowchart to determine which chart types are appropriate to your data. In addition, the flowchart visually presents the methods and properties to use with your chart:

   Pass numeric data to SetDataYAxis.

2. Pass non-numeric data to SetDataXAxis.

3. Does the numeric data include 0 or negative values? If yes, finish by selecting one of these appropriate chart types:

   • Bar

   • Stacked bar

   • Horizontal bar

   • Horizontal stacked bar

   • Line

   • Histogram

   Note: Negative values cannot be displayed in any type of percent bar chart.

4. Otherwise, do you need to display more than one series of data? If no, finish by selecting one of these appropriate chart types:

   • Pie

   • Ring

   • Bar

   • Stacked bar

   • Percent bar

   • Horizontal bar

   • Horizontal stacked bar

   • Horizontal percent bar

   • Line

   • Histogram

5. Otherwise, select one of these appropriate chart types:

   • Bar

   • Stacked bar

   • Percent bar

   • Horizontal bar

   • Horizontal stacked bar

   • Horizontal percent bar

   • Line

   • Histogram

Determining the Chart Type for Two Sets of Numeric Data

Use the following procedure to determine the chart type and methods and properties to use for two sets of numeric data:

1. Do you have other non-numeric data to display? If no, complete steps 2 and 3:

2. Select one of these appropriate chart types:

   • Line.

   • Histogram.

   • Scatter.

   • Funnel (with both actual and target data).

   • Overlay.

3. Use these methods and properties for scatter, line, and histogram charts:

   1. Pass numeric data to SetDataYAxis.

   2. Pass numeric data to SetDataXAxis.

4. Otherwise, if you need to display more than one series of data in a funnel chart, complete the following:

   1. Pass the non-numeric data to SetDataXAxis.

   2. Pass numeric data to SetFunnelDataActual. (Alternatively, pass the numeric data to SetDataYAxis).

   3. (Optional) Pass numeric data to SetFunnelDataTarget.

Determining the Chart Type for Three Sets of Numeric Data

Use the following procedure to determine the chart type and methods and properties to use for three sets of numeric data:

1. Select the appropriate chart type: Bubble.

2. Pass numeric data to SetDataYAxis.

3. Pass numeric data to SetDataXAxis.

4. Pass numeric data to SetDataZAxis.

Setting Chart Colors

Chart colors are determined in the following ways:

• Automatically.

• By using the SetColorArray method to specify an array of color choices.

• By using the SetDataColor method to specify a field on a record that holds a color value.

Automatic color determination occurs when neither of the other two methods is used. For all charts except pie charts, each data series is assigned a color; all data points within a series share that color. For pie charts each data point is assigned its own color. In that way it’s easier to distinguish pie segments from one another. Here is an example of the base data that will be charted:

The Review Rating field is assigned to the x-axis, Percent is assigned to the y-axis, and Year is assigned to the data series:

&cChart.SetData(Record.CJY_RVW_DSTRBTN);
&cChart.SetDataXAxis(CJY_RVW_DSTRBTN.CJY_RVW_RTG);
&cChart.SetDataYAxis(CJY_RVW_DSTRBTN.CJY_DSTRBTN_PCT);
&cChart.SetDataSeries(CJY_RVW_DSTRBTN.CJY_YR);

Image: Bar and pie charts using automatic color generation

Automatic color generation results in the following bar and pie charts:

SetColorArray allows you to create an array of color values in PeopleCode and pass that to the charting engine for use in rendering the chart. It works the same way as using automatic color assignment, except that it allows you to pass in a color sequence that differs from the style sheet’s default sequence. For bar charts, each data series is assigned a color; all data points within a series share that color. In the preceding example, all data for the year 2011 is displayed in blue bars; for the year 2012, in red bars. For pie charts each data point is assigned its own color.

Using the same data as before, the SetColorArray method can be used to specify a color array:

&clr_array = CreateArray(%ChartColor_Black,%ChartColor_Blue,%ChartColor_Cyan,%ChartColor_DarkGray,%ChartColor_Gray, %ChartColor_Green);

rem The preceding is equivalent to CreateArray(0,1,2,3,4,5);

&cChart.SetColorArray(&clr_array);

Image: Bar and pie charts using the specified color array

Specifying the color array results in these charts:

SetDataColor works a bit differently from SetColorArray. By using the value of a record field, SetDataColor provides more granular control of bar chart colors, in that you can vary bar color data point by data point and not by the higher level data series:

&cChart.SetDataColor(CJY_RVW_DSTRBTN.CJY_COLOR);

Image: Bar and pie charts using the specified data color values

Note that in the preceding data grid, each row of data also includes a color value. The charts that result are:

If both SetColorArray and SetDataColor are set for a chart, SetDataColor takes precedence and SetColorArray is ignored.

Setting Chart Legends

The chart property HasLegend must be set to true for a legend to appear.

&cChart.HasLegend = True;

Legend entries are determined in two ways:

• Automatically

• By using the SetLegend method to specify an array of legend entries

Image: Bar and pie charts using automatic legend generation

Here are charts that have automatically generated legend entries:

The default position for the legend is to the left of the chart. Set the chart property LegendPosition to move the legend to other locations next to the chart.

A legend entry provides a text description that explains what a color in the chart represents. The colors in the legend are sequenced in the same order as the data and colors are sequenced in the chart.

In all chart types except pie charts, the default legend entries describe the data series. In a pie chart, the default legend entries describe the data points (that is, the pie segments). In a pie chart if you have a legend, each pie chart segment is automatically labeled with the percentage it contributes to the whole.

If you use SetLegend to create legend entries, as an application developer you must ensure that the number of entries in the legend array matches exactly the number of data points that appear in your chart.

&LegendArray = CreateArray("Entry 1", "Entry 2");
&cChart.SetLegend(&LegendArray);

Image: Bar and pie charts using the specified legend array

These charts use the specified legend array:

Note that in the case of the pie chart, there were not enough legend entries in the array to account for all the segments in the pie chart. Therefore, for the pie chart, the default legend was used.

If the number of entries in the array is increased to match the number of pie slices, there are more entries than are needed for the bar chart, which produces several undesirable results.

&LegendArray = CreateArray("Entry 1", "Entry 2", "Entry 3", "Entry 4", "Entry 5", "Entry 6");
&cChart.SetLegend(&LegendArray);

Image: Bar and pie charts using a legend array that matches the number of pie segments

The bar chart displays the default legend entries (2) ignoring any additional entries that were supplied in the legend array:

If the number of entries is increased to be larger than needed for either the bar chart or the pie chart, similar undesirable results are displayed for the bar chart.

&LegendArray = CreateArray("Entry 1", "Entry 2", "Entry 3", "Entry 4", "Entry 5", 
"Entry 6", "Entry 7");
&cChart.SetLegend(&LegendArray);

Image: Bar and pie charts using a legend array that is greater than the number of pie segments

In this case, the pie chart reverts to the automatically generated legend:

If color is set by SetDataColor and the default legend is chosen, the bar chart only shows legend entries for the data series.

&cChart.SetDataColor(CJY_RVW_DSTRBTN.CJY_COLOR);
&cChart.HasLegend = True;

Image: Bar and pie charts using default legends and set data colors

The bar chart and pie charts show default legends.

If color is set by SetDataColor and the legend array is larger than needed for either chart type, the results are also undesirable.

&cChart.SetDataColor(CJY_RVW_DSTRBTN.CJY_COLOR);
&cChart.HasLegend = True;
&LegendArray = CreateArray("Entry 1", "Entry 2", "Entry 3", "Entry 4", "Entry 5", "Entry 6", "Entry 7", "Entry 8", "Entry 9", "Entry 10", "Entry 11", "Entry 12");

Image: Bar and pie charts with a legend array larger than needed by either chart

The bar chart displays the default legend entries (2) ignoring any additional entries that were supplied in the legend array.

If color is set by SetDataColor and the legend array is the size required by the pie chart, the results are also undesirable.

&cChart.SetDataColor(CJY_RVW_DSTRBTN.CJY_COLOR);
&cChart.HasLegend = True;
&LegendArray = CreateArray("Entry 1", "Entry 2", "Entry 3", "Entry 4", "Entry 5", "Entry 6");

Image: Bar and pie charts with a legend array the size required by the pie chart

The pie chart uses the specified legend array.

If color is set by SetDataColor and the legend array is the size required by the bar chart, the desired results are produced for both charts.

&cChart.SetDataColor(CJY_RVW_DSTRBTN.CJY_COLOR);
&cChart.HasLegend = True;
&LegendArray = CreateArray("Entry 1", "Entry 2");

Image: Bar and pie charts with a legend array the size required by the bar chart

The legends for both charts are correct. The bar chart uses the specified legend array; the pie chart uses the default legend.

Creating Reference Areas Using the ReferenceArea Class

The essential steps to use the ReferenceArea class are:

1. Create an instance of the ReferenceArea class in PeopleCode by using the GetReferenceArea built-in function:

   &ref1 = GetReferenceArea();

2. Set the properties on the instance of ReferenceArea class that you created.

3. Add the instance to an array of ReferenceArea instances:

   &ref_areas = CreateArray(&ref1);

   Note: For each band of color, you would add a separate instance of the ReferenceArea class to this array.

4. Pass the array into the SetReferenceArea method of the Chart class:

   &cChart.SetReferenceArea(&ref_areas);

Using Reference Areas with Charts

Image: Reference areas on a bar chart

To produce a bar chart similar to the following example that displays a reference area, you would create two instances of the ReferenceArea class:

While it is not required, you could create a user-defined PeopleCode function that returns the array of reference areas.

Function bld_ref_areas Returns array;
   &ref1 = GetReferenceArea();
   &ref1.Association = %Ref_Association_Y1;
   &ref1.Description = "1 STD from Mean";
   &ref1.ShortText = "Ref Area1";
   &ref1.IsDisplayedTextInLegend = True;
   &ref1.ReferenceAreaColor = %ChartColor_Yellow;
   &ref1.ReferenceAreaValues = CreateArray(50000, 30000);   
   &ref_areas = CreateArray(&ref1);
   Return &ref_areas;
End-Function;

Then, you associate the array returned by this function to the instance of Chart class using the SetReferenceArea method:

&cChart.SetReferenceArea(bld_ref_areas());

Creating Reference Lines Using the ReferenceLine Class

The essential steps to use the ReferenceLine class are:

1. Create an instance of the ReferenceLine class in PeopleCode by using the GetReferenceLine built-in function:

   &refln1 = GetReferenceLine();

2. Set the properties on the instance of ReferenceLine class that you created.

3. Add the instance to an array of ReferenceLine instances:

   &ref_lines = CreateArray(&refln1);

   Note: For each reference line, you would add a separate instance of the ReferenceLine class to this array.

4. Pass the array into the SetReferenceLine method of the Chart class:

   &cChart.SetReferenceLine(&ref_lines);

Using Reference Lines with Charts

Image: Reference lines on a bar chart

To produce a chart similar to the following example that displays a reference line, you would create two instances of the ReferenceLine class:

While it is not required, you could create a user-defined PeopleCode function that returns the array of reference lines.

Function bld_ref_lines() Returns array;
   &refln1 = GetReferenceLine();
   &refln1.Association = %Ref_Association_Y1;
   &refln1.Description = "Average";
   &refln1.ShortText = "Avg";
   &refln1.IsDisplayedTextInLegend = False;
   &refln1.ReferenceLineLocation = %Ref_Back;
   &refln1.ReferenceLineColor = %ChartColor_Red;
   &refln1.ReferenceLineValue = CJY_CHRT_REF_WK.CJY_AMT;
   &reflines = CreateArray(&refln1);
   Return &reflines;
End-Function;

Then, you associate the array returned by this function to the instance of Chart class using the SetReferenceLine method:

Function bld_chrt();
   &cChart = GetChart(CJY_CHRT_REF_WK.CJY_CHRT1);
   &cChart.Reset();
   &cChart.SetData(Record.CJY_SLRY);
   &cChart.SetDataXAxis(CJY_SLRY.CJY_NM);
   &cChart.setDataYAxis(CJY_SLRY.CJY_SLRY);
   &cChart.SetReferenceLine(bld_ref_lines());
End-Function;

Using the Series Class with the Chart Class

The essential steps to use the Series class are:

1. Specify the field representing the data series for the chart.

   &cChart.SetDataSeries(RECORD.FIELD);

2. Create an instance of the Series class in PeopleCode by using the GetSeries built-in function:

   &series1 = GetSeries();

3. Set the Name and Type properties on each instance of the Series class that you created.

   Note: The value of the Name property must match exactly the value of a member in the data series as specified by either the SetDataSeries method or set by the SetSeriesLabel method.

4. Add the instance to an array of Series instances:

   &all_series = CreateArray(&series1);

   Note: Add a separate instance of the Series class to this array for each member of the data series that you want to override the default chart type. Members not explicitly added to this array will inherit the default chart type. Alternatively, you can use the %SeriesType_Inherit constant to specify that a data series member inherit the default chart type.

5. Pass the array into the SetSeries method of the Chart class:

   &cChart.SetSeries(&all_series);

Overriding the Chart Type Using the Series Class

Image: A bar chart displaying two additional chart types

In the following example of a bar chart, two of the five series are displayed as different chart types:

To produce a bar chart similar to the preceding example that uses a different chart type for the first and the fourth of five series, you would create two instances of the Series class. In this example, the Name property matches the value of the field as specified by the SetDataSeries method:

Component Chart &oChart;

&oChart = GetChart(QE_JET_CHARTWRK.QE_JET);
&oChart.Reset();
&oChart.Type = %ChartType_2DBar;

&oChart.SetData(Record.QE_CHART_NPARKS);

&oChart.SetDataYAxis(QE_CHART_NPARKS.QE_VISITORS);
&oChart.SetDataXAxis(QE_CHART_NPARKS.QE_YEARS);

&oChart.SetDataSeries(QE_CHART_NPARKS.QE_PARKNAME);

&oChart.XAxisTitle = "Years";
&oChart.YAxisTitle = "No. of visitors";
&oChart.MainTitle = "Visiting National Parks";

&oChart.HasLegend = True;
&oChart.LegendPosition = %ChartLegend_Left;

Local Series &S1, &S2;

&S1 = GetSeries();
&S1.Name = "YELLOWSTONE";
&S1.Type = %SeriesType_Line;

&S2 = GetSeries();
&S2.Name = "ARCHES";
&S2.Type = %SeriesType_Area;

&oChart.SetSeries(CreateArray(&S1, &S2));

Using the ToolTipLabel Class with the Chart Class

The essential steps to use the ToolTipLabel class are:

1. Create an instance of the ToolTipLabel class in PeopleCode by using the GetToolTip built-in function:

   &label1 = GetToolTip();

2. Set the ToolTipLabelType and ToolTipLabelValue properties on each ToolTipLabel object that you created.

3. Add the object to an array of ToolTipLabel objects:

   &tooltip_labels = CreateArray(&label1, &label2);

4. Pass the array into the SetToolTipLabels method of the Chart object:

   &cChart.SetToolTipLabels(&tooltip_labels);

Creating Custom Tooltips

Image: Custom tooltips

To create custom tooltips similar to the following example, you would create three instances of the ToolTipLabel class.

In the preceding example, the custom tooltip displays the x-axis data (%TooltipLbl_X), y-axis data (%TooltipLbl_Y), and the data series (%TooltipLbl_Series). The following PeopleCode program would generate these custom tooltips:

/* Declare and instantiate a chart object */
Component Chart &QEChart;
Component TooltipLabel &label1, &label2, &label3;
Component array of TooltipLabel &tooltip_labels;

&QEChart = GetChart(QE_CHART_T2_CHR.QE_CHART_T2_CHRTFL);
&QEChart.Reset();

/* Set the chart parameters for chart descriptions */
&QEChart.Type = %ChartType_2DBar;
&QEChart.MainTitle = "Shoes sales data for North America";
&QEChart.XAxisTitle = "Product Category";
&QEChart.YAxisTitle = "Sales in Millions";
&QEChart.HasLegend = True;

/* Set the chart data record and specify x-axis, y-axis, and series data */
&QEChart.SetData(Record.QE_CHART_T1_PRO);
&QEChart.SetDataXAxis(QE_CHART_T1_PRO.QE_CHART_T1_PROD);
&QEChart.SetDataYAxis(QE_CHART_T1_PRO.QE_CHART_T1_SALES);
&QEChart.SetDataSeries(QE_CHART_T1_PRO.QE_CHART_T1_REGION);
&label1 = GetToolTip();
&label1.ToolTipLabelType = %TooltipLbl_X;
&label1.ToolTipLabelValue = "Product";
&label2 = GetToolTip();
&label2.ToolTipLabelType = %TooltipLbl_Series;
&label2.ToolTipLabelValue = "Region";
&label3 = GetToolTip();
&label3.ToolTipLabelType = %TooltipLbl_Y;
&label3.ToolTipLabelValue = "Sale (M)";
&tooltip_labels = CreateArray(&label1, &label2, &label3);
&QEChart.SetToolTipLabel(&tooltip_labels);