Namespace: debugger - FusionCharts XT Suite Documentation

The debugger is used to trace errors within charts and verify the flow of events for a chart in case of unexpected behaviors. The debugger logs all activities resulting from firing of all events in the framwork.

For more information on how to enable the debugger, refer to FusionCharts.debugger.enable.

The debugger should not be used in a production environment. It is intended only to be used in development or staging.

To ensure compatibility with older versions of Internet Explorer, the debugger object should be called as FusionCharts['debugger'] instead of FusionCharts.debugger.

Example

// Use the debugger to output the debugger messages to JavaScript console.
FusionCharts["debugger"].enable(true, function (message) {
    console.log(message);
});

Members

<inner> errorNatures

The debugging events FusionCharts.debugger#event:error and FusionCharts.debugger#event:warning pass on the "nature" of the error/warning as its argument. The value of this argument is one from the following list - giving a summary of the category of the error/warning raised.

Name	Description
`TypeException`	Type mismatch of an input being processed. For example, `null` or `undefined` has been found in an operation where only `string` type of data is expected.
`ValueRangeException`	The error or warning event was caused due to a critical value involved during an operation is outside the acceptable range.
`ParameterException`	This exception is caused when a parameter passed on to a function is missing or is in an unacceptable format.
`RuntimeException`	When a specific combination of inputs caused a process to reach a computational error such as division by zero, mathematical operation on non-numeric values, etc - this nature of warning or error is raised.
`DesignTimeException`	Specific implementations of FusionCharts library may cause issues on specific browsers. Such issues (wherever detected) is notified as `DesignTimeException`. An example for the same would be having a chart's variable name exposed globally and also be similar to the chart's Id - this causes issue on older versions of Internet Explorer browser.
`NotImplementedException`	You've hit a jackpot! The operation that caused this error or wanning is planned, but not yet implemented. Welcome to the future!
`UnspecifiedException`	Exceptions that were trapped but specific cause of the same is not ascertained.

<inner> outputFormats

When debugger is enabled, it forwards its output to a callback function as explained in FusionCharts.debugger~debuggerCallback. The parameters that can be forwarded to this callback function can be adjusted based on the outputFormat set on the debugger. The outputFormat can be configured using the function FusionCharts.debugger.outputFormat or by passing a format to the third parameter of the function FusionCharts.debugger.enable.

The different output formats that the debugger provides are:

text - (default) Meant for simple text output from the debugger
event - Outputs the debugger messages in an event-like format, similar to FusionCharts.eventListener.
verbose - Forwards all debugger messages and its associated arrguments as separate parameters.

Properties:

Property Description

text

Type:: string

With text set as the output format of debugger, the debugger callback function receives only a single string parameter that contains details regarding the activities going on within the FusionCharts framework.

Properties

Property	Description
`message` Type: string	The single parameter that is passed on to the FusionCharts.debugger~debuggerCallback function is the error message in a pre-formatted form `#<event-id> fired "<event-name>" event.`

event

Type:: string

Function that calls the debugger method in typical FusionCharts events argument format as specified in FusionCharts~eventListener. In this format, the output callback function receives two arguments - the eventObject and the eventArgument.

Properties

Property	Description
`eventObject` Type: object	This contains details regarding the event itself - such us the name of the event, reference to the chart that raised this event, etc. More details regarding the properties of this object is at FusionCharts~eventListener.
`eventArgument` Type: object	This parameter is an object that contains information relevant to the particular event being triggered. They are specific to each event.

verbose

Type:: string

This function formats outputs with all details, and still maintains a human readable format. It is best used in conjunction with an advanced JavaScript console.

Properties

Property	Description
`eventId` Type: number	This parameter is the incremental `id` that is associated to every new event being fired. Even if the events are not received in order, their sequence of trigger can be inferred from the event Id.
`senderId` Type: string	The reference to the object that has triggered the debugger event.
`eventArguments` Type: object	This parameter is an object that contains information relevant to the particular event being triggered. They are specific to each event.

Methods

<static> outputFormat(format)

Specifies how to format the output of the function that will accept output from the debugger.

Parameters:

Parameter	Description
`format` Type: FusionCharts.debugger~outputFormats	Can be one of the accepted format names such as `text`, `verbose`, `event` as available in FusionCharts.debugger~outputFormats.

<static> outputTo(debuggerCallback)

The debugger of FusionCharts framework is cabaple of receiving all messages, logs and events that occur internally within the framework. However, the debugger has no way to output these messages. So, the FusionCharts.debugger~debuggerCallback function needs to be attached to the debugger to which all such debug messages get forwarded. This lets to output a custom function to output the message at a desired location.

This method allows specifying the function to which the debugger output will be redirected, i.e., the activities of the debgger will be forwarded to a function provided through this method.

