ZingChart Object and Methods

Overview

The ZingChart object contains properties to set global attributes such as general font face or size. The object also contains three important methods: the render method (zingchart.render()), which controls the rendering formats and characteristics to display the chart; the exec method (zingchart.exec()), which provides a mechanism to invoke various API calls on a chart; and the bind (zingchart.bind()) and unbind (zingchart.unbind()) methods, which listen for events that occur in the chart, and then do something with that event.

ZingChart Object

The ZingChart object contains the necessary properties and methods for chart rendering.

Note: As of v2.9.0, we recommend using the LICENSE on the zingchart object with zingchart.LICENSE. This was previously set on the ZC.

AttributeTypeInfo
BUILDCODEArray

Array of strings that denote our encrypted license keys.

['license_hash_key', 'zingchart.com']

LICENSEArray

Array of strings that denote our encrypted license keys.

['license_hash_key1', 'license_hash_key2']

LICENSEKEYArray

Array of strings that denote our encrypted license keys.

['license_hash_key1', 'license_hash_key2']

ASYNCBoolean

Renders the chart in "steps", providing faster (but incremental) visual results. This is useful in case of big charts that take longer time to render.

true | false | 1 | 0

bindFunction

Binds an event to a chart (or to all charts in a page).

zingchart.bind("id", "eventName", function() {...})

execFunction

The API entry method, used to call various API commands against the chart.

zingchart.exec("id", "call", {...})

FONTFAMILYString

Global setting for the font family used by all the elements of the library.

"Arial" | "Helvetica" | ...

FONTSIZENumeric

Global setting for the font size used by all the elements of the library.

9 | 11 | ...

MODULESDIR  
unbindFunction

Unbinds an event from a chart (or from all charts in a page).

zingchart.bind("id", "eventName", function() {...})

ZCOUTPUTBoolean

Sets whether an optional parameter called zcoutput, containing the rendering option, will be passed for every data request.

true | false | 1 | 0

SYNTAXString

Sets whether the library converts input JSON syntax from camel case to dashed.

dashed | mixed

EXPORTURLString

Sets the export URL for where the library will send ajax requests when exporting PDFs. If `AJAXEXPORT` is turned on, then images will also be rendered on the server, but currently images are rendered client side using Canvas and blobs.

https://export.zingchart.com | https://customExportUrl.com

AJAXEXPORTBoolean

Sets whether the library uses the export server for all exports. Currently, the default is false since chart images are rendered on the client side using Canvas and blobs. Setting this to true will force a server export.

false | true

DEVObject

Object that contains performance flags for various rendering paths within the ZingChart engine. DO NOT OVERRIDE THIS.

{}

DEV

The zingchart.DEV object flags are for turning on and off rendering paths within the ZingChart rendering engine. These are globals, for all charts on the page, and MUST be defined before the zingchart.render() method.

// prevents lib from storing the original data package
zingchart.DEV.KEEPSOURCE = false;
// prevents lib from creating a copy of the data package instead of working with the provided one (which can be altered) 
zingchart.DEV.COPYDATA = false; 

zingchart.render({...})
AttributeTypeInfo
CACHECANVASTEXTBoolean

To use a cache object for storing text objects when rendering in Canvas. Default is false.

true | false | 1 | 0

CACHESELECTIONBoolean

To use a cache object for storing chart selected states. Default is false.

true | false | 1 | 0

CHECKDECIMALSBoolean

Shortcut in rendering logic for checking decimals. If turned on, will be slower. Default is false.

true | false | 1 | 0

COPYDATABoolean

