Charting Examples

Placing a Chart Control on a Page

In Application Designer, create a new page.

Select Insert, Chart and draw a rectangle to represent the area the chart will occupy. The chart can be any size, and you can have more than one chart on a page.

Place the page on a component and register the component.

Associating the Chart Control with a Record Field

Image: Chart Properties dialog box

Each chart on a component must be associated with a unique field. Double-click the chart control to access the Chart Properties dialog box and enter a record name and field name.

The chart field has no special requirements. Its only purpose is to provide a reference to the field in PeopleCode.

This sample chart uses a derived/work record named DOC_CHRT_WRK that is dedicated to this purpose.

Creating the Chart Data Record

The chart needs either a record or a rowset to serve as the data source. This sample chart uses a record. See the Chart class SetData method for details about using a rowset.

See SetData.

Image: Example of a chart data record

At a minimum, the record must have fields for the x-axis data and the y-axis data. Optionally, the record can have fields for series data, chart color, and glyph size.

The record must be available in the component buffer at runtime. You can use a database record that is already part of your application or you can use a derived/work record or a component rowset that you populate at runtime. For greatest control, you will normally populate your record or rowset at runtime.

For the sample chart, place the record on a grid on a second page on the sample component. This placement gives you the opportunity to experiment with the data.

Image: Example of a page definition with chart data grid

Your chart data record must be placed at level 1 on the same component as the chart so that the data is available in the component buffer at runtime. In your application, you can hide the grids or scroll areas that hold the records. For the sample chart, you will keep the grid visible so you can enter sample data.

Adding PeopleCode to Instantiate a Chart Object

This example instantiates a chart object using the Chart class, so it can be used to create bar charts, line charts, pie charts, and so on. Other examples in this section demonstrate how to create charts based on the Gantt class, OrgChart class, and RatingBoxChart class.

See Creating a Gantt ChartCreating a Gantt Chart, Creating a Rating Box Chart.

Add this PeopleCode to the Activate event on the page:

/* Declare and instantiate a chart object */
Component Chart &cChart;

&cChart = GetChart(DOC_CHRT_WRK.DOC_CHRT_FLD);

Chart PeopleCode is commonly placed on the Activate event, but it can be placed on any appropriate event. You could, for instance, execute the chart PeopleCode from a FieldChange event associated with a push button.

Setting the Data Source

The SetData method takes either a record or a rowset as an argument. In general, specify a record or component rowset when building a chart from page data and a standalone rowset when building a chart using an iScript.

In this example, the PeopleCode sets Product as the series data and sets Region to the x-axis, so that in a bar chart products will be grouped along the x-axis by region. In a line chart, each series is represented by a line. Sales figures are charted on the y-axis.

/* Set the chart data record and specify x-axis, y-axis, and series data */

&cChart.SetData(Record.DOC_CHRT_SLSREC);
&cChart.SetDataXAxis(DOC_CHRT_SLSREC.DOC_CHRT_RGN);
&cChart.SetDataYAxis(DOC_CHRT_SLSREC.DOC_CHRT_SALES);

See SetData, SetDataSeries, SetDataXAxis, SetDataYAxis, Creating a Chart Using an iScript.

Viewing the Page in the Browser

Image: Chart class chart with no data

This is the most basic Chart class chart. It has no data and only the default y-axis.

Adding Data for the Chart

Add the following data to the chart:

Image: A simple bar chart

This bar chart is generated by the example code and data:

This chart graphs sales on the y-axis (the vertical axis) and regions on the x-axis (the horizontal axis).

When the data for the chart is grouped according to values, a set of data representing a single value is called a series. For instance, if a chart shows sales for different products in each region, then the set of data for each product is a series.

At this point, the chart has only one series, so you do not need to set the series record field.

Specify the Series Data

If you want to graph more than one product on your chart, you need to specify the source of the series data.

For example, add the products shown in this table to your data:

Add this PeopleCode to set the series record field:

&cChart.SetDataSeries(DOC_CHRT_SLSREC.DOC_CHRT_PRDCT);

Image: Default 2D bar chart with products as series

The resulting chart is a default 2D bar chart with bars for each region grouped by series:

The chart has four series:

• Footballs

• Rackets

• Shoes

• Tents

Each series shows four regions along the x-axis:

• Arizona

• California

• Oregon

• Washington

Sales values appear against the y-axis as bar height.

The chart uses the default colors.

Specifying Chart Colors

