Skip to main content

This is documentation for Caché & Ensemble.

For information on converting to InterSystems IRIS, see the InterSystems IRIS Adoption Guide and the InterSystems IRIS In-Place Conversion Guide, both available on the WRC Distributions page (login required).

Previous sectionNext section

Zen Charts

Zen reports callback charts use the same syntax as Zen pages to display charts. Callback charts are defined in the package %ZEN.Report.Display.COSChart, and all of the chart element names begin with the letter “c”, for example, <cbarChart>. See “Using Callback Charts in Zen Reports”. Syntax described in sections “Types of Chart,” “Chart Layout, Style, and Behavior” and “Chart Axes” applies equally well to charts in Zen pages and callback charts in Zen reports. XPath charts is an older implementation of charting in Zen reports which uses syntax different from Zen pages. See “Using XPath Charts in Zen Reports”.

Techniques for providing data for charts in Zen pages are different from both callback charts and XPath charts in Zen reports. See “Providing Data for Zen Page Charts” in this book and “Providing Data for Zen Report Charts” in the book Using Zen Reports.

The base chart class %ZEN.SVGComponent.chart defines the data, grid (axes and scales), styles, and legend used by charts. You can think of charts as occupying a virtual coordinate space that measures 100 units by 100 units. Internally, charts are plotted in terms of pixels, which allows you to specify size and positioning parameters in pixels as well as in terms of the virtual coordinate space. See “Specifying Size and Position.” Within the total space occupied by the chart, there is a smaller plot area where the chart plots the data. Margins define the space around the plot area. Generally you use these margins as space in which to display the labels and legend for the chart.

This chapter begins by introducing the various types of chart, so that you can look at some visual examples and think about the items you want to display on the Zen page, before reading the exact details of how to use a specific type of chart. Chapter topics appear in this order:

Types of Chart

This topic describes and illustrates the types of chart that you can place on the Zen page. Each description includes the unique attributes that define that type of chart. For attributes that all charts share in common, see the sections “Providing Data for Zen Page Charts” and “Chart Layout, Style, and Behavior.”

Zen offers the following built-in chart types:

Bar Charts

Bar Chart
generated description: svg barchart

<barChart> has the following attributes:

Bubble Charts

If you supply a third series, the chart uses that data to draw the radius of each bubble. Values in the radius series are scaled and multiplied by the value of the radius property.

The following figure shows a chart with x, y and radius data series. Note how the default partial transparency of the bubbles lets you see the shapes even when they overlap. The property opacity controls this characteristic. Note also that in this example, the value of showQuadrant is true, so the chart area is divided into quadrants.

Radius Data Series
generated description: svg bubblechart radius

You can supply up to two additional data series. The fourth series determines how colors are applied to the data bubbles, and the fifth controls opacity of bubbles.

Values in the fourth, or color data series can be any arbitrary data. The chart establishes color categories for each new value encountered in the series, and assigns the colors to corresponding bubbles on the chart. The chart uses the colors that are currently in effect, see seriesColors and seriesColorScheme.

The following code fragment shows the part of an ongetData handler that sets up a color data series.

/// Callback to provide data for bubble chart.
ClientMethod getBubbleChartData(series) [ Language = javascript ]
{
  var chart = zenPage.getComponentById('chart');
  var data = new Array(chart.seriesSize);

  // ...code omitted...

  if (series == 3) // color
  {
    for (var i = 0; i < chart.seriesSize; i++) 
    {
      data[i] = (i%3)?"group 1":"group 2"
    }  
  }
  return data;
}
Copy code to clipboard

The following figure shows the resulting chart, with colors applied to randomly generated data. Note that in this chart, the value of showRegression is true, so the chart contains a computed linear regression line, and showQuadrant is false, so the chart does not show quadrants. The property lineStyle provides a style specification for the regression line.

Color Data Series
generated description: svg bubblechart color

Values in the fifth, or opacity data series can be any arbitrary data. Values in the opacity series are scaled and multiplied by the value of the opacity property. Values are not normalized, so a large range in values can result in the smallest values being driven to 0 and becoming invisible.