Parameters:

Parameter	Description
`debuggerCallback` Type: FusionCharts.debugger~debuggerCallback	This is the function to which the debugger output will be passed on. Sending the value as `null` removes (detaches) the `debuggerCallback` and subsequently disables the debugger.

Example

<!-- In this example we will render a chart and output the debugger
     messages to an area within the page. -->
<html>
<head>
<script type="text/javascript" src="fusioncharts.js"></script>
<script type="text/javascript">
FusionCharts["debugger"].outputTo(function (message) {
    document.getElementById('debugger-output').innerHTML += '<p>' +
        message + '</p>';
});
FusionCharts["debugger"].enable(true);

// Render a chart
FusionCharts.ready(function () {
    FusionCharts.render({
        type: 'pie2d',
        renderAt: 'chart-container',
        dataSource: {
            chart: {
                caption: 'Sales Summary',
                numberPrefix: '$'
            },
            data: [
                { value: 234, label: 'Q1' },
                { value: 167, label: 'Q2' },
                { value: 110, label: 'Q3' },
                { value: 36, label: 'Q4' }
            ]
        }
    });
});
</script>

<!-- Style the debugger output to fix it in top right cormer of the page -->
<style type="text/css">
#debugger-output {
    position: absolute;
    top: 0;
    right:0;
    width: 300px;
    height: 125px;
    overflow: auto;
}
</style>
</head>
<body>
    <!-- we create a div element and position it in top
         right corner of the page -->
    <div id="debugger-output"></div>
    <div id="chart-container"></div>
 </body>
 </html>

<static> enable(state, outputTo, outputFormat) → {boolean}

The FusionCharts debugger is not enabled by default. This method allows us to enable the debugger and also optionally provide basic debugger configuration.

The debugger works in conjunction with the browser's JavaScript console or any other special console-like implementation that you may have. To enable the debugger, call this function and pass a callback that outputs the message to the JavaScript console. The code would log the activities of every chart and the entire framework.

FusionCharts['debugger'].enable(true, function (message) {
    console.log(message);
});

If you have added this code right after including the fusioncharts.js script in a page that renders a single chart with id "myChart", your output would look somewhat like:

#1 [FusionCharts] fired "ready" event.
#2 [myChart] fired "beforeinitialize" event.
#3 [myChart] fired "beforedataupdate" event.
#4 [myChart] fired "dataupdated" event.
#5 [myChart] fired "initialized" event.
#6 [myChart] fired "beforerender" event.
#7 [myChart] fired "internal.loaded" event.
#8 [myChart] fired "internal.drawstart" event.
#9 [myChart] fired "dataloaded" event.
#10 [myChart] fired "internal.domelementcreated" event.
#11 [myChart] fired "loaded" event.
#12 [myChart] fired "drawcomplete" event.
#13 [myChart] fired "rendercomplete" event.

The output clearly shows that FusionCharts declared itself as ready and then the chart followed the routine of initialising itself, loading data, loading dependencies and then completing the rendering process. Had there been any error, it would have reflected in the output.

The debugger is not intended to be kept enabled on a production server since it has performance and memory requirement overhead. It is meant for pre-production debugging only.

Parameters:

Parameter	Description
`state` Type: boolean	Specifies whether to enable logging of debug information.
`outputTo` Type: FusionCharts.debugger~debuggerCallback Attributes: <optional>	The function to which the debugger output will be passed on.
`outputFormat` Type: FusionCharts.debugger~outputFormats Attributes: <optional> Default: "text"	Can be one of the accepted format names such as "text", "verbose", "event".

Returns:

The current 'enable' state of the debugger.

Type:

boolean

<static> enableFirebugLite()

(experimental) This method fetches FirebugLite component's code and adds it to current page. Subsequently, on load of the script it enables advanced console logging to it. This is very useful for debugging on older Internet Explorer browsers and on mobile device browsers that do not have a JavaScript debugging console.

Visit http://getfirebug.com/firebuglite for more information on this very popular component. This function fetches the script from their latest stable release channel as mentioned in http://getfirebug.com/firebuglite#Stable

Type Definitions

Error-1110111515A

AJAX runtime error. Raised when AJAX transactions raise error (security or others). The error message describes the nature of the error.

Type:

RuntimeException

Error-25081840

This error occurs when the FusionCharts constructor is called without the new keyword and also without passing a reference chart id as the parameter. In case you are rendering a new chart, ensure you do a new FusionCharts({}); or in case you are using the constructor as a getter, ensure you pass the chart Id (string) as first parameter.

Type:

RuntimeException

Error-06091847

