FAQ - Main Changes and new Features in CCC version 2

What are the main changes and new features?

To the Eye

  • Small multiple charts
  • Interactivity
    • selection of visual elements
    • highlight of visual elements (on mouse over)
    • better visual element tooltips, showing business level information, in HTML format, by default
  • Multiple data dimensions can be represented in a discrete axis and in the legend (ex. series)
  • Tooltips can show data dimensions not visually represented
  • Gradients in visual elements fill style
  • Several out of the box visual improvements
    • better support for dynamic and diverse data by using automatic layout
    • better numeric tick calculation algorithm; sensitive to available space and font characteristics
    • automatic discrete ticks hiding when available space would cause labels to overlap
    • no more cut-off axis labels at the chart boundaries
    • legend items' style is consistent with that of the corresponding visual element, by default
    • automatic sizing of axes, legend and title panels, according to current data and font characteristics


  • Data Engine with new and reworked functionality
    • data dimensions (see dimensions)
      • independent of the data transport format
      • related to business concepts
      • values can be calculated or read from the data transport format
      • values can be formatted and sorted
      • direct support of the Google-table style cell format, for supplying both a value and its formatted value (ex. {v: 1, f: "1.0"})
    • grouping and selection functions
    • rows whose measures are all null can be ignored (see ignoreNulls)
  • Visual Roles
    • provide separation between data dimensions - the business - and visual functions - series or category
    • visual roles are bound to data dimensions: «the "series" role is bound to the "country" dimension»
    • visual roles binding may be required or optional: «"size" is an optional role of the metric dot chart»; when bound, the chart shows dynamically sized bubbles
    • visual roles support binding to more than one data dimension: «the "series" role is bound to every value combination of the "country" and "year" dimensions»
  • Trending capabilities
    • Some chart types allow adding trend lines to them
    • Supported trend types are: Linear, Moving Average and Weighted Moving Average
    • Extensible: create your own trending algorithm and register it with the CCC library
  • Extensibility
    • consistent interfaces across action handlers, extension point functions, and other "auxiliary functions"
    • common "data" and "visual" object models
    • better future compatibility
    • compatible, as much as possible, to version 1 of CCC
    • extension point functions can control both the stationary and the interactive styles
  • Layout - box model
    • margins and paddings options;
      • specified in pixels or percentages
      • applicable to the chart, and the legend, title and content panels
    • size and sizeMax options
      • specified in pixels or percentages
      • applicable to the legend, title and axis panels
    • when the size of panels is automatically calculated, the smallest possible size that holds all of the content is chosen. This is in opposition with version 1's layout rules were a docked panel would take up all of the available space of the side it was docked to
    • in contrast to CSS, CCC sizes specify the size of the outermost box - the margin box
    • borders are taken into account in the layout

By Component

  • Line/Dot/Area charts
    • we call them, simply, Point charts!
    • areas can be overlapped (instead of just stacked), with semi-transparent colors
    • new line and area segmentation mode, that segments only as needed, regains all line join types and displays areas with no vertical separation
    • null data values can be shown as a gap, as zero, or be linearly interpolated (see nullIterpolationMode)
    • a secondary point plot can be superimposed and fully configured to represent chosen series
    • a third point plot can be superimposed and fully configured showing trend lines for the series of the first and/or second plot (see trendType)
  • Stacked bar chart
    • negative value support - separate positive and negative stacks
    • overflow indicator
    • show a white space between stacked bars (see barStackedMargin)
  • Metric Line/Dot charts
    • we call them, simply, Metric Point charts!
    • new color and size roles for creating bubble charts
    • axes' offset determination is automatic and takes the size of each bubble into account
    • a second metric point plot can be superimposed and fully configured showing trend lines for all the series of the main plot (see trendType)
  • Pie chart
    • the new linked labels mode shows value labels beside the pie, each linked with a line to its corresponding pie slice (see valueLabelStyle)
    • dynamic tooltip placement per slice
  • Waterfall chart
    • rewritten so that it could provide a useful representation of any regular data set
    • summarizes data by grouping it on its multiple categories
    • summary steps are calculated for each grouping level
    • shows steps with negative values by inverting the "water direction"
  • Cartesian Axis
    • automatic sizing - no need to guess an axis' size anymore!
    • we know you needed this one: title
    • no more axis labels being cut-off at the chart boundaries
    • offset option implemented in all axis types (discrete, numeric, timeseries)
    • tick labels that, besides all layout efforts, do not fit the available orthogonal space are trimmed and suffixed with ".."
    • options and extension points can be specified in one of several ways (options only in code, not supported by CDE):
      • by orientation prefix: "yAxisMinorTicks" (the first vertical axis),
      • by logical prefix: "orthoAxisMinorTicks" (the first orthogonal axis), or
      • by scale type prefix: "continuousAxisLabelSpacingMin" (any continuous axis), or
      • by the catch-all prefix: "axisMinorTicks" (any axis)
      • see other examples at the cartesian axes documentation
  • Discrete Axis
    • click and double-click action
    • select by clicking on a label
    • select by rubber-banding over the labels
    • tick labels that, besides all layout efforts, would overlap with neighbour tick labels, are omitted and replaced with a placeholder "·" (that allows seeing a tooltip describing the hidden label) (see overlappedLabelsMode)
  • Numeric Axis
    • ticks calculation is sensitive to available space and font characteristics - no need to guess a desired tick count anymore! (see labelSpacingMin)
    • ever needed that numeric ticks with decimal places would not be generated? Then see tickExponentMin.
    • zero-lines, shown when zero is part of the axis scale's domain (see zeroLine)
  • Continuous Axis (numeric or timeseries)
  • Legend
    • automatic sizing
    • column or row layout, depending on the panel position
    • configurable behavior for clicking on a legend item's label: toggle visibility (default), or toggle selection (see the legendClickMode option of color axes)
    • select by clicking on a legend item's marker
    • select by rubber-banding over legend items
    • legend items' markers style is consistent with that of the corresponding visual element, by default
    • legend items' markers change their style according to the selected state of the controlled datums
    • each distinct discrete color axis that is configured can show its items in the legend
  • Tooltip
    • intelligent placement avoids crossing screen boundaries, whenever possible
    • fades in and out when changing between visual elements, but...
    • ...simply updates its content, if quickly changing between visual elements of the same kind
    • default tooltip
      • shows business level information
      • in HTML format
      • stacked charts show a corresponding percentual numeric value beside numeric dimensions
      • when more than one datum is associated to a visual element, the tooltip shows a summary of values of each dimension
  • Protovis
    • mark stroke properties
      • all mark types support the new extension points, if applicable: lineJoin, lineCap, strokeMiterLimit and strokeDasharray
      • normal segmented lines support downgrading to a bevel join when the specified strokeMiterLimit is reached.
      • the new "smart" line and area segmentation mode only applies segmentation when line properties actually change; as a consequence, all stroke properties are supported inside each segment
    • gradients support in marks' fillStyle and strokeStyle properties
      • we added support for a subset of the CSS3 Gradients
      • linear and circular gradients
    • mark properties and delegation
      • a property function, like those used in extension points, can handle only certain cases and delegate the other cases to the default implementation
      • works for delegating to CCC's default implementations, when existent

Which charts were updated?

Some of version 2's changes affect all chart types - like those due to the new data engine, or to the changing of a common component like the legend panel. Other than that, the updated charts were the so called main chart types:
  • Bar-family
    • Bar (stacked or grouped, possibly with line series)
    • NormalizedBar
    • Waterfall
    • Box plot
  • Categorical Line/Dot/Area
    • Line
    • Dot
    • Area
    • Stacked Line
    • Stacked Area
  • Metric-family
    • Line
    • Dot
  • Pie
  • Heat grid

Which charts were not updated?

Unfortunately, there wasn't enough time to update the following chart types:
  • Bullet
  • Data tree
  • Parallel Coordinates

We plan to update those in a future release. Until then, these charts should work like they used to.
These charts' compatVersion option is implicitly set to 1.

Is version 2 backward compatible?