If you do not want to use the default colors, you need a column containing the colors for each bar. Typically, the bars in a series are colored alike.

Add the following PeopleCode to your program to set the colors for your chart:

/* Associate color field with chart */
&cChart.SetDataColor(DOC_CHRT_SLSREC.DOC_CHRT_COLOR);

Adding Text Elements

The following PeopleCode adds these elements to your chart:

• Title

• Legend

• Y-axis title

• X-axis title

/* Set title and legend properties */
&cChart.MainTitle = "Recreational Product Sales by Region";
&cChart.HasLegend = True;
&cChart.LegendPosition = %ChartLegend_Right;

/* Set axis text properties */
&cChart.XAxisTitle = "Region";
&cChart.YAxisTitle = "Sales";

Image: Sample bar chart with custom colors, a main title, axis titles, and a legend

This is the resulting chart:

Reviewing the Complete Program

The PeopleCode for this bar chart has been presented in snippets. Here is the complete program that produced the chart:

/* Declare and instantiate a chart object */
Component Chart &cChart;

&cChart = GetChart(DOC_CHRT_WRK.DOC_CHRT_FLD);

/* Set the chart data record and specify x-axis, y-axis, and series
data */

&cChart.SetData(Record.DOC_CHRT_SLSREC);
&cChart.SetDataXAxis(DOC_CHRT_SLSREC.DOC_CHRT_RGN);
&cChart.SetDataYAxis(DOC_CHRT_SLSREC.DOC_CHRT_SALES);
&cChart.SetDataSeries(DOC_CHRT_SLSREC.DOC_CHRT_PRDCT);

/* Associate color field with chart */
&cChart.SetDataColor(DOC_CHRT_SLSREC.DOC_CHRT_COLOR);

/* Set title and legend properties */
&cChart.MainTitle = "Recreational Product Sales by Region";
&cChart.HasLegend = True;
&cChart.LegendPosition = %ChartLegend_Right;

/* Set axis text properties */
&cChart.XAxisTitle = "Region";
&cChart.YAxisTitle = "Sales";

Other Modifications

The remainder of this section shows the effects of modifying other aspects of your chart.

Changing X-Axis and Series Values

&cChart2.SetDataXAxis(DOC_CHRT_SLSREC.DOC_CHRT_PRDCT);
&cChart2.SetDataSeries(DOC_CHRT_SLSREC.DOC_CHRT_RGN);

&cChart2.MainTitle = "Recreational Product Sales by Product";
&cChart2.XAxisTitle = "Product";

Image: Bar chart with series set to region

To group sales by product instead of by region, switch the series and the x-axis. You will also need to reorder colors to correspond to regions instead of products:

Axis Properties

Image: Bar chart with negative values

If your chart has negative values, the bars automatically extend below the x-axis:

If you want to remove the tick marks from the x- or y-axis, you need to specify an empty array for the SetXAxisLabels or SetYAxisLabels methods.

The following example removes the tick marks from the y-axis:

Local array of string &Arr;

&Arr = CreateArray("");
&Chart.SetYAxisLabels(&Arr);

If you set the x-axis labels to an empty array to remove the ticks, you must be plotting a single series on the chart because labels are automatically generated for each series if you do not provide them.

See SetXAxisLabels, SetYAxisLabels.

You can also use the XAxisMin, XAxisMax, YAxisMin, YAxisMax, and other axis properties to control the appearance of the axes.

See XAxisLabelOrient, YAxisLabelOrient, YAxisMax, YAxisMin

Chart Class Chart Types

Use the Type property to set the chart type.

2D Bar Chart

&cChart.Type=%ChartType_2DBar;

Image: 2D bar chart

The default Chart class chart type is a 2D bar chart:

The following examples show the various chart types using the same data. Each example gives the PeopleCode snippet that creates that chart type.

For a complete list of all Chart class chart types, see Chart class Type property.

See Type.

The Charting Examples section provides other examples of PeopleCode for charts using Gantt class, OrgChart class, and RatingBoxChart class at the end of the chapter.

See Creating a Gantt ChartCreating a Gantt Chart, Creating a Rating Box Chart.

Horizontal Bar Chart

Use this line of code to specify a horizontal bar chart:

&cChart.Type = %ChartType_2DHorizBar;

Image: Horizontal bar chart

This example illustrates a horizontal bar chart:

Stacked Bar Chart