/// Callback to provide data for bubble chart.
ClientMethod getBubbleChartData(series) [ Language = javascript ]
{
  var chart = zenPage.getComponentById('chart');
  var data = new Array(chart.seriesSize);

  // ...code omitted...    

  if (series == 4) // opacity
   {
     data[1] = 1;
     data[2] = 4;
     data[3] = 1;
     data[4] = 1;
     data[5] = 4;
     data[6] = 1;
     data[7] = 4;
     data[8] = 4;
     data[9] = 4; 
   }
   return data;
}
Copy code to clipboard

The following figure shows the resulting chart, with opacity applied to random generated data. Note also that the quadrants have been modified by setting the property xCenterValue, and the properties upperRightStyle and lowerLeftStyle have been used to modify the quadrant colors.

Opacity Data Series
generated description: svg bubblechart opacity

<bubbleChart> has the following attributes:

Bullseye Charts

Bullseye Chart
generated description: svg bullseyechart

Bullseye charts are often used in situations where the largest circle shows the entire data set, the next circle shows data items that meet some relevant set of criteria, and the next circle shows data items that meet additional criteria. For example, if the largest circle shows the total number of patients in a study, the next circle might show patients with diabetes, and the smallest diabetic patients undergoing a specific treatment.

Combo Charts

Combo Chart Displaying Area, Bar and Line Charts
generated description: svg combochart abl

You can use other chart elements to plot multiple data series using a single type of chart, but <comboChart> sometimes offers advantages. For example, you can chart multiple filled line charts using <lineChart>, but <comboChart> may be a better choice, because it renders area charts with partial transparency, so all of the chart areas are visible, even when they overlap.

Combo Chart Displaying Four Area Charts
generated description: svg combochart areas

You can also use the attribute seriesTypes to display one of the data series as target lines. The following figure shows a chart where the fourth data series supplies target lines.

Combo Chart with Target Lines
generated description: svg combochart target

<comboChart> supports the following attributes:

Difference Charts

  1. The first series provides a set of reference data values.

  2. The second data series provides values that you want to compare to the reference data set.

The <diffChart> shades the area between the two series using the color of the second data series. To further distinguish between the series, the chart draws a line representing the reference series across the shaded area of the chart. This line uses the color of the first, or reference data series, and can take additional styling from the refLineStyle attribute. <diffChart> does not support chartPivot.

The following figure shows a difference chart:

Difference Chart
generated description: svg diffchart

For comparison, the following figure shows the same data plotted as a filled line (area) chart:

Area Chart
generated description: svg areachart

<diffChart> has the following attributes:

High/Low Charts

High/Low Chart
generated description: svg hilowchart
  1. A series of high values sets the top (right) limit of each bar.

  2. A series of low values sets the bottom (left) limit of each bar.

  3. (Optional) The “closing” values. The chart places a marker on each bar at these values.

Each low value is assumed to be smaller than its corresponding high value. Each closing value is assumed to be between its corresponding high and low values. The chart uses its first seriesColors value to plot all bars and marker. It ignores the colors provided for the other series.

<hilowChart> has the following attributes:

Line Charts

Line Chart
generated description: svg linechart

<lineChart> has the following attributes:

Percent Bar Charts

You can use ongetLabelX to provide labels for the bars, and seriesNames to provide labels for the legend, matching names to colors by order in the series.

Percent Bar Chart
generated description: svg percentbarchart

<percentbarChart> has the following attributes:

Pie Charts

A <pieChart> that plots the items in a single data series displays a circle with radial slices representing items in the series. The chart adjusts the size of each slice to be proportional to the contribution of that item to the total. Note that the end user can rotate the pie chart with click and drag gestures in the browser.

Pie Chart with One Data Series
generated description: svg piechart1series

<pieChart> has the following attributes:

plotBy

The <pieChart> plotBy attribute controls how Zen generates a pie chart from the data provided. You may actually provide multiple series to the <pieChart>. The chart processes all the data series to create one series, and then displays that series as slices in the chart. plotBy options are as follows.

  • "items" – plot a slice for every item in this chart's data.

  • "series" – plot a slice for every data series in this chart's data.

  • "both" – plot a slice for each item within each data series, which means that the chart contains seriesCount * seriesSize slices.

  • "auto" – automatically select the appropriate way to display data based on how many data series and items are present.

Pie Charts by Items

When the value of plotBy is "items", a <pieChart> plots one slice for every item within the data series. If you provide multiple data series to an "items" pie chart, each slice of the pie represents the total of a particular item, summed across all of the data series in the chart.

