New Froala Editor v4.4 is here – Learn More
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
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>