With a the stacked bar chart, you can place a different emphasis on the same data. The stacked column shows total sales per region as well as the product segments that contribute to the total.

Use this line of code to specify a stacked bar chart:

&cChart.Type = %ChartType_2DStackedBar;

Image: Stacked bar chart

This example illustrates a stacked bar chart:

Horizontal Stacked Bar Chart

Use this line of code to specify a horizontal stacked bar chart:

&cChart.Type = %ChartType_2DHorizStackedBar;

Image: Horizontal stacked bar chart

This example illustrates a horizontal stacked bar chart:

Percent Bar Chart

A percent bar is similar to a stacked bar, but the segments of each bar add up to 100. The segments show the proportional contribution of each product to total sales.

Use this line of code to specify a stacked percent bar chart:

&cChart.Type = %ChartType_2DPercentBar;

Image: Percent bar chart

This example illustrates a percent bar chart:

Horizontal Percent Bar Chart

Use this line of code to specify a horizontal percent bar chart:

&cChart.Type = %ChartType_2DHorizPercentBar;

Image: Horizontal percent bar chart

This example illustrates the fields and controls on a horizontal percent bar chart:

Line Chart

A line chart is useful for showing changes and trends over time or across categories.

Use this line of code to specify a line chart:

&cChart.Type = %ChartType_2DLine;

Image: Line chart

This example illustrates a line chart:

Overlay Chart

You can overlay one chart on top of another to compare two different but related sets of data. The following chart uses a second set of data, showing average temperature for each region.

Use the OLType property to specify whether the overlay is a line chart or a histogram.

Add this PeopleCode to the PeopleCode for your bar chart to create 2D line chart overlay:

/* Create Overlay */
&cChart3.SetOLData(Record.DOC_CHRT_OLREC);
rem &cChart.SetOLDataSeries(DOC_CHRT_OLREC.SC_CHART_SERIES);
&cChart3.SetOLDataXAxis(DOC_CHRT_OLREC.DOC_CHRT_RGN);
&cChart3.SetOLDataYAxis(DOC_CHRT_OLREC.DOC_CHRT_SALES);
&cChart3.OLType = %ChartType_2DLine;

Image: Overlay chart

This example illustrates a 2D line chart overlay on a vertical bar chart:

Scatter Chart

Use this line of code to specify a scatter chart:

&cChart.Type = %ChartType_2DScatter;

A scatter chart compares number pairs. Each pair is plotted against the horizontal x-axis and the vertical y-axis. The data values are scattered across the chart. XY scatter charts are good for showing comparisons of numbers, such as scientific or statistical data, where several measurements need to be plotted on a single chart.

A scatter chart is a true XY chart, meaning that the x-axis is numeric. The IsTrueXY property is automatically set to True.

For example, this sample data could be used to make an XY scatter chart:

You use this code snippet to make a scatter chart:

&cChart5.Type = %ChartType_2DScatter;
&cChart5.SetData(Record.DOC_CHRT_XYDATA);
&cChart5.SetDataXAxis(DOC_CHRT_XYDATA.DOC_CHRT_X);
&cChart5.SetDataYAxis(DOC_CHRT_XYDATA.DOC_CHRT_Y);

Image: Scatter chart

This example illustrates the scatter chart for the preceding data:

Bubble Chart

A bubble chart is a special type of scatter chart.

If you add a third data set, the z-axis, to a scatter chart, you can create a bubble chart, which uses the size of the markers to represent a third dimension of numeric data.

You can also set annotations for scatter charts and bubble charts.

This chart example uses Age to determine the size of the bubble markers on the chart and Name to set the annotations:

&cChart6.Type = %ChartType_2DBubble;
&cChart6.SetData(Record.DOC_CHRT_XYDATA);
&cChart6.SetDataXAxis(DOC_CHRT_XYDATA.DOC_CHRT_X);
&cChart6.SetDataYAxis(DOC_CHRT_XYDATA.DOC_CHRT_Y);
&cChart6.SetDataZAxis(DOC_CHRT_XYDATA.DOC_CHRT_AGE);
&cChart6.SetDataAnnotations(DOC_CHRT_XYDATA.DOC_CHRT_LASTNAME);

Image: Bubble chart

This example illustrates the bubble chart for the preceding data:

Pie Chart

A pie chart shows comparisons within a single set of values, and it shows how parts contribute to a whole. It is an ideal chart type to display the contribution of each region to an annual sales total.

