RingChart - Documentation

Properties

dataTipRenderer :function (internal.dataTipRenderer)

The dataTipRenderer is used to customize the data tip that is shown on mouse-over events. You can append to or modify the 'tip' parameter to customize the data tip. You can also return modified x, y coordinates to place the data tip in a different location.

CAUTION: The default datatip is designed to work with series.dataTipLabels. Be sure to factor that into any custom datatips you may create.

Example

// tip - html DIV element
// e - svg rect of the bar being moused over
// d - datum
// i - datum index
// j - group index (optional)
// x - suggested x position of data tip
// y - suggested y position of data tip
// return {Array} [x, y] - x and y coordinates placing data tip.

function dataTipRenderer(tip, e, d, i, x, y) {
 if (!d.series.dataTipLabels) return false;

 var bounds = e.getBoundingClientRect();
 var x1 = d3.event.pageX; //- bounds.left;
 var y1 = d3.event.pageY; //- bounds.top;

 var tipLabels = d.series.dataTipLabels(d, d.data, i)

 var html = '<div class="vz-tip-header1">HEADER1</div>' +
	'<div class="vz-tip-header-rule"></div>' +
	'<div class="vz-tip-header2"> HEADER2 </div>' +
	'<div class="vz-tip-header-rule"></div>' +
	'<div class="vz-tip-header1"> HEADER3 </div>';

 html = html.replace("HEADER1", tipLabels[0]);
 html = html.replace("HEADER2", tipLabels[1]);
 html = html.replace("HEADER3", tipLabels[2]);

 tip.html(html);

 return [x1 - 100, y1 - 150 - (d.series.plotType == viz.PLOT_BAR_STACKED ? 40 : 0)];
}

dateRange :Functor (function () { return [d3.min(scope.series[0].data, function (d) { return scope.series[0].x(d)}), d3.max(scope.series[0].data, function (d) { return scope.series[0].x(d)})]},)

Functor that returns an [min, max] array as a range of dates to be plotted. This allows you plot time series that may have different start/end dates and clamp them by a given a range.

duration :Number (500)

Duration (in milliseconds) of any component transitions.

expandTicksOnHover :Number (true)

True allows ticks marks to expand radially on mouse hover. False keeps ticks stationary.

gutterAngle :Number (30)

Determines the radial angle of the gutter (where series labels are plotted) in degrees

height :Number/String (600)

Height of component in either pixels (Number) or percentage of parent container (XX%)

Example

viz.height(600) or viz.height('100%');

innerRadius :Number/String (100)

Determines the inner radius of the chart in either pixels (Number) or percentage of parent container (XX%)

lineAreaCurve :d3.curve (d3.curveBasisOpen)

Curve vertex type to use for LineArea series.

margin :Object ({top:'5%', bottom:'5%', left:'5%', right:'5%'})

Margins between component render area and border of container. This can either be a fixed pixels (Number) or a percentage (%) of height/width.

outerRadius :Number/String (290)

Determines the outer radius of the chart in either pixels (Number) or percentage of parent container (XX%)

ringPadding :Number (.025)

Determines the spacing between ring series as a percentage of the outer radius

series :Array (Needs to be set at runtime)

Array of series objects.

series.plotRatio - Float represents percentage of radius to be used for series ring radius - REQUIRED

series.plotType - String representing plot type. REQUIRED

  viz.PLOT_BAR_STACKED, viz.PLOT_LINE_AREA, viz.PLOT_SCATTER

series.x - Functor that returns x(angle) position of datum. REQUIRED

series.y - Functor that returns y(radial) position of datum. REQUIRED

series.dataTipLabels - Functor that returns 3 element array for 3 data tip label values - OPTIONAL

series.styles - Object that contains any "series-.." styles to be overriden for this series - OPTIONAL

series.valueRange - Functor that returns array [min, max] of y values to be used in plot scale. - OPTIONAL

Example

var tempSeries = {};
tempSeries.data = laTemps;
tempSeries.label = 'Temps';
tempSeries.x = function (d, i) { return d.Date; };
tempSeries.y = function (d) { return [d.TempMax] };
tempSeries.plotType = viz.PLOT_BAR_STACKED;
tempSeries.valueRange =  function (series) {
 return [
  d3.min(series.data, function (d, i) { return d3.sum(series.y(d, i))}),
  d3.max(series.data, function (d, i) { return d3.sum(series.y(d, i))})
 ]
};
tempSeries.plotRatio = .35;
tempSeries.dataTipLabels = function (d, datum, index) {
 return [
  'Low: ' + d3.format(',')(Math.round(datum.TempMin)) + '°F',
  'High: ' + d3.format(',')(Math.round(datum.TempMax)) + '°F',
  d3.timeFormat('%b %d, %Y')(datum.Date)
 ]
}
tempSeries.styles = {
 'series-bar-fill': function (d, i, index) { return tempScaleColorClimate(d.TempMax) },
 'series-bar-fill-opacity': 0.5
}

