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

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:

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.

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.

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.

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.

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 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.

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.

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:

and also:

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

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:

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:

allow change of the default visual style of a chart, from colors to text formatting and alignment, etc.

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.

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).

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.

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:

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.

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:

pvc.visual.Scene

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.

DOM

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.

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

pvc.visual.Sign

Property

Type

Description

Color

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.

Interactivity

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.

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:

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:

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.

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.

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:

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:

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:

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:

Data dimensionscan (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:

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.

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: