Options and Properties

version items static member dataFormats annotations ref (Deprecated) DOMInsertModes FroalaCharts.options Creating a chart object

version

Specifies the framework version of Froala Charts. In the format [major, minor, revision, nature, build]

items static member

The reference to every new instance of Froala Charts is maintained in this object with the chart ID as the key. Upon dispose of the instance, the key is removed from this. One can iterate through all instances of Froala Charts using this object.

A short-hand approach to accessing a single chart by its id is to use FroalaCharts function itself but without the new operator and by passing the chart id as the first parameter.

Example

// Assuming a page has many instances of Froala Charts, but
// none of them are rendered, we are going to iterate through all and
// render them.
for (var item in FroalaCharts.items) {
  FroalaCharts.items[item].render();
}

// Alternate method to access the charts using FroalaCharts function to retrieve the chart from its id.
for (var item in FroalaCharts.items) {
  FroalaCharts(item).render();
}

dataFormats

The list of data formats that can be passed over to setChartData or setChartDataUrl or during creating a new instance of FroalaCharts. The parameters that accept data format should have one of the values from this enumeration:

Value	Description
`json`	This denotes that the data being passed on to the chart or returned by the chart is in standard JSON format. The JSON format can be a string containg JSON data or it can also be a JavaScript object.
`jsonurl`	Specifying the data format as `jsonurl` indicates that the data is not JSON data by itself but rather the data being passed is a URL pointing to a file that contains JSON data.
`csv`	Froala Charts supports data in comma separated value format. However, this is presently supported to retrieve data set in one of the other formats and data cannot be passed on to chart in CSV format.

annotations

Annotations are a set of customisable shapes (squares, circles, texts, images) that can be created and positioned anywhere on charts. Whenever a new Froala Charts object is created, one instance of the class annotations is created. Whenever annotation definitions are added via data, this object is updated with the same.

ref (Deprecated)

Every instance of Froala Charts, when rendered within a container element (provided by the renderAt parameter,) creates a <span> element within which a chart is rendered. As such, the user-provided container element is not polluted by the DOM elements created by a chart.
This property is deprecated. Use getObjectReference instead.

Example

// Iterate on all charts rendered on a page and move them to a common location
var sidebar = document.getElementById('sidebar-html-div'), // assuming that your common container is this
  chart;
for (chart in FroalaCharts.items) {
  chart = FroalaCharts.items[chart];
  chart.ref & amp; & amp;
  sidebar.appendChild(chart.ref.parentNode);
}

DOMInsertModes

When a chart is rendered within a DOM element on a page, the chart by default clears its contents and replaces them with the chart. However, this behavior can be changed by specifying the insertMode of the chart during construction of a chart or while calling render.

FroalaCharts.options

FroalaCharts.options consists of many attributes that can be used to configure advanced options of the FroalaCharts library.

Attributes

defaultTheme

Theme can be applied at global level (of a page) which sets a default theme for all the charts in a particular page.

Type:string

export.useCanvas

Custom fonts from client side export can now be exported using useCanvas option. While exporting in SVG format, do include all the external resources in the page.

Type: string

Default Value: False

preventTrackResize

Froala Charts checks for its parent container resize on a time interval of every 300 milliseconds and if the container size has changed the chart will automatically resize if the chart's height and width are in percentage. Set its value to true to stop this behaviour.

Type: boolean

Default value:'False'

resizeTrackingInterval

Set the time interval for checking parent container's size if preventTrackResize is set to false.

Type: number

Default value: '300'

scriptBaseUri

Can be used to define the path of the source js files. For example, if map definition file has to be kept in different folder than froalacharts.js, the path can be set using this attribute.

Type: string

SVGDefinitionURL

Set to absolute to use absolute URLs for SVG definitions, otherwise URLs are assumed to be relative.

Type: string

Default value: 'relative'

Creating a chart object

Create new instances of charts, gauges and maps using this function.

The preferred way to draw charts using Froala Charts is to pass the chart configurations and data to this constructor and call render() on the returned instance. You can provide all the properties, data and event bindings of charts through the parameters passed to this function.

You can call methods of the FroalaCharts class on the returned instance. For all practical purposes, this is the first step to creating a chart using Froala Charts.

Accessing existing charts using FroalaCharts() constructor:

The FroalaCharts function has a dual behavior - other than creating new charts, it can also be used to access already created charts. This is done by dropping the new operator and passing only the chart id as a parameter. For example, var salesChart = FroalaCharts('sales-chart'); will return the instance of the chart with the id "sales-chart". The previous code snippet is equivalent to var salesChart = FroalaCharts.items['sales-chart'];. Refer to items to know more.

Parameters

While creating a new instance of FroalaCharts, you can pass options object with all configuration parameters for that instance. All configurations passed through this object are referred to as "construction parameters". Through these parameters, you can customize the look and feel of a chart, pass data to the chart, configure its dimensions and bind to events.

Each of this object's properties correspond to a configuration option.

type

Provide the name of the chart type to be rendered. Click here for the complete list of charts in Froala Charts.

This parameter controls what chart will be rendered. The data passed to the chart has to be compatible with the chart type specified here.

Alternatively, you can also call chartType on the chart instance to provide the chart type.

Type: string

id

Type: string

This name is used to refer to the current instance after the chart has been created. The chart instance is available under this name in items. If no id is provided, Froala Charts automatically generates an id for each chart.

width

Set the width in pixels or percent such as 640 or '50%'. If width is in pixels, there is no need to provide the px unit suffix. You can call resizeTo function on the chart instance to set the width later on.

Type: numeric or percent

Default value: "400"

width: '400'

height

Set the height in pixels or percent such as 640 or '50%'. If height is in pixels, there is no need to provide the px unit suffix. You can call resizeTo function on the chart instance to set the height later on.

Type: numeric or percent

Default value: "300"

renderAt

A chart needs reference to a DOM element on the page where it will be rendered. You can provide the HTML ID of the element as a string to this option, or you can pass a reference of the DOMElement itself where the chart needs to be rendered.

For example, if you have a DOMElement like <div class='chart-1' id='chart-container'></div>, you can provide the value of the div's id attribute to this option as a string. Alternatively, you can pass direct reference to the DOMElement like: renderAt: document.getElementByClassName("chart-1").

Instead of providing the DOMElement here, it can also be passed as the first parameter to the render function. Setting the DOMElement in render function overrides the value set here.

Type: string or DOMElement

dataFormat

This is the name of the format of data passed to the dataSource option below. Currently, FroalaCharts accepts only JSON and XML data. The value for this option is one of the formats specified in dataFormats.

Type: Froala

dataSource

Type: string or object

Provide the source of data and configuration of the chart. FroalaCharts accepts data in the formats specified in dataFormats.

This is the preferred way to set data and configuration of the chart. The data and configuration can also be updated or set using the functions setChartData and setChartDataUrl.

events

You can bind multiple events to this particular chart instance through this option. You need to pass an object to this option, where each key is an event name fired by FroalaCharts and value for that key is a callback in the format of eventListener.

To bind multiple charts to the same event, you need to use addEventListener function instead.

Type: object

link

Provide LinkedCharts configuration. See configureLink for details.

Type: object

showDataLoadingMessage

Froala Charts shows a message while it is retrieving data from a url provided as dataSource. While displaying the message the chart is grayed out and interaction on it is blocked. This can be prevented by setting this option to false.

Type: boolean

Default value: false

showChartLoadingMessage

Shows Loading chart... message in renderAt container if the chart needs to load additional resource/JS files. This can be turned off by setting this option to false.

Type: boolean

Default value: true

baseChartMessageFont

Allows to set the common custom font face for all chart messages.

Type: string

Default value: 'Verdana'

baseChartMessageFontSize

Allows to set the common custom font size for all chart messages.

Type: string

Default value: '10'

baseChartMessageColor

Allows to set the common custom font color for all chart messages.

Type: hexcolor

Default value: '#666666'

dataLoadStartMessage

Allows to set the message to be displayed before the chart data begins loading. Additional properties like the font face, size, and color can be set by suffixing the property name with the corresponding message key, e.g. dataLoadStartMessageFont, dataLoadStartMessageFontSize, dataLoadStartMessageColor. If message keys are not specified, base cosmetics are used.

Now using a prefix 'i-', an image URL can be specified and the corresponding image will be displayed in place of the message. Alignment and properties of the image can be configured using attributes such as dataLoadStartMessageHAlign, dataLoadStartMessageVAlign, dataLoadStartMessageAlpha and so on.

Type: string

Default value: 'Retrieving data. Please wait.'

dataLoadErrorMessage

Allows to set the message to be displayed when there is an error loading the chart data. Additional properties like the font face, size, and color can be set by suffixing the property name with the corresponding message key, e.g. dataLoadErrorMessageFont, dataLoadErrorMessageFontSize, dataLoadErrorMessageColor. If message keys are not specified, base cosmetics are used.

Now using a prefix 'i-', an image URL can be specified and the corresponding image will be displayed in place of the message. Alignment and properties of the image can be configured using attributes such as dataLoadErrorMessageHAlign, dataLoadErrorMessageVAlign, dataLoadErrorMessageAlpha and so on.

Type: string

Default value: 'Error in loading data.'

dataInvalidMessage

Allows to set the message to be displayed when the data loaded for the chart is invalid. Additional properties like the font face, size, and color can be set by suffixing the property name with the corresponding message key, e.g. dataInvalidMessageFont, dataInvalidMessageFontSize, dataInvalidMessageColor. If message keys are not specified, base cosmetics are used.

Now using a prefix 'i-', an image URL can be specified and the corresponding image will be displayed in place of the message. Alignment and properties of the image can be configured using attributes such as dataInvalidMessageHAlign, dataInvalidMessageVAlign, dataInvalidMessageAlpha and so on.

Default value: string

Default value: 'Invalid data.'

dataEmptyMessage

Allows to set the message to be displayed if data loaded for the chart is empty. Additional properties like the font face, size, and color can be set by suffixing the property name with the corresponding message key, e.g. dataEmptyMessageFont, dataEmptyMessageFontSize, dataEmptyMessageColor. If message keys are not specified, base cosmetics are used.

Now using a prefix 'i-', an image URL can be specified and the corresponding image will be displayed in place of the message. Alignment and properties of the image can be configured using attributes such as dataEmptyMessageHAlign, dataEmptyMessageVAlign, dataEmptyMessageAlpha and so on.

Type: string

Default value: 'No data to display.'

typeNotSupportedMessage

Allows to set the message to be displayed if specified chart type is not supported. Additional properties like the font face, size, and color can be set by suffixing the property name with the corresponding message key, e.g. typeNotSupportedMessageFont, typeNotSupportedMessageFontSize, typeNotSupportedMessageColor. If message keys are not specified, base cosmetics are used.

Now using a prefix 'i-', an image URL can be specified and the corresponding image will be displayed in place of the message. Alignment and properties of the image can be configured using attributes such as typeNotSupportedMessageHAlign, typeNotSupportedMessageVAlign, typeNotSupportedMessageAlpha and so on.

string

Default value: 'Chart type not supported.'

loadMessage

Allows to set the message to be displayed when the chart begins to load. Additional properties like the font face, size, and color can be set by suffixing the property name with the corresponding message key, e.g. loadStartMessageFont, loadStartMessageFontSize, loadStartMessageColor. If message keys are not specified, base cosmetics are used.

Now using a prefix 'i-', an image URL can be specified and the corresponding image will be displayed in place of the message. Alignment and properties of the image can be configured using attributes such as loadMessageHAlign, loadMessageVAlign, loadMessageAlpha and so on.

Type: string

Default value: 'Loading chart. Please wait.'

renderErrorMessage

Allows to set the message to be displayed if there was an error while rendering the chart. Additional properties like the font face, size, and color can be set by suffixing the property name with the corresponding message key, e.g. renderErrorMessageFont, renderErrorMessageFontSize, renderErrorMessageColor. If message keys are not specified, base cosmetics are used.

Now using a prefix 'i-', an image URL can be specified and the corresponding image will be displayed in place of the message. Alignment and properties of the image can be configured using attributes such as renderErrorMessageHAlign, renderErrorMessageVAlign, renderErrorMessageAlpha and so on.

Type: string

Default value: 'Unable to render chart.'

containerBackgroundColor

