The Backend

This extension expects to be able to fetch data from a backend server. Communication is established through a GET request to a URL and can also be accompanied by parameters (jQuery.getJSON(url, dataObject)). The signature in the initial options object is quite simple:

var wrap = $('#id').CreateChart({
    url : 'https://mybackendserver.com',
    params : {
        key : 'valuePairs',
        ...
    },
    ...
});

The data is fetched asynchronously and listened to by promises.

Expected Data Format

The extension expects a JSON object with the following signature:

{
    code : 200,
    msg : 'success',
    results : {
        cols : [],
        rows : [[], [], ...]
    }
}

Columns

Column definitions are expected to come in from the backend because it is closer to the data definitions. Each column element has to be parseable by DataTable.prototype.addColumn(descriptionObject) (docs).

Property	Optional	Comment
type	No	One of 'string', 'number', 'boolean', 'date', 'datetime', and 'timeofday'
role	Yes	A role for the column. Please consult the [[docs
label	Yes	A label to be displayed for the column.
id	Yes	An ID for the column.
pattern	Yes	A number (or date) format string specifying how to display the column value.

Example: this example documents itself

cols : [
    {role:'domain',type:'string',label:'Clients'},
    {role:'data',type:'number',label:'Income'}
]

Rows

Rows are expected to come in as arrays of values. The array of rows has to be parseable by DataTable.prototype.addRows(arrayOfRowObjects) (docs). The rowObjects can be simple arrays of values, and all arrays must have the same length.

Example: this easy version shows how simple it is to put values directly into arrays that act as rows

rows : [
    [ 'Company A', 125000 ],
    [ 'Company B', 1200 ],
    [ 'Company C', 3412650 ],
    [ 'Company D', 315084 ]
]

There is a more complex version that exposes more features but it escapes the scope of this document. For more information see the docs to understand cell objects.

Error Handling

There is an error handler that will report on three kinds of exceptions. Once the exception is raised the initialization process is interrupted (a promise fails). A message will inform the user that something has happened.

[for debugging purposes only] some of this must be removed

Cause	Description
BackendHttpErrorException	[to be removed] any HTTP code that is considered an error (500, 404, etc) will throw. The message will display the error code, the error string and the target URL.
BackendParserErrorException	[to be removed] if the data coming in from the server is not well formed JSON, the parser will raise the exception. Any error thrown in PHP will also cause a parser error so this is message is cause for concern on behalf of the backend developer.
BackendTimeoutException	if a timeout for Ajax calls is defined in jQuery (there is none by default), then an exception is raised when the request time runs out.
DataSignatureException	[to be removed] [only for debugging purposes] this will be thrown when the JSON object's signature returned from the backend does not meet the requirements.
DataCodeException	this should be the only exception raised if everything is working correctly in the backend. The server may encounter a problem processing the request so this exception captures any message and code relayed back to the client.