372 lines
No EOL
8.9 KiB
Markdown
372 lines
No EOL
8.9 KiB
Markdown
# amCharts Responsive
|
|
|
|
Version: 1.0.5
|
|
|
|
|
|
## Description
|
|
|
|
Use this plugin to enable "responsive" features for amCharts' JavaScript Charts,
|
|
JavaScript Stock Chart, or JavaScript Maps.
|
|
|
|
"Responsive" chart or map will modify it's features dynamically (even as you
|
|
resize the container) based on the available area. For example: a full fledged
|
|
line chart with legend guides, labels, titles and other elements will be
|
|
displayed in all its glory if container is big enough.
|
|
|
|
If the container shrinks (i.e. you resize a browser window or view it on an
|
|
iPad), it starts "compacting" the chart. First the legend is removed. Shrink it
|
|
even further, axis titles are removed and its value labels are moved inside the
|
|
plot area. Going even smaller, bullets, labels gone. All the way to the
|
|
sparkline representation of the chart.
|
|
|
|
Plugin brings a universal set of pre-defined rules that you can use to instantly
|
|
enable responsiveness. Those are custom-tailored for each chart/map type and
|
|
will probably fit your requirements out-of the-box. All you need to do is to
|
|
enable "responsive" plugin for your chart instance.
|
|
|
|
You can modify those defaults rules, or make your own list. The plugin allows
|
|
that. (see further down this file for instructions)
|
|
|
|
|
|
## Usage
|
|
|
|
1. Include the minified version of file of this plugin. I.e.:
|
|
|
|
```
|
|
<script src="amcharts/plugins/responsive/responsive.min.js" type="text/javascript"></script>
|
|
```
|
|
|
|
(this needs to go after all the other amCharts includes)
|
|
|
|
2. Add the following setting to your chart configuration:
|
|
|
|
```
|
|
AmCharts.makeChart( "chartdiv", {
|
|
...,
|
|
"responsive": {
|
|
"enabled": true
|
|
}
|
|
} );
|
|
```
|
|
|
|
Or if you are using non-JSON setup:
|
|
|
|
```
|
|
chart.responsive = {
|
|
"enabled": true
|
|
};
|
|
```
|
|
|
|
That's it.
|
|
|
|
|
|
## Advanced use
|
|
|
|
### Rules
|
|
|
|
You can modify (or completely overwrite) the default responsive rules used by
|
|
the plugin.
|
|
|
|
A plugin works by checking chart area dimensions after each resize. (or after
|
|
initial build / mobile device orientation change) It then overrides particular
|
|
settings suitable for these particular dimensions.
|
|
|
|
Override rules are implemented by defining chart rules, or just "rules" moving
|
|
forward. Each rule has two things:
|
|
|
|
1. Dimension conditions;
|
|
2. Overrides. (a set of properties to override for this particular rule)
|
|
|
|
A rule is an object, for example:
|
|
|
|
```
|
|
{
|
|
"minWidth": 200,
|
|
"maxWidth": 400,
|
|
"maxHeight": 400,
|
|
"minHeight": 200,
|
|
"overrides": {
|
|
"precision": 2,
|
|
"legend": {
|
|
"enabled": false
|
|
},
|
|
"valueAxes": {
|
|
"inside": true
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
The above rule will be applicable to a chart that is between 200px and 400px in
|
|
width and height.
|
|
|
|
It is not necessary to add all of the dimensional properties. You just neat at
|
|
least one.
|
|
|
|
So for example to make the rule apply to all charts with width 400px or lower,
|
|
you would do something like this:
|
|
|
|
```
|
|
{
|
|
"maxWidth": 400,
|
|
"overrides": {
|
|
"precision": 2,
|
|
"legend": {
|
|
"enabled": false
|
|
},
|
|
"valueAxes": {
|
|
"inside": true
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
Please note that there are several other conditional properties besides the ones
|
|
that deal with chart's dimensions:
|
|
|
|
* "rotate" (true|false) - set this property if you want to make this rule
|
|
applicable to rotated serial chart only (i.e. bar chart)
|
|
|
|
* "legendPosition" ("top|bottom|left|right") - set this property if you want the
|
|
rule applied only when the chart legend is set to particular position.
|
|
Please note that this does not check whether the legend is enabled at all.
|
|
|
|
Now, on to explaining "overrides". It's an object, that contains properties that
|
|
you want to override the chart's initial ones with.
|
|
|
|
It can be either simple properties, like "fontSize" or "precision", or complext
|
|
types like object, or array.
|
|
|
|
To override a property of a child object, such as "legend", you would simply go
|
|
with JSON representation of the properties you need to override. I.e.:
|
|
|
|
```
|
|
"legend": {
|
|
"enabled": false
|
|
}
|
|
```
|
|
|
|
This will look for a "legend" property in chart object, then change it's
|
|
"enabled" property to false.
|
|
|
|
### Overriding arrays of objects
|
|
|
|
Some objects in charts are collected in arrays, i.e. "graphs", "valueAxes", etc.
|
|
|
|
There are some ways to override their properties as well.
|
|
|
|
To override properties for ALL objects in the array, you would provide an
|
|
override instruction as an object. I.e.:
|
|
|
|
```
|
|
"graphs": {
|
|
"bullet": "round",
|
|
"lineThickness": 5
|
|
}
|
|
```
|
|
|
|
The above will add a round bullet and set line thickness to all of the graphs on
|
|
the chart.
|
|
|
|
You can also target individual items in the array. There are two ways to do
|
|
that:
|
|
|
|
a) Use "id" property;
|
|
b) Apply using the same index.
|
|
|
|
To individually apply property overrides, you will need to supply override
|
|
instructions as an array:
|
|
|
|
```
|
|
"graphs": [
|
|
{
|
|
"id": "g1",
|
|
"bullet": "round",
|
|
"lineThickness": 5
|
|
}
|
|
]
|
|
```
|
|
|
|
The above will apply the same properties for the graph with an id of "g1" only.
|
|
It will not touch the rest of the graphs.
|
|
|
|
Please note that original graph definition in your chart settings needs to have
|
|
the "id" property set so this plugin can target it.
|
|
|
|
Or you can omit the "id" and just apply overrides in the same order as you have
|
|
them defined. I.e.:
|
|
|
|
```
|
|
"graphs": [
|
|
{
|
|
"bullet": "round"
|
|
},
|
|
{
|
|
"bullet": "square"
|
|
}
|
|
]
|
|
```
|
|
|
|
The above will apply round bullets to the first defined graph, and square
|
|
bullets to the second graph.
|
|
|
|
### Chaining multiple rules
|
|
|
|
The cool pat is that you can daisy-chain the override rules, much like in CSS.
|
|
|
|
The plugin will examine all of the rules if their dimensional conditions match
|
|
current chart condition and will apply their overrides in the same order they
|
|
are defined.
|
|
|
|
Consider this rule set:
|
|
|
|
```
|
|
"responsive": {
|
|
"enabled": true,
|
|
"rules": [
|
|
// at 400px wide, we hide legend
|
|
{
|
|
"maxWidth": 400,
|
|
"overrides": {
|
|
"legend": {
|
|
"enabled"
|
|
}
|
|
}
|
|
},
|
|
|
|
// at 300px or less, we move value axis labels inside plot area
|
|
// the legend is still hidden because the above rule is still applicable
|
|
{
|
|
"maxWidth": 300,
|
|
"overrides": {
|
|
"valueAxes": {
|
|
"inside": true
|
|
}
|
|
}
|
|
},
|
|
|
|
// at 200 px we hide value axis labels altogether
|
|
{
|
|
"maxWidth": 200,
|
|
"overrides": {
|
|
"valueAxes": {
|
|
"labelsEnabled": false
|
|
}
|
|
}
|
|
}
|
|
|
|
]
|
|
}
|
|
```
|
|
|
|
In case several rules modify the same property, the last one will always "win".
|
|
|
|
### Combining custom rules with pre-defined ones
|
|
|
|
The plugin will combine your custom rules with pre-defined ones automatically.
|
|
|
|
In case you want to go pure and set only your own responsive rules, you can set
|
|
property "addDefaultRules" to false. I.e.:
|
|
|
|
```
|
|
"responsive": {
|
|
"enabled": true,
|
|
"addDefaultRules": false,
|
|
"rules": [
|
|
{
|
|
"maxWidth": 400,
|
|
"overrides": {
|
|
"legend": {
|
|
"enabled"
|
|
}
|
|
}
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
When your custom rules are combined with pre-defined ones, yours are appended at
|
|
the end of the list. This means that your rules will always have the "last
|
|
word".
|
|
|
|
|
|
## Requirements
|
|
|
|
This plugin requires at least 3.13 version of JavaScript Charts, JavaScript
|
|
Stock Chart or JavaScript Maps.
|
|
|
|
Any older versions will be ignored by this plugin. The charts will function but
|
|
no responsive rules will be applied to them.
|
|
|
|
|
|
## Demos
|
|
|
|
Run the index.html in the subdirectory /examples. It will allow viewing misc
|
|
chart types at various resolutions.
|
|
|
|
|
|
## Extending this plugin
|
|
|
|
You're encouraged to modify, extend and make derivative plugins out of this
|
|
plugin.
|
|
|
|
You can modify files, included in this archive or, better yet, fork this project
|
|
on GitHub:
|
|
|
|
https://github.com/amcharts/responsive
|
|
|
|
We're curious types. Please let us know (contact@amcharts.com) if you do create
|
|
something new out of this plugin.
|
|
|
|
|
|
## License
|
|
|
|
This plugin is licensed under Apache License 2.0.
|
|
|
|
This basically means you're free to use or modify this plugin, even make your
|
|
own versions or completely different products out of it.
|
|
|
|
Please see attached file "license.txt" for the complete license or online here:
|
|
|
|
http://www.apache.org/licenses/LICENSE-2.0
|
|
|
|
|
|
## Contact us
|
|
|
|
* Email:contact@amcharts.com
|
|
* Web: http://www.amcharts.com/
|
|
* Facebook: https://www.facebook.com/amcharts
|
|
* Twitter: https://twitter.com/amcharts
|
|
|
|
|
|
## Changelog
|
|
|
|
### 1.0.5
|
|
* Fixed an issue where Responsive plugin was disabling initial animations.
|
|
|
|
### 1.0.4
|
|
* Fixed errors when legend was `null` (thanks Hasan Akgün)
|
|
|
|
### 1.0.3
|
|
* Fixed issue with Stock Chart when Period Selector and Data Set Selector were turned off
|
|
|
|
### 1.0.2
|
|
* Fixed a bug where the plugin was causing an error when chart/map container was being hidden
|
|
|
|
### 1.0.1
|
|
* Fixed bug with overrides being overwritten with chart object in some cases
|
|
* V3.14 compatibility
|
|
|
|
### 1.0
|
|
* Added support for GANTT chart type (available sin JavaScript Charts V3.14)
|
|
|
|
### 0.9.2
|
|
* Fixed a custom rules being applied in the wrong order
|
|
|
|
### 0.9.1
|
|
* Made all examples use minified version of the plugin
|
|
* Introduced removal of grid lines on micro charts
|
|
* Tweaked legend hiding dimensions for pie chart
|
|
|
|
### 0.9
|
|
* Initial release |