A pie chart ignores the series and only plots x-axis data against y-axis values. Our original bar chart has four regions times four products, resulting in 16 XY pairs. A pie chart with all of those slices would be confusing and not helpful. Instead, suppose you want to show just the data for tents, which are in rows 13–16. You can use a combination of the DataWidth and DataStartRow properties to select which rows to display.

You can make a pie chart showing only rows 13–16 by adding this snippet of code:

&cChart.DataWidth = 4;
&cChart.DataStartRow = 13;
&cChart.Type = %ChartType_2DPie;

Image: 2D pie chart

This example illustrates a 2D pie chart generated from a portion of the rowset:

Exploded Pie Chart

Use the SetExplodedSectorsArray Chart class method to specify the sectors to explode. Sectors correspond to rows of data used by the pie chart. Sector 1 is the first row of data, or the row specified with the DataStartRow chart class property, if it is used, and so on.

The following snippet of code explodes sectors 1 and 3:

Local array of number &ExplodedArray;
&ExplodedArray = CreateArray(1,3);
&cChart.SetExplodedSectorsArray(&ExplodedArray);

Image: Exploded pie chart

This example illustrates an exploded pie chart:

See the SetExplodedSectorsArray property.

3D Pie Chart

Use this line of code to specify a 3D pie chart:

&cChart.Type = %ChartType_3DPie;

Image: 3D Pie Chart

This example illustrates a 3D pie chart.

Adding Drilldown

If you set the property IsDrillable to True and add FieldChange PeopleCode to your chart, your user can get more information by clicking a chart data element—a bar, line segment, data point, or pie slice.

For a simple example, add this PeopleCode to the FieldChange event on the y-axis field:

MessageBox(0, "", 0, 0, "Sales for " | DOC_CHRT_SLSREC.DOC_CHRT_PRDCT | " in " | DOC_CHRT_SLSREC.DOC_CHRT_RGN | " = " | DOC_CHRT_SLSREC.DOC_CHRT_SALES | "");

And add this code to the page Activate event for your pie chart:

&cChart.IsDrillable = True;

Image: Example of drill-down triggering PeopleCode with MessageBox

When the user clicks the Arizona slice of the pie chart, this message appears:

Current context provides the values for fields in the current row in the component buffer. You can use drilldown with your chart data fields along with any other data in the component buffer to accomplish anything FieldChange PeopleCode is capable of.

If the bars on a bar chart are too narrow, a user may not be able to click them. Sometimes, a few bars on a chart are affected, sometimes all of the bars cannot be clicked. The workaround is to put fewer bars on your chart or to make your chart bigger so that each bar is wider.

See IsDrillable.

Using the Other Charting Classes

In addition to the all the charts you can create with the Chart class, you can create specialized charts using the Gantt class, the OrgChart class, and the RatingBoxChart class.

You follow the same initial steps to create these specialized charts as you do for the Chart class chart types. The PeopleCode programs to set the data and properties are similar as well, but Gantt charts, organization charts, and rating box charts use data differently and interact with the user in different ways than do the Chart class charts.

See Creating a Gantt ChartCreating a Gantt Chart, Creating a Rating Box Chart.

PeopleCode for the Rating Box Chart Example

Complete these steps to create a rating box chart:

1. Prepare the data for the chart.

   Typically, write PeopleCode in an event such as PreBuild to populate a rowset with the data you want to display in the rating box chart.

   Component Rowset &rs, &rsRatingBox;
   Component RatingBoxChart &rbRatingBoxChart;
   
   /* the record QE_RATEBOX_DATA has the data for the RATING BOX  chart */
   &rs = CreateRowset(Record.QE_RATEBOX_DATA);
   &rs.Fill("Where QE_RATEBOX_TC=:1", QE_RATEBOX_TC.QE_RATEBOX_TC.Value);
   
   /* Get the grid on the page for the node data and initalize to nulls */
   &rsGrid = GetLevel0()(1).GetRowset(Scroll.QE_RATEBOX_TC);
   &rsGrid.Flush();
   
   /* Copy data from database table, QE_RATEBOX_DATA, to the
   level 1 component rowset associated with the component derived working
   record QE_RATEBOX_DR */
   
   &rs.CopyTo(&rsGrid, Record.QE_RATEBOX_DATA, Record.QE_RATEBOX_DR);
   

