# Introduction to echarty

## Description

echarty provides a lean interface between R and Javascript library ECharts.
We encourage users to follow the original ECharts API documentation to construct charts with echarty.
Main command ec.init can set multiple native ECharts options to build a chart.
The benefits - learn a very limited set of commands, and enjoy the full functionality of ECharts.

## Package Conventions

pipe-friendly - supports both %>% and |>
commands have three prefixes to help with auto-completion:

- ec. for general functions, like ec.init
- ecs. for Shiny functions, like ecs.output
- ecr. for rendering functions, like ecr.band

## Events

Event handling in Shiny is done through callbacks.
See considerable sample code in eshiny.R, run as `demo(eshiny)`.
There are three built-in event callbacks - click, mouseover, mouseout. All other ECharts events could be initialized through `ec.init(capture=...)`.
For event handling in R (without Shiny) use parameter `ec.init(on=...)` which expects JavaScript handlers. Search for ‘event’ in code examples.

## ECharts initialization parameters

Chart initialization is performed by the echarty::ec.init() command.
Here is full list of ec.init optional parameters:

- ask, js, elementId, ctype, xtKey, dbg are specific to echarty
- theme, iniOpts, on, off, capture, group belong to the ECharts chart instance object.
- connect, disconnect, registerMap, registerTheme, registerLocale, registerCustomSeries are commands of the global ECharts object.

There are R code examples for some of these parameters.

## R vs Javascript numbering

R language counting starts from 1.
Javascript (JS) counting starts from 0.
ec.init supports R-counting of indexes (ex. encode) and dimension (ex. visualMap).
All other contexts like ec.upd or ecs.proxy require JS-counting of indexes and dimensions.

## Javascript built-in functions

To allow access to charts from JS.
ec_chart(id) - get the chart object by id
ec_option(id) - get the chart’s option object by id
Parameter id could be the internal JS variable echwid, or the value set through ec.init parameter elementId. See code examples.

## Column-to-style binding with encode

ECharts series encode enables binding axes and tooltip to data columns. Echarty enhances this method for all series data parameters like itemStyle,labels,emphasis,etc. The bindings are set through `series$encode$data`. For instance
`encode= list(data= list(value= c('xc','yc'), itemStyle= list(opacity= 'oc')))`
would match columns xc,yc,oc to each item’s value and opacity. The result is a new `series$data` added to the series. It permits to finely customize chart elements directly from data.
Echarty has also an alternative tool, style-named columns with `ec.data(..nasep)`, but `encode$data` offers more flexibility. It is not compatible with timeline however.

## Code examples

Here is the complete list of sample code locations:

- website gallery
- collection of code examples
- Shiny code is in eshiny.R, run with `demo(eshiny)`
- demos on RPubs
- searchable gists
- answers to Github issues
- code in Github tests
- command examples, like in ?ec.init

## Global Options

Options are set with R command options. Echarty uses the following options:

- echarty.theme = name of theme file, without extension, from folder `/inst/themes`
- echarty.font = font family name
- echarty.urlTiles = tiles URL template for leaflet maps

    # set/get global options
    options('echarty.theme'='jazz') # set
    getOption('echarty.theme')      # get
    #> [1] "jazz"
    options('echarty.theme'=NULL)   # remove