Skip to contents

Introduction to echarty

Source: vignettes/echarty.Rmd
echarty.Rmd

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

For event handling in Shiny see sample code in eshiny.R, run as demo(eshiny).
Echarty has three built-in event callbacks - click, mouseover, mouseout. All other ECharts events could be initialized through p$x$capture. Another option is to use p$x$on with JavaScript handlers, see code in examples.

Widget x parameters

These are htmlwidget and ECharts initialization parameters supported by echarty. There are code samples for most of them in examples:

  • capture = event name(s), to monitor events, usually in Shiny
  • on = define JavaScript code for event handling, see ECharts
  • registerMap = define a map from a geoJSON file, see ECharts
  • group = group-name of a chart, see ECharts
  • connect = command to connect charts with same group-name, see ECharts
  • locale = EN(default) or ZH, set from locale parameter of ec.init, see ECharts.
  • renderer = canvas(default) or svg, set from renderer in ec.init, see ECharts.
  • jcode = custom JavaScript code to execute, set from js parameter of ec.init

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).
ec.upd requires indexes and dimensions to be set with JS-counting.

Javascript built-in functions

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

Code examples

Here is the complete list of sample code locations:

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