This error occurs when a new chart is created (instantiated) with the an id that has been already assigned to an existing chart. Change the chart Id or dispose the other chart with the duplicate id.

Type:

ParameterException

Error-03091549

The event name has not been provided while adding an event listener. Ensure that you pass a string to the first parameter of FusionCharts.addEventListener.

Type:

ParameterException

Error-03091550

The event listener passed to FusionCharts.addEventListener needs to be a function.

Type:

ParameterException

Error-03091560

The event listener passed to FusionCharts.removeEventListener needs to be a function. Otherwise, the event listener function has no way to know which function is to be removed.

Type:

ParameterException

Error-03091559

The event name passed to FusionCharts.removeEventListener needs to be a string.

Type:

ParameterException

Error-1603111624

FusionCharts JavaScript Library automatically determines the location where it was loaded from within the server. This it does by probing the <script> tag that has fusioncharts.js as a part of its src attribute. In case, this baseUri cannot be determined, this error is raised. Usually, this occurs when

fusioncharts.js has been loaded by a script / resource loader like requireJS or jQuery
fusioncharts.js has been renamed to something else and then loaded
fusioncharts.js is loaded from an external domain and as search browser has enforced cross-domain security restrictions.

Type:

RuntimeException

Error-2105141421

FusionCharts#setChartAttribute was called while chart data was not set or while chart data had an error. Check whether FusionCharts.event:dataLoaded had been successfully fired before FusionCharts.event:renderComplete and that none of the data load error events such as FusionCharts.event:dataLoadError or {@link FusionCharts.event:invalidData} has been fired.

Type:

RuntimeException

Error-25081429

FusionCharts#getChartAttribute accepts only a string or an array of attribute names as its paramater. Check whether your call to the function involved passing some other type of parameter.

Type:

RuntimeException

Error-25081731

FusionCharts#configureLink accepts a configuration object or an array of configuration objects as its parameter. Check whether some other data type has been passed or not.

Type:

ParameterException

Error-25081617

Every instance of FusionCharts has a set of functions that are specific to a chart type and set of functions that are available only after a chart has been rendered. In case a call to such functions are made before the chart has been completely rendered, this error is raised. The error message includes the name of the function in question.

Ensure you programmatically interact with a chart (with respect to the function involved,) after the FusionCharts#event:renderComplete event has been fired.

Type:

RuntimeException

Error-25081850

This is an error that occurs when FusionCharts failed to render the chart. When FusionCharts#render is called, it expects the rendering process to complete and a corresponding chart be available on the browser DOM having the same id as the chart id.

Check whether the chart being rendered has a unique ID.
Ensure that the chart container being rendered in is not within a frame or iframe.
Ensure that the container being rendered in is not deleted or manipulated during the rendering process. Avoid updating the innerHTML of the container once a chart has been rendered within it; use standard DOM append, prepend, insert, remove functions.
Check whether any third-party JavaScript or JavaScript UI library is not interfering with the rendering process.

Type:

RuntimeException

Error-13111126041

This error is raised when the chart cannot internally access the DOM functions of the rendered chart. The likely cause of this issue is an internal failure to enumerate the basic DOM functions that are needed for the chart to render. Ensure that your browser has not enforced cross-domain script security restrictions that was intended.

Type:

RuntimeException

Error-25081843

FusionCharts raises this error to ensure that the charts function reliably on older Internet Explorer browsers (IE 8 and below.) Ensure that you have unique name for your chart id and that it does not correspond to any global variable, DOM element id or frame name.

Type:

CompilationException

Error-03091456

FusionCharts could not find the container DOM element while rendering chart. Ensure that a DOM element exists which has an id attribute same as the one provided in renderAt construction parameter or when passed to the FusionCharts#render function.

Type:

CompilationException

Error-05102109

The id of the container element provided has more than one element with the same id. This would cause problems in referring to the correct chart during its operation.

Ensure that no other DOM element exists on the page with the same id attribute as of the container element where the chart is supposed to be rendered.

Type:

CompilationException

Error-03091611

This error is raised when FusionCharts data setter functions receive a FusionCharts~dataFormats that is not internally registered successfully. It is very less likely that this error will be raised unless the implementation of FusionCharts is done using a non-standard way (e.g. directly chart.options.dataFormat has been changed.)

Type:

ParameterException

Error-25081543

When an invalid data format has been passed to FusionCharts#getChartData or other data- getter functions, this error is raised. Ensure that you are using one of the data formats specified in FusionCharts~dataFormats.

Type:

ParameterException

Error-14090217

This error is encountered when either the source or the target parameter of FusionCharts.transcodeData receives a value that is not part of the list of data formats in FusionCharts~dataFormats. Note that url-prefixed data formats are not intended to be supplied to the transcoder function.

Type:

ParameterException