We went into great efforts to ensure that CCC version 2 also runs version 1 charts:
  • there is a new chart option, compatVersion, that instructs a chart to behave and look like a certain CCC version, as much as possible
  • CCC version 1 has version number of 1...
  • when compatVersion is set to Infinity, the default of the CCC library, charts work like the latest version
  • when running in CDF and CGG, unedited previous version charts will run as if compatVersion had been specified as 1
  • once edited, a previous version chart will receive the new compatVersion property, with a default value of 2 - you must set this to 1, if you want to maintain the chart in compatibility mode
Generally, if compatVersion is not set to 1, a CCC version 1 chart might have to be converted, to accommodate for the following changes in:
  • extension point function signatures
  • the structure of constituent protovis marks of each CCC panel
  • the clickAction, doubleClickAction and renderCallback functions signature
  • the tooltipFormat function signature
  • the tooltip text format, now being HTML by default

If a chart is not highly customized with "dynamic" logic, it should work without any conversion.
We hope that all the new features that CCC version 2 has to offer will be enough reasons to justify any necessary conversions.

See How are extension points changed? for information on extension point changes.

In CDE, how can I tell if chart property is supported in version 2?

Some chart properties were deprecated in version 2. When you open a chart created in version 1, the deprecated properties will still show up, so that you can keep the chart in version 1, and keep changing them, if necessary.
When and if you want to upgrade your chart to version 2, the values of relevant version-1-only properties have to be copied, or adapted, to version 2 equivalent properties.

But how can you tell which properties are version-1-only? It's easy, the property descriptions of version-1-only properties are prefixed with "V1 - ". For example, the property "V1 - Show values" has been deprecated.

Charts created with new version of CDE will contain only version 2 properties.

Can version 2 properties be used in compatibility mode?

If you don't want to, or can't, convert your chart, right away, you can still benefit of some of the new functionalities of version 2.

As a general rule, a property of version 2 is supported as long as:
  • there isn't a corresponding CDE property in version 1, and
  • its default value does not break the charts' appearance

As an example, the version 2 property baseAxisOffset isn't available because version 1 has a related/equivalent CDE property: "Axis offset". On the contrary, the version 2 property baseAxisTitle can be used.

Selecting visual elements

All the main chart types support selection by the user of one or more visual elements. The user can select elements if the option selectable is true.

Selection modes

The option ctrlSelectMode controls whether selection behavior is additive or not.
When true, the default value, when selecting a set of visual elements, any previously selected visual elements are deselected first. For selection to be additive, the user must press the CTRL key during the selection action.
When false, selection is always additive.

Ways to select visual elements

The user can select visual elements in one of the following ways:
  • Clicking
    • on a visual element, selects it
    • on a discrete axis label, selects all visual elements having the associated discrete values
    • on a legend item's marker, selects all visual elements having the associated discrete values
    • on an empty chart area, clears the current selection; this behavior can be disabled by specifying the value 'manual' in the option clearSelectionMode
  • Rubber-banding
    • over visual elements on the main content area, selects them
    • over a discrete axis' labels, selects all the visual elements associated to the included labels
    • simultaneously over the labels of the two perpendicular discrete axes, selects the visual elements that are the result of intersecting the individual selections on each axis (only applies to the Heat Grid chart)
    • over the legend items, selects all the visual elements associated to the included items

The rubber-band

The rubber-band looks like this:

The style of the rubber-band may be changed by use of the chart extension point rubberBand_.

Selection style

The default visual effect of selecting varies from chart type to chart type, but generally causes graying out not-selected visual elements. The previous bar chart would look like this, when the mouse is released:

The selected style of visual elements can be changed by use of extension point functions.

Highlighting visual elements

In version 1, when the user hovered over a visual element, a tooltip describing it could already be shown. Now, additionally, the visual element can be highlighted. The user can highlight elements if the option hoverable is true.

Highlight style

The way a visual element is highlighted varies from chart type to chart type. Here's how it looks in a bar chart:

When any element is selected, the colors of not-selected elements are grayed-out, making it harder to distinguish elements of the same series. In that case, highlighting an element also reveals same-series elements by making them darker than the others:

In the case of a Line/Area chart the way selection and highlighting look can be seen in the following images:


