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 | Array | Array of strings that denote our encrypted license keys.
|
| LICENSEKEY | Array | Array of strings that denote our encrypted license keys.
|
| 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 {...} |
| 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 "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 | 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.