Error-1113062012

When browser lacks native support for JSON, FusionCharts uses internal JSON parser. This error is raised when even the internal parser fails to initialise. The application or implementation needs to be debugged to identify the cause of this issue.

Type:

RuntimeException

Warning-04031935

FusionCharts can be configured to block loading of external JavaScript files by setting the internal constant BLOCK_EXTERNAL_SCRIPT_LOADING=true;. When this has been done, and some chart still needs external resource (script) that has not been manually loaded, this warning is issued. Ensure that the relevant files, such as, fusioncharts.charts.js, fusioncharts.widgets.js or other such files are already included in page before rendering the chart.

Type:

RuntimeException

Warning-08101320181

Since FusionCharts 3.4.0, the use of .swf suffix in chart types is deprecated since, Flash variant of charts are no longer supported. As such, a warning message is issued to notify developers to follow steps specified in '3.4.0 Migration Guide" to upgrade to the newest API.

Type:

DesignTimeException

Since:

3.4.0

Warning-11133001041

Use of deprecated getChartFromId() or getMapFromId() global objects detected. Developer needs to upgrade to usage of the latest API and access chart instances using FusionCharts.items or FusionCharts("chart-id").

Type:

DesignTimeException

Since:

3.4.0

Warning-14051100501

The reference to the theme name provided as part of the chart data is not registered. Verify whether the corresponding theme file has been included in page.

Type:

RuntimeException

Warning-23091255

This warning is issued when a chart's rendering process and the process of data being fetched from an URL has happened simultaneously. FusionCharts delays the rendering of the chart in anticipation of the arrival of data and in the process reduces redundant re-rendering of the charts.

This warning is for information purpose only and does not require any action.

Type:

RuntimeException

Warning-03091609

When an invalid data format has been passed to FusionCharts#setChartDataUrl or other data- url-setter functions, this warnig is raised. The chart continues to use the last used data format in this situation. Ensure that you are using one of the data url prefixed formats specified in FusionCharts~dataFormats.

Type:

ParameterException

Warning-03091610

When an invalid data format has been passed to FusionCharts#setChartData or other data- setter functions, this warnig is raised. The chart continues to use the last used data format in this situation. Ensure that you are using one of the data formats specified in FusionCharts~dataFormats.

Type:

ParameterException

Warning-1810131922A

FusionCharts supports construction parameters to have dataSource and dataFormat to be provided. As such charts render with the data provided during construction. However, if a chart has been rendered by calling FusionCharts#render, but no data has been provided to the chart, this warning is raised.

Unless this is intentionally implemented, try furnishing the chart with data before .render() is called.

Type:

ParameterException

debuggerCallback(outputFormatParameters)

The parameters passed on to the debugger callback function is in line with the value of FusionCharts.debugger~outputFormats specified via FusionCharts.debugger.outputTo.

Parameters:

Parameter	Description
`outputFormatParameters` Type: * Attributes: <repeatable>	The parameters passed to the callback depend upon the debugger output format set. The details regarding the different variants of parameter is at FusionCharts.debugger~outFormats.

Events

error

FusionCharts framework is designed to be non disruptive in execution. This means that in case of an error, the library would attempt recovery or graceful fallback or not render a chart. It should ideally not raise a JavaScript runtime error unless at places that is intended to raise error or when unexpected runtime errors occur.

For known error causing situations, this error event is raised with an error code and a message guiding to the possible cause of error. In situtations where charts behave unexpectedly, this event can be subscribed to discover possible errors.

Furthermore, these events are forwarded to the FusionCharts.debugger output and when debugger is enabled, any such error event would be visible.

Parameters:

Parameter	Description
`id` Type: string	Reference ID of the error being raised.
`nature` Type: FusionCharts.debugger~errorNatures	Is a cue as to what category of error is this. The value of this param must be same as one from within the FusionCharts.debugger~errorNatures collection.
`source` Type: string	source is a cue as to which object/module caused this error.
`message` Type: string	The content of this argument is generally a human comprehensible message denoting the cause of the error being raised.

warning

Certain implementation setup, browser or combination of the both cause unexpected scenarios during the rendering process of a chart. Whenever such situations are encountered that "may" cause issue but, during the propagation of the event, has been compensated for. FusionCharts keeps the developer in the loop by issuing this warning event.

Parameters:

Parameter	Description
`id` Type: string	Reference ID of the warning being raised.
`nature` Type: FusionCharts.debugger~errorNatures	Is a cue as to what category of warning is this. The value of this param must be same as one from within the FusionCharts.debugger~errorNatures collection.
`source` Type: string	source is a cue as to which object/module caused this error.
`message` Type: string	The content of this argument is generally a human comprehensible cause of the error being raised.