var pollutionSeries = {};
pollutionSeries.data = pollution;
pollutionSeries.label = 'Pollution';
pollutionSeries.x = function (d, i) { return d.Date; };
pollutionSeries.y = function (d) { return d.AQI };
pollutionSeries.plotType = viz.PLOT_LINE_AREA
pollutionSeries.plotRatio = .2;
pollutionSeries.dataTipLabels = function (d, datum, i) {
 return [
  'Particulate: ' + d3.format(',.2f')(datum.PM2_5),
  'Air Quality Index: ' + d3.format(',.2f')(datum.AQI),
  d3.timeFormat('%b %Y')(datum.Date)
 ]
}
pollutionSeries.styles = {
  'series-area-fill': function (d, i, index) {
    return "url(#" + vizuly2.svg.gradient.radialFade(viz, '#000', [1, .25], [.8, 1]).attr("id") + ")";
  },
  'series-area-fill-opacity': .7,
  'series-line-stroke-over': '#390ed5',
  'series-area-fill-over': '#E64A19'
 }

viz.series([tempSeries, pollutionSeries])

width :Number/String (600)

Width of component in either pixels (Number) or percentage of parent container (XX%)

Example

viz.width(600) or viz.width('100%');

xAxis :d3.axis (d3.axisBottom)

D3 Axis used to render x (radial) axis. This axis can be overriden with custom settings by capturing the 'measure' event.

Example

viz.on('measure', function () { viz.xAxis().tickSize(10) }) //Sets each axis tick to 10 pixels

xMinorTickCount :Number (8)

Number of minor ticks between major ticks on x-axis

xTickCount :Number (10)

Number of major ticks to use on x-axis

xTickFormat :function (function (d) { return d })

Label formatter for the x axis. Can be customized to modify labels along axis.

Example

//Sets each axis tick label to a date month/year format.
viz.xTickFormat(function (d) { return d3.timeFormat('%m/%y')(d)} })

xTickFormatHover :Functor (function (d) { return d3.timeFormat('%b %d, %Y')(d) })

Format for x radial outer label on mouse hover

xTickLengthMajor :Functor (function (d) { return (outerRadius - innerRadius) * .04 })

Determines the length of major ticks

xTickLengthMinor :Functor (function (d) { return (outerRadius - innerRadius) * .02; })

Determines the length of minor ticks

Methods

applyCallbacks()

Used to set listeners to multiple events at once.

This method is usually called internally from a vizuly2.core.component to set listeners for style specific methods.

Example

var stylesCallbacks = [
   {on: 'updated.styles', callback: applyStyles},
   {on: 'mouseover.styles', callback: styles_onMouseOver},
   {on: 'mouseout.styles', callback: styles_onMouseOut}
 ];

 viz.applyCallbacks(stylesCallbacks);

applyStyles(styles)

Used to apply a collection of styles at one time

Parameters:

Name	Type	Description
`styles`	String	A style collection object

Example

var blueStyles =
  {
    'background-color-top': '#021F51',
    'background-color-bottom': '#039FDB',
    'value-label-color': '#FFF',
    'x-axis-label-color': '#FFF',
    'y-axis-label-color': '#FFF',
  	 'bar-fill': '#02C3FF',
  	 'axis-stroke': '#FFF',
  	 'bar-radius': 0
  }

 viz.applyStyles(blueStyles);

clearStyles()

Used to clear all runtime styles and set all styles back to components default style settings.

destroy()

Removes the component from the DOM and removes all event listeners. Typically this is called when a page programmer is removing the component from memory and wants to free the component up for garbage collection by the browser.

getStyle(style, args)

Used by the component at runtime to get the current value for a given style. This can be either the default style or runtime applied styles.

The value returned could be either a static value, or a result of a dynamic function that calculates the style at runtime.

Parameters:

Name	Type	Description
`style`	String	Name of the style
`args`	Array	Any arguments that need to be passed to the style functor

Example

// This sets all '.vz-bar' elements with a fill matching the 'bar-fill-color' style
 selection
 .selectAll('.vz-bar')
 .style('fill', function (d,i) { return viz.getStyle('bar-fill-color',arguments); });

id()

Returns a unique identifier that has been auto generated at instantiation. This ensures that multiple components of the same type will have a unique DOM id

Example

// Returns the viz parent DIV element
 document.getElementById(viz.id());

 // Alternatively you can also use
 viz.selection();

on(event, listener)

Used to set listeners to component events. Passing a null listener value will clear the event listener

Note: You can use event namespaces (D3.dispatch) to set multiple listeners for a single event

Parameters:

Name	Type	Description
`event`	String	of event to be listened for
`listener`	function	function used to capture emited event

Example