The following conceptual figure shows how three data series, each containing six items, would generate an six-slice pie chart. Each slice represents the sum of the values for that item provided by the three series.

How Zen Plots Pie Charts by Item
generated description: svg piechart items

When the value of plotBy is "items", labels for the slices are treated as <yAxis> labels. This means you cannot specify them directly using a chart attribute such as seriesNames. Labels are provided by a %ZEN.Auxiliary.dataController, if present, or you can provide an onGetLabelY event handler to get the label values.

Pie Charts by Series

When the value of plotBy is "series", multiple series are in use. The <pieChart> plots one slice for every data series, so the number of slices in the pie chart is seriesCount. Each slice represents the sum of all the items within one of the series. The seriesNames attribute provides the labels for the slices, and for the legend.

The following conceptual figure shows how three data series, each containing six items, generate a three-slice pie chart. Each slice represents the sum of the eight items in that series.

How Zen Plots Pie Charts by Series
generated description: svg piechart series
Pie Charts by Both Items and Series

When the value of plotBy is "both", multiple series are in use. The <pieChart> plots one slice for every item in every data series, so there are seriesCount times seriesSize slices. The base color for each slice is the associated series color. Alternating slices use dark and normal shades of this color. The chart legend displays series names; the seriesNames attribute provides these labels. The slices display item names; the labels are provided by an onGetLabelY event handler, or a data controller.

The following pie chart example compares three series (Products, Services, and Training), each of which has data items in four categories (America, Asia, Europe, and Africa). The chart has twelve slices.

Zen Pie Chart from Both Items and Series
generated description: svg piechart both

Scatter Diagrams

XY or Scatter Chart
generated description: svg xychart
  1. The first data series provides the x values

  2. The second data series provides correlated y values

  3. Any additional data series are plotted as y values correlated to the x values provided by the first series.

The result is that an <xyChart> always displays one less plot than its number of data series.

<xyChart> has no unique attributes. <xyChart> has the same general-purpose attributes as any Zen chart. For descriptions, see the sections “Providing Data for Zen Page Charts” and “Chart Layout, Style, and Behavior.” An <xyChart> always has markersVisible and plotToEdge set to true. Generally you need to manipulate some of the other chart attributes to produce the desired results. For example:

  • The seriesCount value must always be one more than the number of plots you want to display. This leaves room for the first, x-value series.

  • The first data series is not plotted, so the <xyChart> applies series settings beginning with the second series, not the first. For example:

    • The seriesColors list applies to the second, third, and successive series.

    • The seriesNames list applies to the second, third, and successive series.

    • The markerShapes list applies to the second, third, and successive series.

  • A scatter diagram does not appear “scattered” unless you hide the lines between the markers. To do this, set the plotStyle for an <xyChart> as follows:

    plotStyle="stroke:none;". This is a better approach than setting plotStyle="stroke-width: 0;", because some SVG implementations render a very thin line, even when stroke-width is set to 0.

<xyChart> has the following attributes:

Tree Map Charts

Tree Map Chart
generated description: svg treemapchart

Providing Data for Zen Page Charts

The data for a chart consists of one or more data series. Each data series that you use for a chart is a simple array of numeric values. You can provide the data for a Zen page chart in one of two ways:

Regardless of which technique your chart uses to retrieve data, you can limit the data returned by either technique to the desired number and size of series.

Zen reports callback charts and Zen pages use identical syntax to display charts. Callback charts are defined in the package %ZEN.Report.Display.COSChart

When it comes to displaying charts, Zen pages and Zen reports use identical syntax. Syntax described in the previous section, “Types of Chart,” and in the later sections “Chart Layout, Style, and Behavior” and “Chart Axes” applies equally well to Zen pages and Zen reports. However, the techniques for providing data for charts in Zen reports are different from the techniques for Zen pages. For details, see the section “Providing Data for a Zen Report Chart” in the book Using Zen Reports.

To provide data for charts on Zen pages, use the topics in this section.

Using a JavaScript Method

All charts support the ongetData attribute for generating chart data.

The ongetData expression invokes a client-side JavaScript method defined in the page class. This method becomes the ongetData event handler for the chart. The chart calls the ongetData event handler once for each of the data series specified by seriesCount. The event handler accepts a single argument, series, which specifies the data series currently being processed. The value of series is the 0-based ordinal number of the current data series; possible values range from 0 to seriesCount - 1.

