1# amCharts Responsive 2 3Version: 1.0.2 4 5 6## Description 7 8Use this plugin to enable "responsive" features for amCharts' JavaScript Charts, 9JavaScript Stock Chart, or JavaScript Maps. 10 11"Responsive" chart or map will modify it's features dynamically (even as you 12resize the container) based on the available area. For example: a full fledged 13line chart with legend guides, labels, titles and other elements will be 14displayed in all its glory if container is big enough. 15 16If the container shrinks (i.e. you resize a browser window or view it on an 17iPad), it starts "compacting" the chart. First the legend is removed. Shrink it 18even further, axis titles are removed and its value labels are moved inside the 19plot area. Going even smaller, bullets, labels gone. All the way to the 20sparkline representation of the chart. 21 22Plugin brings a universal set of pre-defined rules that you can use to instantly 23enable responsiveness. Those are custom-tailored for each chart/map type and 24will probably fit your requirements out-of the-box. All you need to do is to 25enable "responsive" plugin for your chart instance. 26 27You can modify those defaults rules, or make your own list. The plugin allows 28that. (see further down this file for instructions) 29 30 31## Usage 32 331. Include the minified version of file of this plugin. I.e.: 34 35``` 36<script src="amcharts/plugins/responsive/responsive.min.js" type="text/javascript"></script> 37``` 38 39(this needs to go after all the other amCharts includes) 40 412. Add the following setting to your chart configuration: 42 43``` 44AmCharts.makeChart( "chartdiv", { 45 ..., 46 "responsive": { 47 "enabled": true 48 } 49} ); 50``` 51 52Or if you are using non-JSON setup: 53 54``` 55chart.responsive = { 56 "enabled": true 57}; 58``` 59 60That's it. 61 62 63## Advanced use 64 65### Rules 66 67You can modify (or completely overwrite) the default responsive rules used by 68the plugin. 69 70A plugin works by checking chart area dimensions after each resize. (or after 71initial build / mobile device orientation change) It then overrides particular 72settings suitable for these particular dimensions. 73 74Override rules are implemented by defining chart rules, or just "rules" moving 75forward. Each rule has two things: 76 771. Dimension conditions; 782. Overrides. (a set of properties to override for this particular rule) 79 80A rule is an object, for example: 81 82``` 83{ 84 "minWidth": 200, 85 "maxWidth": 400, 86 "maxHeight": 400, 87 "minHeight": 200, 88 "overrides": { 89 "precision": 2, 90 "legend": { 91 "enabled": false 92 }, 93 "valueAxes": { 94 "inside": true 95 } 96 } 97} 98``` 99 100The above rule will be applicable to a chart that is between 200px and 400px in 101width and height. 102 103It is not necessary to add all of the dimensional properties. You just neat at 104least one. 105 106So for example to make the rule apply to all charts with width 400px or lower, 107you would do something like this: 108 109``` 110{ 111 "maxWidth": 400, 112 "overrides": { 113 "precision": 2, 114 "legend": { 115 "enabled": false 116 }, 117 "valueAxes": { 118 "inside": true 119 } 120 } 121} 122``` 123 124Please note that there are several other conditional properties besides the ones 125that deal with chart's dimensions: 126 127* "rotate" (true|false) - set this property if you want to make this rule 128 applicable to rotated serial chart only (i.e. bar chart) 129 130* "legendPosition" ("top|bottom|left|right") - set this property if you want the 131 rule applied only when the chart legend is set to particular position. 132 Please note that this does not check whether the legend is enabled at all. 133 134Now, on to explaining "overrides". It's an object, that contains properties that 135you want to override the chart's initial ones with. 136 137It can be either simple properties, like "fontSize" or "precision", or complext 138types like object, or array. 139 140To override a property of a child object, such as "legend", you would simply go 141with JSON representation of the properties you need to override. I.e.: 142 143``` 144"legend": { 145 "enabled": false 146} 147``` 148 149This will look for a "legend" property in chart object, then change it's 150"enabled" property to false. 151 152### Overriding arrays of objects 153 154Some objects in charts are collected in arrays, i.e. "graphs", "valueAxes", etc. 155 156There are some ways to override their properties as well. 157 158To override properties for ALL objects in the array, you would provide an 159override instruction as an object. I.e.: 160 161``` 162"graphs": { 163 "bullet": "round", 164 "lineThickness": 5 165} 166``` 167 168The above will add a round bullet and set line thickness to all of the graphs on 169the chart. 170 171You can also target individual items in the array. There are two ways to do 172that: 173 174a) Use "id" property; 175b) Apply using the same index. 176 177To individually apply property overrides, you will need to supply override 178instructions as an array: 179 180``` 181"graphs": [ 182 { 183 "id": "g1", 184 "bullet": "round", 185 "lineThickness": 5 186 } 187] 188``` 189 190The above will apply the same properties for the graph with an id of "g1" only. 191It will not touch the rest of the graphs. 192 193Please note that original graph definition in your chart settings needs to have 194the "id" property set so this plugin can target it. 195 196Or you can omit the "id" and just apply overrides in the same order as you have 197them defined. I.e.: 198 199``` 200"graphs": [ 201 { 202 "bullet": "round" 203 }, 204 { 205 "bullet": "square" 206 } 207] 208``` 209 210The above will apply round bullets to the first defined graph, and square 211bullets to the second graph. 212 213### Chaining multiple rules 214 215The cool pat is that you can daisy-chain the override rules, much like in CSS. 216 217The plugin will examine all of the rules if their dimensional conditions match 218current chart condition and will apply their overrides in the same order they 219are defined. 220 221Consider this rule set: 222 223``` 224"responsive": { 225 "enabled": true, 226 "rules": [ 227 // at 400px wide, we hide legend 228 { 229 "maxWidth": 400, 230 "overrides": { 231 "legend": { 232 "enabled" 233 } 234 } 235 }, 236 237 // at 300px or less, we move value axis labels inside plot area 238 // the legend is still hidden because the above rule is still applicable 239 { 240 "maxWidth": 300, 241 "overrides": { 242 "valueAxes": { 243 "inside": true 244 } 245 } 246 }, 247 248 // at 200 px we hide value axis labels altogether 249 { 250 "maxWidth": 200, 251 "overrides": { 252 "valueAxes": { 253 "labelsEnabled": false 254 } 255 } 256 } 257 258 ] 259} 260``` 261 262In case several rules modify the same property, the last one will always "win". 263 264### Combining custom rules with pre-defined ones 265 266The plugin will combine your custom rules with pre-defined ones automatically. 267 268In case you want to go pure and set only your own responsive rules, you can set 269property "addDefaultRules" to false. I.e.: 270 271``` 272"responsive": { 273 "enabled": true, 274 "addDefaultRules": false, 275 "rules": [ 276 { 277 "maxWidth": 400, 278 "overrides": { 279 "legend": { 280 "enabled" 281 } 282 } 283 } 284 ] 285} 286``` 287 288When your custom rules are combined with pre-defined ones, yours are appended at 289the end of the list. This means that your rules will always have the "last 290word". 291 292 293## Requirements 294 295This plugin requires at least 3.13 version of JavaScript Charts, JavaScript 296Stock Chart or JavaScript Maps. 297 298Any older versions will be ignored by this plugin. The charts will function but 299no responsive rules will be applied to them. 300 301 302## Demos 303 304Run the index.html in the subdirectory /examples. It will allow viewing misc 305chart types at various resolutions. 306 307 308## Extending this plugin 309 310You're encouraged to modify, extend and make derivative plugins out of this 311plugin. 312 313You can modify files, included in this archive or, better yet, fork this project 314on GitHub: 315 316https://github.com/amcharts/responsive 317 318We're curious types. Please let us know (contact@amcharts.com) if you do create 319something new out of this plugin. 320 321 322## License 323 324This plugin is licensed under Apache License 2.0. 325 326This basically means you're free to use or modify this plugin, even make your 327own versions or completely different products out of it. 328 329Please see attached file "license.txt" for the complete license or online here: 330 331http://www.apache.org/licenses/LICENSE-2.0 332 333 334## Contact us 335 336* Email:contact@amcharts.com 337* Web: http://www.amcharts.com/ 338* Facebook: https://www.facebook.com/amcharts 339* Twitter: https://twitter.com/amcharts 340 341 342## Changelog 343 344### 1.0.2 345* Fixed a bug where the plugin was causing an error when chart/map container was being hidden 346 347### 1.0.1 348* Fixed bug with overrides being overwritten with chart object in some cases 349* V3.14 compatibility 350 351### 1.0 352* Added support for GANTT chart type (available sin JavaScript Charts V3.14) 353 354### 0.9.2 355* Fixed a custom rules being applied in the wrong order 356 357### 0.9.1 358* Made all examples use minified version of the plugin 359* Introduced removal of grid lines on micro charts 360* Tweaked legend hiding dimensions for pie chart 361 362### 0.9 363* Initial release