// Sets a listener to the update event
 viz.on('update', myListenerFunction);

 // Sets two namespace specific listener to a mouseover event
 viz.on('mouseover.module_1', myModule1ListenerFunction);
 viz.on('mouseover.module_2', myModule2ListenerFunction);

 // Clears the event listener for the update event
 viz.on('update', null);

onChange(Property, Listener)

Used to capture any component property change events.

Parameters:

Name	Type	Description
`Property`	String	name of change event to be listened for
`Listener`	function	function used to capture emited event

Example

// Listens for any changes to the data property
 viz.onChange('data', myListenerFunction);

parent()

Returns the parent DOM element the component appended to.

removeDataTip()

Used by internally components to remove a data tip. This is usually called on a mouseout event.

selection()

Returns a d3.selection of the component's DIV container that was created at component instantiation.

showDataTip(e, d, i, j)

Used internally by components to display a data tip. This is usually called on a mouseover event.

Parameters:

Name	Type	Description
`e`	DOMElement	The target element that triggered the call
`d`	Object	The datum associated with the triggering event
`i`	Number	The index associated with the datum
`j`	Number	Optional - The series (if one exists) asscoiated with the datum

size()

Returns a size object based on the components internal measure function with absolute pixel values. This is helpful for applying styles/decorations after the component has rendered and you want to know specific measurements of the component.

Example

size.top
size.left
size.height
size.width

style(style, value)

Used to set, retrieve and clear runtime styles

Parameters:

Name	Type	Description
`style`	String	Name of the style
`value`	function	Value of the style

Example

// Retrieves a current style value (either runtime style of default style)
 viz.style('myStyleName');

 // Sets a new style value
 viz.style('myStyleName', myStyleValue);

 // Clears a runtime style (default styles will still be active)
 viz.style('myStyleName', null);

(static) update()

Triggers the render pipeline process to refresh the component on the screen.

updateOnResize(resize, delay)

This function can be used to dynamically update a component when the window is resized. Typically this is used when the viz.size() or viz.width() is set to a percentage. A default delay of 50 milliseconds is used to buffer resize events and prevent the component from repeatedly updating while the user is resizing the window. This delay can be modified as seen in the delay parameter below.

Parameters:

Name	Type	Description
`resize`	Boolean	A `true` value will call viz.update() when the user resizes the window. A `false` value will cancel the resize.
`delay`	Number	Optional. The time in milliseconds to wait between resize events before calling `viz.update()`

Example

// Sets the width of the component to 100% and uses the resizeOnUpdate with a 100ms delay buffer.
 viz.width('100%').updateOnResize(true, 100);

validate()

Validates that all public properties (passed in props param) have non null values.

This method is usually called internally from a vizuly2.core.component measure function.

Events

In addition to component specific events, all components natively support these events produced by the vizuly2.core.component factory:

initialized, measured, styled, updated, validated

All Events can be accessed via the viz.on('eventName', myEventListener) format.

// Sets a listener to the update event
 viz.on('updated', myListenerFunction);

 // Sets two namespace specific listener to a mouseover event
 viz.on('mouseover.module_1', myModule1ListenerFunction);
 viz.on('mouseover.module_2', myModule2ListenerFunction);

 // Clears the event listener for the update event
 viz.on('updated', null);

click :VizulyEvent

Fires when user clicks a bar.

Parameters:

Name	Type	Description
`e`		DOM element that fired event
`d`		Datum associated with DOM element
`i`		Index of datum in display series
`this`		Vizuly Component that emitted event

Example

viz.on('click', function (e, d, i) { ... });

initialized :VizulyEvent

Fires after component initialize() method has been called.

Parameters:

Type	Description
VizulyComponent	viz - The viz that emited the event

measured :VizulyEvent

Fires after component measure() method has been called

Parameters:

Type	Description
VizulyComponent	viz - The viz that emited the event

mouseout :VizulyEvent

Fires when user moves the mouse off a bar.

Parameters:

Name	Type	Description
`e`		DOM element that fired event
`d`		Datum associated with DOM element
`i`		Index of datum in display series
`this`		Vizuly Component that emitted event

Example

viz.on('mouseout', function (e, d, i) { ... });

mouseover :VizulyEvent

Fires when user moves the mouse over a bar.

Parameters:

Name	Type	Description
`e`		DOM element that fired event
`d`		Datum associated with DOM element
`i`		Index of datum in display series
`this`		Vizuly Component that emitted event

Example

viz.on('mouseover', function (e, d, i) { ... });

styled :VizulyEvent

Fires after component applyStyles() method has been called.

Parameters:

Type	Description
VizulyComponent	viz - The viz that emited the event

updated :VizulyEvent

Fires after component update() method has been called.

Parameters:

Type	Description
VizulyComponent	viz - The viz that emited the event

validated :VizulyEvent

Fires after component validate() method has been called.

Parameters:

Type	Description
VizulyComponent	viz - The viz that emited the event