The event handler also needs to know how many values to supply for the data series. This value is provided by the seriesSize attribute of the chart. In the example code that follows this explanation, this line gets the value of seriesSize from the chart:

var data = new Array(chart.seriesSize);

The method puts seriesSize - 1 items into an array and returns that array. It can use whatever approach is appropriate to provide data for the chart. For instance, it may use a switch statement based on the value of the series input argument.

The following is a sample ongetData event handler that provides random values as a test. You can see this event handler in the SAMPLES namespace in the template page class ZENTest.SVGChartTest. It provides the data for charts drawn by page classes that extend the ZENTest.SVGChartTest template, such as SVGLineChartTest and SVGBarChartTest:


ClientMethod getChartData(series) [ Language = javascript ]
{
  var chart = zen('chart');
  var data = new Array(chart.seriesSize);
  var value = 50;

  for (var i = 0; i < chart.seriesSize; i++) {
    if (Math.random() > 0.9) {
      value += (Math.random() * 50) - 35;
    }
    else {
      value += (Math.random() * 20) - 9;
    }
    data[i] = value;
  }
  return data;
}
Copy code to clipboard

The previous example creates a chart with random data.

Normally, you want to create charts using real data from the server. In the typical case, your server-side method returns a list. On the client side, this list is consumed by the chart component that displays the data. One way to make this work is shown in the following example:

  1. When our example page is first displayed, its %OnAfterCreatePage method calls a server-side method PopulateData() to place values into a page property called Population for later use by client-side code. In our example, this happens only once, when %OnAfterCreatePage is called. Later user actions may change how this data is viewed, but in this example, we only get data from the server once.

    Method %OnAfterCreatePage() As %Status
    {
      // Get the data while we're on the server
      Set sc = ..PopulateData()
    
      // Set the initial series size programmatically
      Set chart = %page.%GetComponentById("chartPop")
      Set chart.seriesSize = $Length(..States,",")
      Quit sc
    }
    
    Copy code to clipboard
  2. The Population property is defined in our page class as follows:

    Property Population As %ZEN.Datatype.list(DELIMITER = ",");
    
    Copy code to clipboard

    And our server-side method PopulateData() places values and comma delimiters into the Population list as follows. Step 3 describes the Internals of the GetCountByState() class query referenced here:

    Method PopulateData() As %Status
    {
      Try {
        Set sc = $System.Status.OK()
        
        // Get a resultset containing population by state
        Set sc = ##class(SimpleZenChart.Person).GetCountByState(.rs)
        Quit:$System.Status.IsError(sc)
        
        // Populate the page properties with comma delimited values
        While (rs.%Next()) {
          Set ..Population = ..Population _ rs.%Get("PersonCount") _ ","
          Set ..States = ..States _ rs.%Get("HomeState") _ ","
        }
      
        // Remove trailing delimiter
        Set ..Population = $Extract(..Population,1,*-1)
        Set ..States = $Extract(..States,1,*-1)
      }
      Catch(ex) {
        Set sc = ex.AsStatus()
      }
      Quit sc
    }
    
    Copy code to clipboard
  3. As seen in the above excerpt, PopulateData() invokes a class query defined in SimpleZenChart.Person to retrieve the results that it uses in constructing the Population list. The GetCountByState() method looks like this:

    ClassMethod GetCountByState(Output Results As %SQL.StatementResult) As %Status
    {
      Try {
        Set sc = $System.Status.OK()
        
        // Make a new SQL statement
        // Use an array to create the query text (this is not required)
        // Pass in schema search list into statement constructor
        Set statement = ##class(%SQL.Statement).%New(,"SimpleZenChart")
        Set query = 4
        Set query(1) = "SELECT HomeState, COUNT(ID) As PersonCount"
        Set query(2) = "FROM Person"
        Set query(3) = "GROUP BY HomeState"
        Set query(4) = "ORDER BY HomeState"
        
        // Prepare query
        Set sc = statement.%Prepare(.query)
        Quit:$System.Status.IsError(sc)
        
        // Execute query
        Set Results = statement.%Execute()
        
        // Check %SQLCODE for an error
        If (Results.%SQLCODE < 0) {
          Set sc = 
            $System.Status.Error($$$GeneralError,
            "Error in %Execute. %SQLCODE = "
            _Results.%SQLCODE_" Error message = "_Results.%Message)
          Quit
        }
      }
      Catch (ex) {
        Set sc = ex.AsStatus()
      }
      Quit sc
    }
    Copy code to clipboard
  4. Each time a chart on our example page is refreshed, including the first time the page is displayed, the chart consults its ongetData expression to see which client-side method it should invoke to populate itself with data. In the following excerpt, the chart is a <barChart> and the client-side method is called getData():

    <barChart 
              id="chartPop" width="100%" height="100%" 
              selectedItemStyle="fill:rgb(255,0,255);" seriesCount="1"
              appearance="2D"
              title="Population By State"
              ongetData="return zenPage.getData(series);" 
              ongetLabelX="return zenPage.getXLabels(value);"
              onelementClick="zenPage.onSelectElement(zenThis);">
       <xAxis title="States"/>
     </barChart>
    Copy code to clipboard
  5. Our sample client-side method getData() consults the Population property of the client-side page object to get the list of values stored in that property. Because Population was defined as type %ZEN.Datatype.list in the page class, getData() automatically understands Population as a JavaScript array; no conversion is necessary. getData() returns this array as its return value.

    ClientMethod getData(series) [ Language = javascript ]
    {
      try {
        var data = zenPage.Population;
        return data;
      }
      catch (ex) {
        zenExceptionHandler(ex,arguments);
      }
    }
    
    Copy code to clipboard
  6. The <barChart> updates its display using the values in the JavaScript array returned by getData().

  7. This example offers other interesting features. For example, when you click on a bar in the bar chart, Zen fires the client-side method identified by the <barChart> onelementClick attribute. In our example, this client-side method is called onSelectElement(). It uses the JavaScript utility function zenSetProp() to find some of the other components on the page then change their contents using data acquired from client-side methods, including getData().

    ClientMethod onSelectElement(chart) [ Language = javascript ]
    {
      try {
        var selected = chart.getProperty('selectedItem')
        
        // Set the population and count for the item
        zenSetProp('htmlState','content',this.getXLabels(selected));
        zenSetProp('htmlCount','content',(this.getData())[selected]);
      }
      catch (ex) {
        zenExceptionHandler(ex,arguments);
      }
    }
    
    Copy code to clipboard
  8. In the excerpt above, the client-side method onSelectElement() uses the number of the currently selected bar in the bar chart as an index into the array returned by getData(). getXLabels() also uses an index into a JavaScript array, but in this case the array is the page property States, which contains a list of states whose population statistics are being stored in the example. Because the States property was defined as type %ZEN.Datatype.list in the page class, getXLabels() automatically understands States as a JavaScript array; no conversion is necessary.

    ClientMethod getXLabels(value) [ Language = javascript ]
    {
      try {
        var data = zenPage.States
        return data[value];
      }
      catch (ex) {
        zenExceptionHandler(ex,arguments);
      }
    }
    
    Copy code to clipboard
  9. A final item of note in this example is one that changes the series size for the chart without modifying or resending any data. The client-side method changeSeriesSize() is invoked when the user selects one of the choices in a list box on the same page with the bar chart. The list box is defined as follows:

    <listBox id="lbSeriesSize" 
             label="Select Series Size" 
             value="5" 
             onchange="zenPage.changeSeriesSize(zenThis);">
      <option text="10"/>
      <option text="20"/>
      <option text="30"/>
      <option text="40"/>
      <option text="50"/>
    </listBox> 
    Copy code to clipboard
  10. The client-side method changeSeriesSize() uses the text value from the selected <option> and uses it to reset the seriesSize value for the <barChart> whose id is chartPop. This is our example <barChart> as shown in step 4. When the seriesSize is reset, the chart redisplays.

    ClientMethod changeSeriesSize(listbox) [ Language = javascript ]
    {
      try {
        // Get selected index and compute value
        var selected = listbox.getProperty('selectedIndex');
        var value = listbox.getOptionText(selected);
        
        // Set the series size in the chart
        zenSetProp('chartPop','seriesSize',value);
      }
      catch (ex) {
        zenExceptionHandler(ex,arguments);
      }
    }
    
    Copy code to clipboard