If set to false, prevents the library from creating a copy of the data package (object) instead of working with the provided one (which can be altered since it's passed by reference). Default is true.

true | false | 1 | 0

KEEPSOURCEBoolean

If set to false, prevents the library from storing the original chart JSON data object. Default is true.

true | false | 1 | 0

MEDIARULESBoolean

If set to false, prevents the library from looking down the chain of `mediaRule` objects defined through the chart configuration. Default is true.

true | false | 1 | 0

PLOTSTATSBoolean

If set to false, skips calculations of several plot relates statistics (min, max, sum, avg values). Default is true.

true | false | 1 | 0

SKIPTRACKERSBoolean

If set to false, skips setting event tracking on nodes. Default is true.

true | false | 1 | 0

SKIPPROGRESSBoolean

If set to false, skips the intro loading screen. This loading screen is most likely invisible to human eye (< 222ms) on the average case. Default is false.

true | false | 1 | 0

SORTTOKENSBoolean

If set to false, forces the library to accept only long tokes (e.g., %node-value instead of %v), saving some parsing time. Default is true.

true | false | 1 | 0

RESOURCESBoolean

If set to false, indicates to the library that there are not external image resources to load. Skip this rendering path. Default is true.

true | false | 1 | 0

Render Method

The ZingChart render method is used to set various chart render options. At a minimum, you must specify the id and data elements for the chart to properly render and display.

zingchart.render({ 
  id: 'myChart', 
  data: { ... }, 
  height: 400, 
  width: 600 
});
AttributeTypeDefaultInfo
auto-resize
autoResize
Boolean true | false | 1 | 0
background-color
backgroundColor
String "none" | "transparent" | "#f00" | "#f00 #00f" | "red yellow" | "rgb(100, 15, 15)" | ...
bgcolorString "none" | "transparent" | "#f00" | "#f00 #00f" | "red yellow" | "rgb(100, 15, 15)" | ...
border-color
borderColor
String "none" | "transparent" | "#f00" | "#f00 #00f" | "red yellow" | "rgb(100, 15, 15)" | ...
border-width
borderWidth
Numeric 

To set the width of the chart.

1 | 5 | ...

cacheObject  
cache-control
cacheControl
String 

ZingChart has a default set of headers when making requests to external assets. You can control and turn that off on an individual chart basis on render.

"http-headers" | "query-string" | "none"

colorString "none" | "transparent" | "#f00" | "#f00 #00f" | "red yellow" | "rgb(100, 15, 15)" | ...
containerString "mydiv_id"
csvdataStringnull"..."
customprogresslogoString 

Allows user to specify what image appears on the loading screen, in lieu of the default ZingChart logo. Refer to our documentation on Removing ZingChart Branding for more information.

"image.png" | ...

dataObjectnull

The chart data. For the chart to properly render, this and the id element are required.

{...}

dataurlString "myjson.php" | "http://www.domain.com/myjson.php" | ...
defaultsObject {...}
defaultsurlStringnull"mydefaults.php" | "http://www.domain.com/mydefaults.php" | ...
eventsObject{} 
exportdataurlString "dataexportscript.php" | ...
exportimageurlString "imageexportscript.php" | ...
fullscreenBooleanfalsetrue | false | 1 | 0
heightMixed450px

To set the height of the chart.

300 | "100%" | "auto" | ...

hideprogresslogoBooleanfalse

To hide or remove the ZingChart logo that appears on the loading screen (generally only visible on charts with larger datasets). Refer to our documentation on Removing ZingChart Branding for more information.

true | false | 1 | 0

idStringnull

The element in the HTML document where you want the chart to render. For the chart to properly render, this and the data element are required.

"mydiv_id"

localeString "en_us" | "fr" | "es" | ...
outputStringssvg"canvas" | "svg" | "vml" | "auto"
widthMixed100%300 | "100%" | "auto" | ...

API Methods

The exec method is used with API methods, allowing you to act upon your chart (e.g., adding nodes, removing nodes). Refer to our documentation on API Methods for more information.

Exec Method

The API entry method, used to call various API commands against the chart.

zingchart.exec(id,'apicall',{
 ... options ...
});
AttributeTypeInfo
apicallString

The name of the API call.

"reload" | "resize" | ...

idString

The ID of the chart.

"mydiv" | ...

Bind Method

Binds an event to a chart (or to all charts in a page).

zingchart.bind('id','eventName',function(event){ 
  ... event.value ...
});
AttributeTypeInfo
eventNameString

The name of the event.

"load" | "complete" | ...

handlerFunction

Handler fired when the event takes place.

function(params) {...}

idString

The ID of the chart or null if event is bound to all the charts in a page.

"mydiv" | null | ...

Unbinds an event from a chart (or from all charts in a page).

zingchart.unbind('id','eventName',function(event){ 
  ... event.value ...
});
AttributeTypeInfo
eventNameString

The name of the event.

"load" | "complete" | ...

handlerFunction

Handler fired when the event takes place.

function(params) {...}

idString

The ID of the chart or null if event is bound to all the charts in a page.

"mydiv" | null | ...

ZC Object

The ZC object contains various global information that we use internally for caching and code re-use. This object also contains some useful user information, like the version and license key.

Note: As of v2.9.0, you can now use all licensing on the zingchart object with zingchart.LICENSE. This decision was made because the ES6 version was exporting two variables and the license was the only user functionality held in the ZC object.

console.log(ZC.VERSION);
console.log(ZC.LICENSEKEY);
AttributeTypeInfo
BUILDCODEArray

Array of strings that denote our encrypted license keys.

['license_hash_key', 'zingchart.com']

LICENSEArray

Array of strings that denote our encrypted license keys.

`['license_hash_key1', 'license_hash_key2']`

LICENSEKEYArray

Array of strings that denote our encrypted license keys.

`['license_hash_key1', 'license_hash_key2']`

VERSIONString

The current version of the library.

Summary

The ZingChart object is essentially the runner of ZingChart, allowing you to set higher-level settings and render charts. For more information, see the ZingChart render method and ZingChart modules pages.