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
|
- 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
, avalue
, and an optionalindex
, which specifies sort order. The data must accommodate the updateaction
.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
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.