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.

Attribute Type Info
BUILDCODE Array

Array of strings that denote our encrypted license keys.

['license_hash_key', 'zingchart.com']

LICENSE Array

Array of strings that denote our encrypted license keys.

['license_hash_key1', 'license_hash_key2']

LICENSEKEY Array

Array of strings that denote our encrypted license keys.

['license_hash_key1', 'license_hash_key2']

ASYNC Boolean

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

bind Function

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

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

exec Function

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

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

FONTFAMILY String

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

"Arial" | "Helvetica" | ...

FONTSIZE Numeric

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

9 | 11 | ...

MODULESDIR    
unbind Function

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

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

ZCOUTPUT Boolean

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

true | false | 1 | 0

SYNTAX String

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

dashed | mixed

EXPORTURL String

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

AJAXEXPORT Boolean

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

DEV Object

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({...})
Attribute Type Info
CACHECANVASTEXT Boolean

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

true | false | 1 | 0

CACHESELECTION Boolean

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

true | false | 1 | 0

CHECKDECIMALS Boolean

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

true | false | 1 | 0

COPYDATA Boolean

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

KEEPSOURCE Boolean

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

true | false | 1 | 0

MEDIARULES Boolean

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

PLOTSTATS Boolean

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

true | false | 1 | 0

SKIPTRACKERS Boolean

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

true | false | 1 | 0

SKIPPROGRESS Boolean

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

SORTTOKENS Boolean

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

RESOURCES Boolean

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 
});
Attribute Type Default Info
auto-resize
autoResize
Boolean   true | false | 1 | 0
background-color
backgroundColor
String   "none" | "transparent" | "#f00" | "#f00 #00f" | "red yellow" | "rgb(100, 15, 15)" | ...
bgcolor String   "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 | ...

cache Object    
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"

color String   "none" | "transparent" | "#f00" | "#f00 #00f" | "red yellow" | "rgb(100, 15, 15)" | ...
container String   "mydiv_id"
csvdata String null "..."
customprogresslogo String  

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" | ...

data Object null

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

{...}

dataurl String   "myjson.php" | "http://www.domain.com/myjson.php" | ...
defaults Object   {...}
defaultsurl String null "mydefaults.php" | "http://www.domain.com/mydefaults.php" | ...
events Object {}  
exportdataurl String   "dataexportscript.php" | ...
exportimageurl String   "imageexportscript.php" | ...
fullscreen Boolean false true | false | 1 | 0
height Mixed 450px

To set the height of the chart.

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

hideprogresslogo Boolean false

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

id String null

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"

locale String   "en_us" | "fr" | "es" | ...
output Strings svg "canvas" | "svg" | "vml" | "auto"
width Mixed 100% 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 ...
});
Attribute Type Info
apicall String

The name of the API call.

"reload" | "resize" | ...

id String

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 ...
});
Attribute Type Info
eventName String

The name of the event.

"load" | "complete" | ...

handler Function

Handler fired when the event takes place.

function(params) {...}

id String

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 ...
});
Attribute Type Info
eventName String

The name of the event.

"load" | "complete" | ...

handler Function

Handler fired when the event takes place.

function(params) {...}

id String

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);
Attribute Type Info
BUILDCODE Array

Array of strings that denote our encrypted license keys.

['license_hash_key', 'zingchart.com']

LICENSE Array

Array of strings that denote our encrypted license keys.

`['license_hash_key1', 'license_hash_key2']`

LICENSEKEY Array

Array of strings that denote our encrypted license keys.

`['license_hash_key1', 'license_hash_key2']`

VERSION String

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.