Using a Data Controller

All charts support the following attributes, which associate the chart with a view on a data controller as described in the chapter “Model View Controller. ”

If your XData Contents block contains a <dataController> reference that looks like this:

<dataController id="source" modelClass="myPackage.MyModel" modelId="1"/>
Copy code to clipboard

Then your XData Contents block may also contain a chart definition that looks like this:

<pieChart id="myChart" controllerId="source"
          height="300" width="300"
          title="Pie Chart" titleStyle="fill: black;"
          backgroundStyle="fill: #c5d6d6;"
          plotAreaStyle="fill: white;"
          labelStyle="fill: black;"
          legendVisible="true" legendX="83" legendY="8"
          legendHeight="" legendWidth="15" >
</pieChart>
Copy code to clipboard

The chart’s controllerId value must match the <dataController> id value. The chart takes its seriesSize from the number of properties in the <dataController> modelClass.

Limiting the Data Set

The following attributes from the base class %ZEN.SVGComponent.chart tell the chart how many series to use, and how many of the items in each data series to use, when constructing the chart. All types of chart support these attributes. If you do not use a dataController to provide the data set, you must specify both seriesCount and seriesSize. If you use a dataController, Zen determines the number of series and items from the data.

Data Series Count and Size
generated description: data source

Chart Layout, Style, and Behavior