and also:

The highlight style of visual elements can be changed by use of extension point functions.

Small Multiple what?

This is one of the most exciting new features of CCC version 2. The «Small multiple charts» technique is a great way to break an overcrowded chart into several more understandable ones.
To use it, there has to be at least one more data dimension in the data source that is used to split the data for each chart.
Currently, small charts are layed out in columns, along a line, and can be optionally wrapped at a given column.
Here's an example of CCC's small multiple charts in action:

See Configuring Small Multiple Charts for more information.

How are extension points changed?

Extension points are one of the great features of CCC charts. They provide almost direct access to the underlying protovis marks.
They serve at least the following purposes:
  1. allow change of the default visual style of a chart, from colors to text formatting and alignment, etc.
  2. allow addition of missing functionality or making deep changes to the behavior of the existing one

Yet, the strengths of extension points also imply that any changes made to the underlying protovis model most likely break existing extensions of the second type. Many of the new CCC version 2 features implied changing the underlying protovis model.

All protovis extension points now have a uniform function signature that exposes a common underlying visual and data object model.
In this way, we hope to bring safety to a greater number of extension scenarios. The underlying protovis model remains accessible, but accessing it comes with a higher probability of future breakage.

Version 1 compatibility

Most version 1 extension points will continue to work if the option compatVersion is set to 1.
In some cases, access to "this.index" and "this.parent.index", now gives different results.
If these indexes were used to access data externally or through the data engine, the same can now be accomplished in different, and hopefully simpler, ways (see pvc.visual.Scene).

Version 2 extension point anatomy

The new anatomy of a protovis mark extension point function can be observed by the following:

 1 function mark_extension_point(scene){
 3     assert(this       instanceof pvc.visual.Context);
 4     assert(this.scene instanceof pvc.visual.Scene);
 5     assert(this.scene === scene);
 7     // The index of the scene
 8     assert(typeof this.index === 'number');
10     // Underlying protovis mark
11     assert(this.pvMark instanceof pv.Mark);
13     // return -> any type, depends on extension point
14 }

The this context object gives way to all CCC functionality and its structure is further explained in Visual API.
An example of an extension point function can be seen in Formatting a bar label.

Visual API

The visual API is a set of classes intended to abstract the details of the underlying protovis model and to provide a uniform extensibility interface across all chart and extension types. The most important classes are the pvc.visual.Context and the pvc.visual.Scene classes.

CCC Context

A pvc.visual.Context object is passed as the JavaScript context object to functions of extension scenarios (extension point functions, action handlers). It is accessible from within a function by using the this keyword. It has the following members:

Property Type Description
scene pvc.visual.Scene A scene is a node in a rendering hierarchy. Rendering generally follows the shape of a scene hierarchy. Each scene contains participating datums and vars (see below).
index number The render index of the scene, when there is a scene, or null, otherwise. This property can be used to change the value of properties depending on the index being, for example, even or odd.
It is not advisable to use it for much else, like using it to obtain data from an external array or something like that.
event HTML DOM Event The window event object, in click and double-click action handlers. In IE, this event object is a "fixed" version of the original window event object.
Visual components
chart pvc.BaseChart The immediate CCC chart object.
panel pvc.BasePanel The immediate CCC panel object.
sign pvc.visual.Sign The CCC sign object on which rendering takes (or took) place.
pvMark pv.Mark The underlying protovis mark. If required, it is at hand.
Interactivity and delegation
finished(value) any Used to inform that the result of an extension point function is final (a finished good) and should not be subject to any additional interactivity effects.
delegate(defaultValue) any Convenience method to call the associated protovis mark's pv.Mark#delegate method.
Calls the underlying implementation of the extension point (protovis property) currently being evaluated.
V1 Compatibility
getV1Series() Any Obtains the value of the version 1 series concept.
getV1Category() Any Obtains the value of the version 1 category concept.
getV1Value() Any Obtains the value of the version 1 value concept.
getV1Datum() pvc.data.Datum Obtains a datum object compatible with certain V1 uses: has the percent property used by some chart types.
Visual data - Value & Label helper methods.
The same as those in pvc.visual.Scene class.