Sets the background color of the chart's container HTML DOM element. It is not same as bgColor chart attribute. To see this background color, a chart's own background alpha must be set to 0 by setting bgAlpha attribute to "0" in chart attributes.

Type: hexcolor

Default value: "#ffffff"

containerBackgroundOpacity

Sets the opacity of the container element. Useful if the chart has underlying HTML elements or background image that needs to be made visible. If opacity is reduced, you need to configure the chart itself to be transparent by setting the bgAlpha chart attribute.

opacity

Default value: 1

containerClassName

Sets the CSS class that will be set on the container DOM element of the rendered chart. Default is froalacharts-container.

Type: string

baseChartMessageImageHAlign

Allows to set the horizontal alignment for all chart message images, helps to horizontally align the image in the canvas. Possible values are left, right and middle.

Type: string

Default value: 'middle'

baseChartMessageImageVAlign

Allows to set the vertical alignment for all chart message images, helps to vertically align the image in the canvas. Possible values are top, bottom and middle.

Type: string

Default value: 'middle'

baseChartMessageImageAlpha

Allows to set the common alpha value for all chart message images, helps to set the opacity of the image. Value can range from 0 to 100.

Type: number

Default value: '100'

baseChartMessageImageScale

Allows to set the common scaling for all chart message images, helps to magnify the image. Value can range from 0 to 300.

Type: number

Default value: '100'

typeNotSupportedMessageImageHAlign

Allows to set the horizontal alignment for image in type not supported chart message, helps to horizontally align the image in the canvas. Possible values are left, right and middle.

Type: string

Default value: baseChartMessageImageHAlign

typeNotSupportedMessageImageVAlign

Allows to set the vertical alignment for image in type not supported chart message, helps to vertically align the image in the canvas. Possible values are top, bottom and middle.

Type: string

Default value: baseChartMessageImageVAlign

typeNotSupportedMessageImageAlpha

Allows to set the alpha value for image in type not supported chart message, helps to set the opacity of the image. Value can range from 0 to 100.

Type: number

Default value: baseChartMessageImageAlpha

typeNotSupportedMessageImageScale

Allows to set the scaling for image in type not supported chart message, helps to magnify the image. Value can range from 0 to 300.

Type: number

Default value: baseChartMessageImageScale

dataLoadErrorMessageImageHAlign

Allows to set the horizontal alignment for image in data load error chart message, helps to horizontally align the image in the canvas. Possible values are left, right and middle.

Type: string

Default value: baseChartMessageImageHAlign

dataLoadErrorMessageImageVAlign

Allows to set the vertical alignment for image in data load error chart message, helps to vertically align the image in the canvas. Possible values are top, bottom and middle.

Type: string

Default value: baseChartMessageImageVAlign

dataLoadErrorMessageImageAlpha

Allows to set the alpha value for image in data load error chart message, helps to set the opacity of the image. Value can range from 0 to 100.

Type: number

Default value: baseChartMessageImageAlpha

dataLoadErrorMessageImageScale

Allows to set the scaling for image in data load error chart message, helps to magnify the image. Value can range from 0 to 300.

Type: number

Default value: baseChartMessageImageScale

dataLoadStartMessageImageHAlign

Allows to set the horizontal alignment for image in data load start chart message, helps to horizontally align the image in the canvas. Possible values are left, right and middle.

Type: string

Default value: baseChartMessageImageHAlign

dataLoadStartMessageImageVAlign

Allows to set the vertical alignment for image in data load start chart message, helps to vertically align the image in the canvas. Possible values are top, bottom and middle.

Type: string

Default value: baseChartMessageImageVAlign

dataLoadStartMessageImageAlpha

Allows to set the alpha value for image in data load start chart message, helps to set the opacity of the image. Value can range from 0 to 100.

Type: number

Default value: baseChartMessageImageAlpha

dataLoadStartMessageImageScale

Allows to set the scaling for image in data load start chart message, helps to magnify the image. Value can range from 0 to 300.

Type: number

Default value: baseChartMessageImageScale

dataInvalidMessageImageHAlign

Allows to set the horizontal alignment for image in data invalid chart message, helps to horizontally align the image in the canvas. Possible values are left, right and middle.

Type: string

Default value: baseChartMessageImageHAlign

dataInvalidMessageImageVAlign