The following diagram shows the major components of a Zen chart. The chart properties described in the following sections control the positioning, style, and behavior of these components.

Chart properties include those from the SVG component class %ZEN.SVGComponent.svgComponent, such as width andheight, and those from the base chart class %ZEN.SVGComponent.chart, such as marginTop and borderOffset.

Layout Attributes for Zen Charts
generated description: chart geography
  • Layout and style” — The relative size and characteristics of the background

  • Plot area” — The part of the chart that displays the data

  • Markers” — Shapes that highlight the exact data points on a continuous plot

  • Legends” — A key to the meaning of each plot on the chart

  • Titles” — Text that labels the chart, and the items on the chart

  • User Selections” — How the chart should respond to user actions, such as mouse clicks

  • Chart Axes” — Characteristics of the two axes that define most charts

Specifying Size and Position

Unless the specific description of a property states otherwise, you can give values for properties that specify sizes and positions in one of the following ways:

  • Do not specify a value, and let Zen calculate the value automatically.

  • Use a value from 0 to 100 that is interpreted as a percentage of the current chart size.

  • Specify a length value with units, such as "10px", to indicate that you want a margin of 10 pixels, independent of chart size

Layout and Style

Plot Area

The following attributes from the base class %ZEN.SVGComponent.chart determine display conventions for graphs within the plot area and for the coordinate axes that border the plot area. Also see the section “Chart Axes.”

A number of attributes are supported by several chart types. These attributes are listed in the table of attributes for the relevant charts, and described in more detail in the following sections.

chartPivot

If the attribute chartPivot is true, rotate the chart so that the x-axis is vertical and the y-axis horizontal. If false, display the chart in typical fashion, with x-axis horizontal and the y-axis vertical.

This attribute has the underlying data type %ZEN.Datatype.boolean. See “Zen Attribute Data Types.”

The following figure shows a pivoted bar chart.

Pivoted Bar Chart
generated description: svg barchart pivoted

chartStacked

The attribute chartStacked comes into play if there are multiple data series. If true, the data series are drawn stacked on top of one another (values are additive). If false, the bars appear side by side (the values are independent).

This attribute has the underlying data type %ZEN.Datatype.boolean. See “Zen Attribute Data Types.”

If you set the property chartStacked to true, the result is a chart with values at each data point from all the data series in the chart stacked into a single bar. The following figure illustrates a stacked bar chart:

Stacked Bar Chart
generated description: svg barchart stacked

And the next figure shows the same data presented as a stacked line chart:

Stacked Line Chart
generated description: svg linechart stacked

showMultiples

If the attribute showMultiples is true, charts that support small multiples display the data as a set of small charts, one for each data series. The chart method hasMultiples lets you determine whether the chart supports multiples.

This attribute has the underlying data type %ZEN.Datatype.boolean. See “Zen Attribute Data Types.”

The following figure shows a line chart with four data series and showMultiples="true".