CCC Scene

A pvc.visual.Scene object gives access to the business and visual information that participates in a part of a visualization. It has the following members:

Property Type Description
Business data
group pvc.data.Data The data object that contains the datums participating in the scene, if any.
datum pvc.data.Datum The first datum of group, when there is one; the single datum of the scene, when there's no group but there is a datum; or null.
atoms object<string, pvc.data.Atom> The atoms map of group, when there is one; the atoms map of datum, when there's no group but there is a datum; or null.
Use it to obtain the value of a business property, like, for example: this.scene.atoms.productType.value.
datums() def.Query<pvc.data.Datum> An enumerable of the participating datums.
Visual data
vars object<string, object> Each visual role usually has a corresponding scene variable with the same name as the role. The scene variable object contains the value and label of the role in this scene.
Use it to obtain the value of a visual role, like, for example: this.scene.vars.series.value.
Note that the variable names are not always equal to the name of the role that feeds it. One example is the 'tick' scene variable of an axis panel scene.
In some cases it is fed with the data bound to the 'category' role, while in others, it is fed with the data of the 'value' or 'y' role.
Visual data - Value helper methods
getColor() any Obtains the value of the "color" variable (defined in plot scenes).
Note this is not a color value (like a color string or a pv.Color object), but, instead, the business value that is passed to a color scale to obtain a color.
getCategory() any Obtains the value of the "category" variable (defined in scenes of categorical plots and pie).
getSeries() any Obtains the value of the "series" variable (defined in scenes of cartesian plots).
getValue() Number, any Obtains the value of the "value" variable (defined in scenes of legend panel, for each item's value - any type, and in categorical/numeric plots - Number type).
getTick() any Obtains the value of the "tick" variable (defined in scenes of cartesian axes).
getX() Number, Date Obtains the value of the "x" variable (defined in scenes of scatter/metric-point plots).
getY() Number Obtains the value of the "y" variable (defined in scenes of scatter/metric point plots).
getSize() Number Obtains the value of the "size" variable (defined in scenes of heat-grid and scatter/metric-point plots).
Visual data - Label helper methods
getColorLabel() string Obtains the label of the "color" variable.
getCategoryLabel() string Obtains the label of the "category" variable.
getSeriesLabel() string Obtains the label of the "series" variable.
getValueLabel() string Obtains the label of the "value" variable.
getTickLabel() string Obtains the label of the "tick" variable.
getXLabel() string Obtains the label of the "x" variable.
getYLabel() string Obtains the label of the "y" variable.
getSizeLabel() string Obtains the label of the "size" variable.
Visual components
chart() pvc.BaseChart The immediate CCC chart object.
panel() pvc.BasePanel The immediate CCC panel object.
parent pvc.visual.Scene The parent scene, if any.
childIndex() number The child index of this scene, if it has a parent, or -1, if not.
root pvc.visual.Scene The root scene. If this instance is the root scene, it will be the value of this property.
isRoot() boolean Indicates if this scene is a root scene.
children() def.Query<pvc.visual.Scene> An enumerable of child scenes.
leafs def.Query<pvc.visual.Scene> An enumerable of the leaf scenes (does not include this scene).
firstChild pvc.visual.Scene The first child scene, if any
lastChild pvc.visual.Scene The last child scene, if any
previousSibling pvc.visual.Scene The previous sibling scene, if any
nextSibling pvc.visual.Scene The next sibling scene, if any
Interactivity state
anyInteraction() boolean Indicates if the scene is active or if, globally, there is any selected datum.
Interactivity - activity state
isActive boolean Indicates if the scene is active. A scene becomes active when the user highlights any of the the visual elements that render it.
anyActive() boolean Indicates if the tree to which this scene belongs has an active scene.
active() pvc.visual.Scene The active scene of the scene tree to which this scene belongs.
activeSeries() any The value of the series variable of the active scene, if any, of the scene tree to which this scene belongs.
isActiveSeries() boolean Indicates if this scene's series variable, if any, is the same as the one returned by activeSeries().
setActive(active) undefined Programatically sets the active state of the scene. When a scene is activated, any previously active scene of the same scene tree is deactivated.
To update the chart, you must execute this.panel().renderInteractive().
clearActive() undefined Clears the active state of the active scene, if any.
To update the chart, you must execute @this.panel().renderInteractive().
Interactivity - selection state
isSelected() boolean Indicates if at least one of the datums participating in the scene is selected.
anySelected() boolean Indicates if, globally, at least one of the datums is selected.

CCC Sign

A pvc.visual.Sign object wraps a protovis mark and configures it with special CCC behavior. These are its most useful members:

Property Type Description
scaleColor(scene) pv.FillStyle When you need an easy way to obtain the default color that the color scale would provide to a scene. In some cases, delegating already returns a modified color.
dimColor(color, type) pv.Color Obtains a dimmed/grayscale version of the specified color string or pv.Color object. The type argument can be one of "fill", "stroke" or "text"; depending on the specified type, slightly different dimming techniques may be used.
showsInteraction() boolean Indicates if the sign shows the interactive state of scenes.
showsActivity() boolean Indicates if the sign shows the active state of scenes.
showsSelection() boolean Indicates if the sign shows the selected state of scenes.
Interactivity - activity state
mayShowActive(scene) boolean Indicates if the sign should show as active in the specified scene.
Interactivity - selection state
mayShowNotAmongSelected(scene) boolean Indicates if, for the given scene, the sign should show as not being among selected ones. By default, if there is at least one selected scene and the specified scene is not selected, the sign will show dimmed colors.
mayShowSelected(scene) boolean Indicates if, for the given scene, the sign should show as being among selected ones.

Common customization scenarios

Formatting a bar label

By default, the bar labels in a bar chart show the label property of the "value" visual role. The "value" visual role is a single dimension continuous role.
In practice, the label is derived from the formatter function of the visual role's single dimension.
If for some reason the shown dimension's default format isn't suitable for the bar label, the barLabel_text extension point can be used to change it, just like it is shown in the following example:

1 function barLabel_text(){
2     // Obtain the typed value of the visual role named "value",
3     // multiply by hundred, round to 2 decimal places and add a percent sign
4     return (100 * this.scene.vars.value.value).toFixed(2) + "%";
5 }

If you prefer to show additional information, the label can show a value taken from some other dimension. For example, suppose that a dimension named 'countryAcronym' is defined:

1 function barLabel_text(){
2     return this.scene.atoms.countryAcronym.label;
3 }

Formatting a numeric axis label

The labels of major ticks, in a numeric axis, show the label property of the visual role assigned to the axis.
In the continuous axis case, the visual role contains a single continuous dimension, and so, in practice, the label is derived from the formatter function of that dimension.

But, suppose you have a line chart, and would rather show the numeric values in "thousands". The following example shows the recommended way to do it:

1 var chartOptions = {
2     yAxisTickFormatter: function(value){
3         // Divide by thousand, round and add the "m" suffix
4         return (value / 1000).toFixed() + "m";
5     }
6 };

If you format the axis ticks this way, the resulting ticks text will be taken into account during the layout of the axis panel, and an appropriate size will be calculated so that it all fits.
If you do it in the version 1 way, by using the "yAxisLabel_text" extension point, the layout will not take the resulting text into account.

Handling the click action

Clicking is enabled if the option clickable is true and the option clickAction is specified.
The new click action interface is:

1 function clickAction(scene){
2     assert(this       instanceof pvc.visual.Context);
3     assert(this.scene instanceof pvc.visual.Scene);
4     assert(this.scene === scene);
5 }

To know more about the CCC context and the scene objects please see How are extension points changed?.
Just like with extension points, the CCC context object is passed as the JavaScript context object, accessible through this. The corresponding scene gives access to data associated with the clicked visual element.
The following example illustrates handling a click action.

 1 var chartOptions = {
 2     clickable: true,
 3     clickAction: function(){
 4         // Show the values of all atoms
 5         var description = ["You clicked:"];
 6         for(var dimName in this.scene.atoms){
 7             var atom = this.scene.atoms[dimName];
 8             description.push(
 9                 dimName + ": " + atom.label + " (" + atom.value + ")");
10         }
12         alert(description.join("\n\t"));
13     }
15     // ... other options ...
16 };
18 var chart = new pvc.LineChart(chartOptions);

Handling a discrete axis click action

Clicking on a discrete axis is enabled if the chart option clickable is true and the axis option clickAction is specified (using one of the axis' option prefixes).
The interface of the click action is identical to that of the click action for visual elements.
The following example illustrates handling the base axis click action to approximately mimic the existing selection behavior:

 1 var chartOptions = {
 2     clickable:  true,
 3     selectable: false, // prevent default selection behavior
 4     baseAxisClickAction: function(){
 5         // Obtain all datums that share the value(s) of the clicked axis label
 6         var datums = this.scene.group.datums(); // not an array; it's a def.Query enumerable.
 7         datums.each(function(datum){
 8             datum.toggleSelected(); 
 9         });
11         this.chart.updateSelections();
12     }
14     // ... other options ...
15 };
17 var chart = new pvc.LineChart(chartOptions);

Handling the selection action

One visual element may be associated to one or more datums, depending on the binding of visual roles to data dimensions.
Selecting a visual element selects all of its datums. Conversely, a visual element is shown selected if at least one of its datums is selected.

The new option selectionChangedAction can be set to a function that is called whenever the current chart's selected datums have changed and the chart is re-rendered. Its interface is:

1 function selectionChanged(currentlySelectedDatums, selectedChangedDatums){
2     assert(this instanceof pvc.visual.Context);
3     assert(this.scene === null);
4 }

The argument currentlySelectedDatums is an array of Datum instances. Each has its own isSelected property with the datum's current selected state.

When a datum is selected programmatically, the chart isn't automatically re-rendered. To update the chart the method updateSelections must be called.
For example, the following code obtains all the datums whose region is one of 'Europe' or 'Australia', and whose year is 2001 or 2002. Then, each is selected individually and only then is the chart updated to reflect selection changes:

 1 var chartOptions = {
 2     selectable: true,
 3     selectionChangedAction: function(currentlySelectedDatums, selectedChangedDatums){
 4         console.log("Selected datums (" + currentlySelectedDatums.length + "):");
 6         currentlySelectedDatums.forEach(function(datum){
 7             console.log(datum.toString());
 8         });
 9     }
11     // ... other options ...
12 };
14 var chart = new pvc.LineChart(chartOptions);
16 chart.setData(/* ... */);
17 chart.render();
19 // .... later .....
21 // datums is a def.Query enumerable of Datum
22 var datums = chart.data.datums({
23     region: ['Europe', 'Australia'], 
24     year:   [2001, 2002]
25 });
27 datums.each(function(datum){ 
28     datum.setSelected(true); 
29 });
31 chart.updateSelections(); // re-renders the chart if any changed and fires 'selectionChangedAction'

Another chart helper method, clearSelections deselects all datums and updates the chart in one call.

Also, at any time, an array with the currently selected datums can be obtained:

1 var datums = chart.data.selectedDatums();
3 datums.forEach(function(datum){ 
4     console.log("Region: " + datum.atoms.region.label + " Year: " + datum.atoms.year.label);
5 });

Implementing single selection

The default selection implementation allows selecting multiple visual elements, by clicking on elements or using the rubber-band.
In a common scenario, you'll want that the user can only select a single visual element at a time. Then the selected visual element can be used to show information in another dashboard component.
The following is a way to do this:

 1 var chartOptions = {
 2     selectable: false, // <--- Disable click-select and rubber-band select
 3     clickable:  true,
 5     // Control selection manually
 6     clickAction: function(scene){
 7        // Replace any selected datums with the datums participating in the scene
 8        this.chart.data.replaceSelected(scene.datums());
10        // Re-renders if any changed
11        this.chart.updateSelections();
12     },
14     // Example CDF code to update dependent components
15     selectionChangedAction: function(selectedDatums, selectedChangedDatums){
16         // Assume that a 'territory' dimension exists and 
17         // that all of the selected datums share the same value.
18         var territory;
19         if(selectedDatums.length){
20             territory = selectedDatums[0].atoms.territory.value;
21         }
23         Dashboards.fireChange('territory', territory || '');
24     },
25     // ... other options ...
26 };
28 var chart = new pvc.LineChart(chartOptions);
30 chart.setData(/* ... */);
31 chart.render();

Defining data dimensions

Data dimensions can (but do not need to) be explicitly defined. When dimensions are not defined, default dimensions, with default options, are generated to satisfy the needs of the chart. It is possible to define one dimension, totally or partially, and let the others be automatically generated.

Imagine that the data source contains a product type dimension whose value is the product type code. The code is needed for drill-down purposes, or for opening a dialog based on the user's selection.
Yet, we would like to show a proper description to the user. Suppose a separate lookup table exists for "decoding" product type codes. The product type dimension could be defined as follows:

 1 var productTypeLookup ={
 2     "BO": "Boeing",
 3     "AB": "Air bus",
 4     "BY": "Bycicle" 
 5 };
 7 var chartOptions = {
 8     categoryRole: 'productType',
10     dimensions: {
11        productType: { 
12            label: 'Product type', 
13            valueType: 'string',
14            formatter: function(code){
15                return productTypeLookup[code];
16            }
17        },
19        readers: [
20           // First column of data source feeds the 'productType' dimension
21           {names: 'productType', indexes: 0}
22        ]
23     }
24     // ... other options ...
25 };
27 var chart = new pvc.BarChart(chartOptions);

The example also shows how the product type dimension would receive its values, by specifying a reader for it, although this isn't further developed here. Also, the example shows how to assign the defined dimension to the category visual role.

See DimensionType for a list of all the available options.

Configuring Small Multiple Charts

Suppose that data is supplied in crosstab format and has three category columns. Two of the category columns will be used to separate the small charts and the other category column will serve as each chart's "category".

The easiest way to map the two columns is to use the multiChartIndexes option, like in the following example:

 1 /* 
 2     |MC1|MC2|CAT|SER1|SER2|...|
 3     |<----3---->|
 4 */
 5 var chartOptions = {
 6     // The indexes of columns that separate small charts
 7     // Index 2 will feed the default "category" dimension
 8     multiChartIndexes: [0, 1],
 9     multiChartMax: 9
11     // ... other options ...
12 };
14 var chart = new pvc.BarChart(chartOptions);

The result would be similar to the one shown in Small Multiple Charts.

For a list of supported properties see, for example, the "Multi-Chart" category properties of the Bar chart .
The axis property domainScope also affects the presentation of multi-charts.

If for some reason more control is required over the small multiple chart data dimensions, or their mapping to visual roles, these can also be defined/mapped explicitly, like in the following example:

 1 var chartOptions = {
 2     multiChartMax: 9,
 4     /* Visual Role mapping */
 5     visualRoles: {
 6         multiChart: "territory, country desc" 
 7     },
 9     /* Data definition */
10     dimensions: {
11         territory: {label: "Territory"},
12         country:   {label: "Country"  }
13     },
15     /* Data mapping */
16     readers: {
17         {names: 'territory, country'}
18     }
20     // ... other options ....
21 };
23 var chart = new pvc.BarChart(chartOptions);

BarChartSelection.png (9.1 kB) Duarte Cunha Leão, 2012-05-11 04:29 pm

BarChartSelectionLasso.png (9.7 kB) Duarte Cunha Leão, 2012-05-11 04:29 pm

BarChartHighlighting.png (10.9 kB) Duarte Cunha Leão, 2012-05-11 05:29 pm

BarChartHighlightingSelected.png (10.6 kB) Duarte Cunha Leão, 2012-05-11 05:33 pm

LineAreaChart.png (16.1 kB) Duarte Cunha Leão, 2012-05-11 05:44 pm

LineAreaChartHighlighting.png (18.3 kB) Duarte Cunha Leão, 2012-05-11 05:50 pm

LineAreaChartHighlightingSelected.png (18.1 kB) Duarte Cunha Leão, 2012-05-11 05:50 pm

SmallMultipleBarChart.png (59.3 kB) Duarte Cunha Leão, 2012-05-14 04:19 pm