component

The vizuly2.core.component is a factory method used to create vizuly components. All vizuly components use this factory method to instantiate their public properties, styles, and events. This factory performs the following functions. All methods described below are common across all vizuly components.

  • Appends a DIV container to the parent DOM object being passed in and assigns it an unique runtime id. This DIV container is accessed via the viz.selection() function.

  • Binds all public property accessors to the components scope variable. This properties can then be accessed internally by the component via scope.myProperty. External access to these properties can be accessed via viz.myProp() to retreive the current value, and viz.myProp(newValue) to set a new value. These properties can be either static values or dynamic functions.

  • Creates dynamic functors and accessors for all styles. Styles can be accessed external to the component via the viz.style(myStyleName) call or set via the viz.style(myStyleName, myStyleValue). Runtime styles can be cleared by passing a null value via viz.style(myStyleName, null)

  • Creates universal component lifecycle events (initialized, validated, measured, updated, styled)

  • Creates a event dispatcher for all custom events being passed in.

  • Creates change events and associated watchers for all public component properties

Parameters:
Name Type Description
parent DOMElement

Container element that will render the component.
scope Object

The scope variable to be referenced by the component.
styles Object

The style object collection for the component
events Array

An array of component specific event names to be used by the component.

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

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

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

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