Line Chart Displayed as Multiples
generated description: svg linechart multiple

timeBased

The attribute timeBased specifies that the x-axis is a time line. It is valid only for line and combo chart types. In order to plot a time based chart, you must use the ongetLabelX callback method to provide time values in the format YYYY-MM-DD or YYYY-MM-DD HH:MM:SS. These values are placed in their proper position on the x-axis timeline. Because the logic that positions values on the timeline depends on the returned date values, you cannot set the property maxLabelLen to a value less than ten.

The chart properties startTime and endTime set the start and end dates for the time line. If you do not supply values for startTime and endTime, the chart uses the earliest and latest values returned by the ongetLabelX callback method.

The following figure illustrates the effect of a timeBased x-axis. The top chart uses a time based x-axis, while the lower chart plots the same x values on a category axis.

Time Based Line Chart
generated description: svg linechart timebased

Markers

Markers are shapes that are placed at each data point along the chart. If the chart has multiple series, each series in the chart can use a different shape for its marker. Marker attributes apply only to types of chart that support markers (that is, line charts). The base class %ZEN.SVGComponent.chart offers the following marker attributes.

Legends

The following attributes from the base class %ZEN.SVGComponent.chart determine the style of the chart legend and whether or not it should display.

Titles

The following attributes from the base class %ZEN.SVGComponent.chart determine the style and contents of the chart title.

User Selections

Chart Axes

  • <xAxis> can be a category axis or a value axis, depending in the type of chart. A category axis names the data categories. A value axis indicates the values of plotted data.

  • <yAxis> is a value axis.

You can supply more than one y-axis to a chart, which enables you to plot data series with different ranges of values on the same chart in a meaningful way. The following example plots six months of data on heating degree days (HDD), and electricity use in kilowatt hours (kWh) for a residential building in the Boston MA area. A heating degree day is a measure of the energy demand for heating buildings. In this example, data values for HDD range from 11 to 34, and data values for kWh range from 841 to 1148. The following code fragment creates a line chart that plots these two data series using two different axes, one for values from 10 to 40, the other for values from 700 to 1200:

<lineChart id="chart" 
  ongetData="return zenPage.getLineChartData(series);"
  onelementClick="zenPage.chartElementClick(chart);"
  ongetLabelX="return zenPage.getXLabels(value);"
  seriesNames="HDD,kWh"
  backgroundStyle="fill: #cccccc;" 
  plotAreaStyle="fill: #eeeeee;"
  title="Line Chart: Two Y Axes" 
  currYAxis="1"
  seriesCount="2"
  seriesSize="6"
  seriesColorScheme="solid"
  plotStyle="stroke-width: 1px;"
  labelsVisible="true"
  seriesYAxes="1,0"
  width="300" 
  height="300">
  <xAxis id="xAxis" />
  <yAxis minorGridLines="true" minValue="700" maxValue="1200" labelUnits="100" 
    minorUnits="10" majorUnits="50" majorGridLines="true" />
  <yAxis minorGridLines="true" minValue="10" maxValue="40" labelUnits="10" baseValue="0"/>
</lineChart>
Copy code to clipboard

The property seriesYAxes associates data series with axes. The property currYAxis specifies the axis that is active when you first display the chart. See “Plot Area”. The following figure shows the resulting chart. The first image shows the chart as it is initially displayed, with the HDD axis visible. The HDD item in the legend is highlighted to show that it is the relevant data series for the axis currently in use. If you click on kWh in legend, the chart displays the appropriate y-axis. All data series associated with an axis are all highlighted when that axis is active.

Line Chart with Two y Axes
generated description: svg two y axes

Compare these charts with the following chart, which attempts to plot both HDD and kWh on a single axis.

Same data Plotted on One y-axis
generated description: svg same axis

Note that <xyChart>, <diffChart> and <bubbleChart> do not support alternate yAxes.

The following attributes from the class %ZEN.Auxiliary.axis are available as attributes of either <xAxis> or <yAxis> within a chart definition. All of these attributes are optional; Zen provides reasonable defaults for each of them based on the data supplied to the chart.

When you work with %ZEN.SVGComponent.chart subclasses programmatically, you work with axes as the xAxis and yAxis properties of the chart object. Each of these properties is a %ZEN.Auxiliary.axis object with properties corresponding to the attributes listed above.