API Reference
Namespaces
Classes
Events
Global
Externals

Class: Visualization

CIQ. Visualization


new Visualization(attributes)

Creates a DOM object capable of receiving a data stream. The object changes as a result of the incoming data. The constructor function takes attributes that define how and where in the HTML document the object gets created. See CIQ.Visualization#setAttributes for more information on attributes.

One useful application of this is to render an SVG graphic.

Methods are provided to pass data into the object and to render it in the HTML document. Note that the data and attributes that are passed into the prototype methods of this object become owned by it and therefore can be mutated.

The DOM object-generating function can assign class names to sub elements within the object. These class names can be used to style the object using CSS. Documentation for the built-in functions explains which classes are available to be styled.

Parameters:
Name Type Description
attributes object

Parameters to be used when creating the object.

Properties
Name Type Argument Description
renderFunction function

DOM object-generating function. Takes data as an array (sorted by index property) and attributes as arguments by reference and returns an HTMLElement (which may have children).

container HTMLElement | string <optional>

Element in which to put the DOM object (or selector thereof). If omitted, a container element is created with 300 x 300 pixel dimensions.

useCanvasShim boolean <optional>

Set to true to relocate the container behind the canvas but in front of the gridlines. Note: Consider using CIQ.ChartEngine#embedVisualization; it automatically places the object within the canvases.

stx CIQ.ChartEngine <optional>

A reference to the chart engine. Required if using the canvas shim.

id string <optional>

Optional id attribute to assign to the object.

forceReplace boolean <optional>

True to force a complete replacement of the DOM object when data changes. Do not set if renderFunction can handle an incremental update of the object. Alternatively, renderFunction might set this attribute. When attributes are updated using setAttributes, a complete replacement occurs.

document HTMLDcument <optional>

Optional document where visualization should be rendered.

Since:
  • 7.4.0
  • 8.5.0 Added the attributes.document parameter.
Example
let svg=new CIQ.Visualization({ renderFunction: CIQ.SVGChart.renderPieChart });
svg.updateData({"Low":{name:"low", value:30}, "High":{name:"high", value:70}});

Members


attributes :object

READ ONLY. The attributes used to render the DOM object. See the function description for details. Do not change this property directly; instead, use CIQ.Visualization#setAttributes.

Type:
  • object
Since:
  • 7.4.0


container :HTMLElement

READ ONLY. The DOM container that hosts the DOM object.

Type:
  • HTMLElement
Since:
  • 7.4.0


data :object

READ ONLY. The data used to render the DOM object. See the function description for details. Do not change this property directly; instead, use CIQ.Visualization#updateData.

Type:
  • object
Since:
  • 7.4.0


object :HTMLElement

READ ONLY. The DOM object created by the rendering function.

Type:
  • HTMLElement
Since:
  • 7.4.0

Methods


destroy(soft)

Removes the DOM object. If the container was generated by this object, the container is also removed.

Parameters:
Name Type Description
soft boolean

True to leave properties of this object alone. Setting to false is preferable.

Since:
  • 7.4.0


draw(forceReplace)

Draws the DOM object in its container. Data must be set using CIQ.Visualization#updateData prior to calling this function. Any content existing within the container is removed prior to drawing the object.

Parameters:
Name Type Description
forceReplace boolean

Indicates whether a full redraw is requested.

Since:
  • 7.4.0


setAttributes(arg1 [, arg2])

Adds or changes the visualization object attributes, and then calls the draw function.

The following generic attributes are available to all objects; all attributes are passed into the object-generating function and may be used there:

  • renderFunction
  • container
  • stx
  • useCanvasShim
  • id
  • forceReplace

Attributes are passed into renderFunction, the object-generating function; and so, additional attributes can be added specific to the function.

Note: The attributes passed into renderFunction can be changed by the render function when necessary. You can set either one attribute by passing in a key and a value, or you can add a set of attributes by passing in an object of key/value pairs.

Parameters:
Name Type Argument Description
arg1 object | string

An attribute key or an object of attribute key/value pairs.

arg2 * <optional>

The value of the attribute if passing in one key and value.

Since:
  • 7.4.0


updateData(data [, action])

Adds or changes the visualization object data, and then calls the draw function.

Parameters:
Name Type Argument Description
data object | array

Provides data used to generate the DOM object. Contains at a minimum a name, a value, and an optional index, which specifies sort order. The data must accommodate the update action.

action string <optional>

The action to take when generating the DOM object. Valid actions are "add", "update", "delete", and "replace" (default).

The data object provides each action with the required data.

Action Required Data
replace A full data object.
delete The data records to remove. Note: This may affect the colors used in the chart.
update The data records to update. The existing records will have their properties replaced with the new properties, leaving all non-matching properties alone.
add The same as the "update" action except the value property of the existing data is augmented instead of replaced by the new value.

See the examples below.

Note: If only the value property is being changed, it may be passed as a raw number rather than being assigned to an object property.

Since:
  • 7.4.0

Returns:

This object.

Type
CIQ.Visualization
Example

Given a CIQ.Visualization instance obj:

obj.updateData({"up",{value:1}},"add") // Adds 1 to the value property of the data record "up".
obj.updateData({"up":1},"add") // Also adds 1 to the value property of the data record "up".
obj.updateData({"up",{name:"UP"}},"update") // Updates the name property of the data record "up" to "UP".
obj.updateData({"down",null},"delete") // Removes the record "down".
obj.updateData({"down",{value:6}},"update") // Updates the value property of the data record "down" to 6.
obj.updateData({"down",0},"update") // Updates the value property of the data record "down" to 0.
obj.updateData({"up":5,"down":4},"replace") // Replaces the entire data record with the new record.
obj.updateData({"up":5,"down":4}) // Same as above; "replace" is the default action.