ember-amcharts

Use amCharts 4 in Ember in a declarative way.

Usage no npm install needed!

<script type="module">
  import emberAmcharts from 'https://cdn.skypack.dev/ember-amcharts';
</script>

README

Build Status Ember Observer Score npm version

ember-amcharts

Use amCharts 4 in Ember in a declarative way.

  • Dynamic (lazy) imports
  • Declarative interface using contextual components
  • Close to original amCharts API

Table of contents

Compatibility

  • Ember.js v3.13 or above
  • Ember CLI v2.13 or above
  • Node.js v10 or above

Installation

ember install ember-amcharts

Usage

<AmChart
  @themes={{array (am-chart-theme "material")}}
  @chartType="XYChart"
  @initialConfig={{this.jsonConfig}}
  as |chart|
>
  <chart.property @property="exporting.menu" @value={{am-chart-obj chart.am4core "ExportMenu"}} />

  <chart.push @property="yAxes" @value={{am-chart-obj chart.am4charts "CategoryAxis"}} as |axis|>
    <axis.property @property="title.text" @value="Stuff" />

    <axis.adapter @property="renderer.labels.template" @adapter="text" @func={{this.axisTextFormatter}} />
  </chart.push>

  {{#if this.triggerExport}}
    <chart.call @obj={{this.chart}} @property="exporting.export" @params={{array "png"}} />
  {{/if}}
</AmChart>

Components

AmChart

Creates the amChart.

Properties:

  • chartType: Name of chart type class (e.g. PieChart, XYChart, …)
  • initialConfig: Object containing JSON-based config. This is only used during construction or when the chart type changes, but otherwise updates will have no effect.
  • themes: Optional. List of themes

Yields hash(once the chart loaded):

  • instance: amChart chart instance
  • am4core: am4core module
  • am4charts: am4charts module
  • property: AmChartProperty as contextual component (setting obj)
  • on: AmChartOn as contextual component (setting obj)
  • call: AmChartCall as contextual component (setting obj)
  • push: AmChartPush as contextual component (setting obj)
  • adapter: AmChartAdapter as contextual component (setting obj)

AmChartProperty

Manages property value, e.g.

<AmChartProperty @obj={{this.chart}} @property="responsive.enabled" @value={{true}} />

translates to the following amChart code:

chart.responsive.enabled = true;

When the component is removed from the template it will restore the original state by disposing the given value or setting the original value again.

Properties:

  • obj: Container obj
  • property: Path to property to set
  • value: Value to set

Limitations:

  • While changes to obj, property and value will be correctly applied, only the value at the original combination obj / property is restored upon component destruction.

AmChartOn

Registers action to an event dispatcher.

<AmChartOn
  @obj={{this.series}}
  @property="columns.template"
  @event="hit"
  @action={{fn this.onColumnClick}}
/>

translates to the following amChart code:

series.columns.template.events.on("hit", function(ev) { … })

Properties:

  • obj: Container obj
  • property: Path to property with event dispatcher
  • event: Event name
  • action: Event handler
  • once: Optional. Boolean indicating whether to subscribe to on (default) or to once.

AmChartCall

Calls function. Parameter updates will cause the function to be called again.

<AmChartCall
  @obj={{this.chart}}
  @property="exporting.export"
  @params={{array "png"}}
/>

translates to

chart.exporting.export("png");

Parameters:

  • obj: Container obj
  • func: Path to function
  • params: List of positional parameters

Yields:

  • return value of function call

AmChartPush

Pushes value into list. Tries to dispose its work upon recomputation with changed obj/property params or upon destruction.

Parameters:

  • obj: container obj
  • property: Path to array
  • value: Value to push into array

Yields hash:

  • value: Return value of push (amChart's push returns the value pushed)
  • property: AmChartProperty as contextual component (setting obj)
  • on: AmChartOn as contextual component (setting obj)
  • call: AmChartCall as contextual component (setting obj)
  • push: AmChartPush as contextual component (setting obj)
  • adapter: AmChartAdapter as contextual component (setting obj)

AmChartAdapter

Adds (and removes) adapter functions.

<AmChartAdapter
  @obj={{axis}}
  @property="renderer.labels.template"
  @adapter="text"
  @action={{this.axisTextFormatter}}
/>

translates to

axis.renderer.labels.template.adapter.add("text", function(label, target, key) { … })

Parameters:

  • obj: container obj
  • property: Path to property
  • adapter: adapter name/identifier
  • action: Function to modify the value
  • priority: Priority of the adapter
  • scope: Scope the function will be called in

Helpers

am-chart-theme

Imports (dynamic import) amChart theme for usage in AmChart component. Takes name of theme as single positional parameter.

am-chart-obj

Creates new instance of specified class. Takes positional parameters container, name. Additional positional parameters are applied to constructor.

Locales

To avoid having to bundling every locale a blueprint is provided to aid with dynamic importing of amChart locales:

ember generate am-chart-locale-importer fr_FR de_DE en_US

will generate a helper named am-chart-locale to be used like this:

<chart.property @property="language.locale" @value={{am-chart-locale "de_DE"}} />>

For a list of all all locales bundled with amCharts check here.

Contributing

See the Contributing guide for details.

License

This project is licensed under the MIT License.