2. Define the RatingBoxChart.

   Add PeopleCode in an event such as Activate.

   Instantiate a RatingBoxChart object using the GetRatingBoxChart built-in function to reference the page control field of the chart.

   Component Rowset &rs, &rsGrid;
   Component RatingBoxChart &rbRatingBoxChart;
   
   &rbRatingBoxChart = GetRatingBoxChart(QE_CHART_DUMREC.QE_CHART_FIELD);
   

3. Set the required display properties for the chart.

   &rbRatingBoxChart.XaxisBoxNum = 3;
   &rbRatingBoxChart.YaxisBoxNum = 3;
   &rbRatingBoxChart.PopUpWidth = 200;
   &rbRatingBoxChart.PopUpHeight = 200;
   &XAxisArray = CreateArray("Low", "Medium", "High");
   &YAxisArray = CreateArray("Low", "Medium", "High");
   
   &rbRatingBoxChart.SetXAxisLabels(&XAxisArray);
   &rbRatingBoxChart.SetYAxisLabels(&YAxisArray);

4. (Optional) Specify other values for the chart display properties.

   If you do not specify these properties, the following default value will be used:

   &rbRatingBoxChart.IsDragable = True;
   &rbRatingBoxChart.BoxMaxDisplayItems = 3;
   &rbRatingBoxChart.NDMaxDisplayDescLength = 25;
   &rbRatingBoxChart.ShowNodeDescription = True;
   &rbRatingBoxChart.GridLineType = %ChartLine_Solid;
   &rbRatingBoxChart.XAxisTitle = "Performance";
   &rbRatingBoxChart.YAxisTitle = "Potential";
   &rbRatingBoxChart.NDMaxDisplayDescLength = 15;
   &rbRatingBoxChart.BoxMaxDisplayItems = 5;
   
   &rbRatingBoxChart.Height = 400;
   &rbRatingBoxChart.Width = 400;
   &rbRatingBoxChart.ShowNodeDescription = true;
   &rbRatingBoxChart.GridLineType=%ChartLine_Solid;
   &rbRatingBoxChart.IsDragable = True;
   &rbRatingBoxChart. BoxMaxDisplayItems= 1;
   &rbRatingBoxChart. NDMaxDisplayDescLength = 50;
   

5. (Optional) Assign style class names for the chart and x- and y-axis title and labels.

   If you do not specify a style class name, the PeopleTools default style sheet is used.

   &rbRatingBoxChart.Style = "PSCHARTDEFAULT";
   &rbRatingBoxChart.XAxisTitleStyle = "PT_RATBOX_XTTL";
   &rbRatingBoxChart.YAxisTitleStyle = "PT_RATBOY_YTTL";
   &rbRatingBoxChart.XAxisLabelStyle = "PT_RATBOX_XAXIS";
   &rbRatingBoxChart.YAxisLabelStyle = "PT_RATBOX_YAXIS";
   

6. (Optional) Specify title and legend properties.

   &rbRatingBoxChart.MainTitle = "Development Division";
   &rbRatingBoxChart.MainTitleStyle="PT_RATBOX_TITLE"
   &rbRatingBoxChart.HasLegend = True;
   &rbRatingBoxChart.LegendPosition = %ChartLegend_Bottom;
   &LegendArray = CreateArray("Architect", "Engineer", "Director", "Manager",
      "Senior Director", "Vice-President");
   &LegendImgArray = CreateArray("PT_ACECUBE", "PT_WF_PERSON","PT_STATUS_ALERT_ICN",
      "PT_STATUS_ASSIGNED_ICN", "QE_SUCCSORGCHART", "QE_KPERSON");
   &rbRatingBoxChart.SetLegend(&LegendArray);
   &rbRatingBoxChart.SetLegendImg(&LegendImgArray);
   

7. Set the node data rowset and record.

   The chart refreshes when the SetRBNodeData method is called.

   /* Set the node data rowset and the node record. */
   &rbRatingBoxChart.SetRBNodeData(&rsGrid);
   &rbRatingBoxChart.SetRBNodeRecord(Record.QE_RATEBOX_DR);
   

8. Add FieldChange PeopleCode on the fields PTXASISRATINGS and PTYAXISRATINGS if you want to perform other logic after the drag and drop operation.

   This example shows a call to the SetRBNodeData function to redraw the chart the user changes the values in either of these two fields in the component:

   /* FieldChange PeopleCode for fields PTXAXISRATINGS and PTYAXISRATINGS*/
   &rbRatingBoxChart.SetRBNodeData(&rsGrid);