Allows to set the vertical alignment for image in data invalid chart message, helps to vertically align the image in the canvas. Possible values are top, bottom and middle.

Type: string

Default value: baseChartMessageImageVAlign

dataInvalidMessageImageAlpha

Allows to set the alpha value for image in data invalid chart message, helps to set the opacity of the image. Value can range from 0 to 100.

Type: number

Default value: baseChartMessageImageAlpha

dataInvalidMessageImageScale

Allows to set the scaling for image in data invalid chart message, helps to magnify the image. Value can range from 0 to 300.

Type: number

Default value: baseChartMessageImageScale

dataEmptyMessageImageHAlign

Allows to set the horizontal alignment for image in data empty chart message, helps to horizontally align the image in the canvas. Possible values are left, right and middle.

Type: string

Default value: baseChartMessageImageHAlign

dataEmptyMessageImageVAlign

Allows to set the vertical alignment for image in data empty chart message, helps to vertically align the image in the canvas. Possible values are top, bottom and middle.

Type: string

Default value: baseChartMessageImageVAlign

dataEmptyMessageImageAlpha

Allows to set the alpha value for image in data empty chart message, helps to set the opacity of the image. Value can range from 0 to 100.

Type: number

Default value: baseChartMessageImageAlpha

dataEmptyMessageImageScale

Allows to set the scaling for image in data empty chart message, helps to magnify the image. Value can range from 0 to 300.

Type: number

Default value: baseChartMessageImageScale

renderErrorMessageImageHAlign

Allows to set the horizontal alignment for image in render error chart message, helps to horizontally align the image in the canvas. Possible values are left, right and middle.

Type: string

Default value: baseChartMessageImageHAlign

renderErrorMessageImageVAlign

Allows to set the vertical alignment for image in render error chart message, helps to vertically align the image in the canvas. Possible values are top, bottom and middle.

Type: string

Default value: baseChartMessageImageVAlign

renderErrorMessageImageAlpha

Allows to set the alpha value for image in render error chart message, helps to set the opacity of the image. Value can range from 0 to 100.

Type: number

Default value: baseChartMessageImageAlpha

renderErrorMessageImageScale

Allows to set the scaling for image in render error chart message, helps to magnify the image. Value can range from 0 to 300.

Type: number

Default value: baseChartMessageImageScale

loadMessageImageHAlign

Allows to set the horizontal alignment for image in load chart message, helps to horizontally align the image in the canvas. Possible values are left, right and middle.

Type: string

Default value: baseChartMessageImageHAlign

loadMessageImageVAlign

Allows to set the vertical alignment for image in load chart message, helps to vertically align the image in the canvas. Possible values are top, bottom and middle.

Type: string

Default value: baseChartMessageImageVAlign

loadMessageImageAlpha

Allows to set the alpha value for image in load chart message, helps to set the opacity of the image. Value can range from 0 to 100.

Type: number

Default value: baseChartMessageImageAlpha

loadMessageImageScale

Allows to set the scaling for image in load chart message, helps to magnify the image. Value can range from 0 to 300.

Type: number

Default value: baseChartMessageImageScale

Example

<html>
<head>
<script type="text/javascript" src="js/froalacharts.js"></script>
<script type="text/javascript">
FroalaCharts.ready(function () {
    // Create a new instance of FroalaCharts for rendering inside an HTML
    // `<div>` element with id `my-chart-container`.
    var myChart = new FroalaCharts({
        type: 'pie',
        renderAt: 'chart-container',

        dataFormat: 'json',
        dataSource: {
            chart: {
                caption: "Harry's SuperMart",
                subCaption: "Top 5 stores in last month by revenue",
            },
            data:[{
                label: "Bakersfield Central",
                value: "880000"
            },
            {
                label: "Garden Groove harbour",
                value: "730000"
            },
            {
                label: "Los Angeles Topanga",
                value: "590000"
            },
            {
                label: "Compton-Rancho Dom",
                value: "520000"
            },
            {
                label: "Daly City Serramonte",
                value: "330000"
            }]
        }
    });

    // Render the chart.
    myChart.render();
});
</script>
<body>
    <div id="chart-container">Froala Charts will load here...</div>
</body>
</html>