About
ApexCharts.RB is a ruby gem that wraps a JavaScript charting library called with the same name,
ApexCharts.JS, that's going to give you
beautiful, interactive, and responsive charts for your ruby app.
Trusted By
Put your organization/company logo and link here
by responding to this issue.
README Versions
This README might not be for the version you use.
Choose the right README:
Table of Contents
- About
- Trusted By
- README Versions
- Table of Contents
- Usage
- Data Formats
- Options
- Installation
- Reusable Custom Palette
- Web Support
- Roadmap
- Contributing
- License
- Like the charts?
Usage
Cartesian Charts
Example series used for cartesian charts:
<% series = [
{name: "Inactive", data: @inactive_properties},
{name: "Active", data: @active_properties}
] %>
To build the data, you can use gem groupdate.
In my case, it was:
@inactive_properties = Property.inactive.group_by_week(:created_at).count
@active_properties = Property.active.group_by_week(:created_at).count
and I'll get the data in this format:
{
Sun, 29 Jul 2018=>1,
Sun, 05 Aug 2018=>6,
..
}
PS: Property can be any model you have and inactive and active
are just some normal ActiveRecord scopes. Keep scrolling down to see
accepted data formats.
Example options used for cartesian charts:
<% options = {
title: 'Properties Growth',
subtitle: 'Grouped Per Week',
xtitle: 'Week',
ytitle: 'Properties',
stacked: true
} %>
Line Chart
<%= line_chart(series, options) %>
Stepline Chart
<%= line_chart(series, {**options, theme: 'palette7', curve: 'stepline'}) %>
Area Chart
<%= area_chart(series, {**options, theme: 'palette5'}) %>
Column Chart
<%= column_chart(series, {**options, theme: 'palette4'}) %>
Bar Chart
<%= bar_chart(series, {**options, xtitle: 'Properties', ytitle: 'Week', height: 800, theme: 'palette7'}) %>
Range Bar Chart
<% range_bar_series = [{
name: "Series A",
data: {
'A' => [1, 5],
'B' => [4, 6],
'C' => [5, 8],
'D' => [3, 11]
}
}, {
name: "Series B",
data: {
'A' => [2, 6],
'B' => [1, 3],
'C' => [7, 8],
'D' => [5, 9]
}
}]
%>
<%= range_bar_chart(range_bar_series, theme: 'palette3') %>
Scatter Chart
<%= scatter_chart(series, {**options, theme: 'palette3'}) %>
Candlestick Chart
Candlestick chart is typically used to illustrate movements in the price of a
financial instrument over time. This chart is also popular by the name "ohlc chart".
That's why you can call it with ohlc_chart too.
So, here's how you make it.
Given:
<%
require 'date'
def ohlc(ary)
[rand(ary.min..ary.max), ary.max, ary.min, rand(ary.min..ary.max)]
end
candlestick_data = 50.times.map do, i, [Date.today - 50 + i, ohlc(Array.new(2){ rand(6570..6650) })]
end.to_h
candlestick_options = {
plot_options: {
candlestick: {
colors: {
upward: '#3C90EB',
downward: '#DF7D46'
}
}
}
}
%>
You can make candlestick chart with this:
<%= candlestick_chart(candlestick_data, candlestick_options) %>
Real life candlestick chart probably don't look like that.
That's because I just use random sets of numbers as the data.
Mixed Charts
You can mix charts by using mixed_charts or combo_charts methods.
For example, given that:
@total_properties = Property.group_by_week(:created_at).count
and
<% total_series = {
name: "Total", data: @total_properties
} %>
you can do this:
<%= combo_charts({**options, theme: 'palette4', stacked: false, data_labels: false}) do %>
<% line_chart(total_series) %>
<% area_chart(series.last) %>
<% column_chart(series.first) %>
<% end %>
Syncing Charts
You can synchronize charts by using syncing_charts or synchronized_charts methods. For
example:
<%= syncing_charts(chart: {toolbar: false}, height: 250, style: 'display: inline-block; width: 32%;') do %>
<% mixed_charts(theme: 'palette4', data_labels: false) do %>
<% line_chart({name: "Total", data: @total_properties}) %>
<% area_chart({name: "Active", data: @active_properties}) %>
<% end %>
<% area_chart({name: "Active", data: @active_properties}, theme: 'palette6') %>
<% line_chart({name: "Inactive", data: @active_properties}, theme: 'palette8') %>
<% end %>
Brush Chart
<%= area_chart(total_series, {
**options, chart_id: 'the-chart', xtitle: nil, theme: 'palette2'
}) %>
<%= mixed_charts(brush_target: 'the-chart', theme: 'palette7') do %>
<% column_chart(series.first) %>
<% line_chart(series.last) %>
<% end %>
Annotations
All cartesian charts can have annotations, for example:
<%= area_chart(series, {**options, theme: 'palette9'}) do %>
<% x_annotation(value: ('2019-01-06'..'2019-02-24'), text: "Busy Time", color: 'green') %>
<% y_annotation(value: 29, text: "Max Properties", color: 'blue') %>
<% point_annotation(value: ['2018-10-07', 24], text: "First Peak", color: 'magenta') %>
<% end %>
Heatmap Chart
<% heatmap_series = 17.downto(10).map do, n, {
name: "#{n}:00",
data: 15.times.map do, i, ["W#{i+1}", rand(90)]
end.to_h
}
end %>
<%= heatmap_chart(heatmap_series) %>
Radar Chart
<% radar_series = [
{
name: "What it should be",
data: { "Code review"=>10, "Issues"=>5, "Pull request"=>25, "Commits"=>60 }
},
{
name: "What it really is",
data: { "Code review"=>1, "Issues"=>3, "Pull request"=>7, "Commits"=>89 }
}
] %>
<%= radar_chart(
radar_series,
{title: "GitHub Radar", markers: {size: 4}, theme: 'palette4'}
) %>
Bubble Chart
<% bubble_series = (1..4).map do, n, {
name: "Bubble#{n}",
data: 20.times.map{[rand(750),rand(10..60),rand(70)]}
}
end %>
<%= bubble_chart(bubble_series, data_labels: false, theme: 'palette6') %>
Polar Charts
Pie Chart
<%= pie_chart([
{name: "Series A", data: 25},
{name: "Series B", data: 100},
{name: "Series C", data: 200},
{name: "Series D", data: 125}
], legend: "left") %>
Donut Chart
<%= donut_chart([25, 100, 200, 125], theme: 'palette4') %>
Radial Bar Chart
Also called circle_chart.
<%= radial_bar_chart([
{name: "Circle A", data: 25},
{name: "Circle B", data: 40},
{name: "Circle C", data: 80},
{name: "Circle D", data: 45}
], legend: true) %>
Data Formats
Cartesian Charts
The data format for line, stepline, area, column, bar, and scatter
charts should be in following format per-series:
{
<x value> => <y value>,
<x value> => <y value>,
...
}
or this:
[
[<x value>, <y value>],
[<x value>, <y value>],
...
]
Candlestick Chart
Candlestick chart is just like other cartesian charts, only the y value is
an array of 4 members which called the OHLC (Open-High-Low-Close):
{
<x value> => [<Open>, <High>, <Low>, <Close>],
<x value> => [<Open>, <High>, <Low>, <Close>],
...
}
or this:
[
[<x value>, [<Open>, <High>, <Low>, <Close>]],
[<x value>, [<Open>, <High>, <Low>, <Close>]],
...
]
Heatmap Chart
The data format for heatmap chart per-series is similar to cartesian
charts. But instead of y values they are heat values. The series names will
be the y values.
{
<x value> => <heat value>,
<x value> => <heat value>,
...
}
or this:
[
[<x value>, <heat value>],
[<x value>, <heat value>],
...
]
Radar Chart
The data format for radar chart per-series is also similar but instead
of x values they are variables and instead of y values they are the only
values for the variables with type of Numeric.
{
<variable> => <value>,
<variable> => <value>,
...
}
or this:
[
[<variable>, <value>],
[<variable>, <value>],
...
]
Bubble Chart
Bubble chart is similar to scatter chart, only they have one more value
for bubble size:
[
[<x value>, <bubble size>, <y value>],
[<x value>, <bubble size>, <y value>],
...
]
Polar Charts
The data format for donut, pie, and radial bar are the simplest. They are
just any single value of type Numeric.
Options
ApexCharts.RB supports all options from apexcharts.js,
but instead of camelCase, you can write them in snake_case.
ApexCharts.RB also provides shortcuts to some ApexCharts.JS options, such as title. In
ApexCharts.JS you would have to write title: { text: "Some title" }. In ApexCharts.RB you
can write title: "Some title" if you just want to add the text. xtitle and ytitle are
even greater shortcuts. Instead of xaxis: { title: { text: "x title" } } you can write
xtitle: "x title"."
options = {
animations: false, # Shortcut for chart: { animations: { enabled: false } }
chart: {
fontFamily: "Helvetica, Arial, sans-serif",
toolbar: {
show: false
}
},
curve: "straight", # Shortcut for stroke: { curve: "straight" }
markers: {
size: 5,
},
tooltip: false, # Shortcut for tooltip: { enabled: false }
xtitle: "Boars per capita"
}
These options can be passed to any chart helper like <%= line_chart(series, options) %>.
Global Options
To change options globally, you can manipulate the Apex JavaScript object directly:
require("apexcharts")
const apexGlobalOptions = {
chart: {
…
},
…
}
Object.assign(Apex, apexGlobalOptions)
All charts will then be created with these global options, which can be overwritten
individually by any ApexCharts.RB helper method.
Formatter Function
To use a simple formatter function (e.g. formatter in tooltip, data_labels, and labels),
you can add functionable-json to your Gemfile and
use it like so:
<%= area_chart series, tooltip: {y: {formatter: function(val) { return '$' + parseFloat(val).toLocaleString() }}} %>
Installation
Add this line to your application's Gemfile:
gem 'groupdate' # optional
gem 'apexcharts'
And then execute:
$ bundle
Reusable Custom Palette
You can create custom palette that works globally or locally.
Global Palette
To create global palettes to be used anywhere on your any parts of your app, you can use
ApexCharts::Theme.create.
For example, in rails app, you would write it in initializers:
# config/initializers/apexcharts.rb
ApexCharts::Theme.create "rainbow", ["#ff0000", "#00ff00", "#0000ff"]
and later somewhere in your app views:
# e.g. app/views/home/index.html.slim
...
= line_chart chart_data, theme: "rainbow"
...
If later for some reason I don't know you want to destroy the palette you can use:
ApexCharts::Theme.destroy "rainbow"
Local Palette
To create local palettes to be used only for current thread (usually for the duration
of a request), you can use the create_palette helper. The theme will only be available
on that page and inside its partials after the palette created.
For example:
create_palette "ephemeral", ["#ab356d", "#12cdf3", "#665572", "#ababac"]
To destroy the palette:
destroy_palette "ephemeral"
on the same page or in its partials. Otherwise, nothing will happen.
Web Support
Rails
Require it in your app/assets/javascripts/application.js.
//= require apexcharts
Or, if you use webpacker, you can run:
$ yarn add apexcharts
and then require it in your app/javascript/packs/application.js.
require("apexcharts")
Sinatra
Require it after you require 'sinatra/base' and add helper Sinatra::ApexCharts in the class that
inherits from Sinatra::Base.
require 'sinatra/base'
require 'apexcharts'
class SimpleApp < Sinatra::Base
helpers Sinatra::ApexCharts
end
To add the asset (ApexCharts.JS), include a script tag in your template
as follows:
template :index do
<<~INDEX
<script src="https://cdn.jsdelivr.net/npm/apexcharts"></script>
<% series = {...} %>
<%= pie_chart(series, legend: "left") %>
INDEX
end
For more details, see example.
Plain HTML+ERB (Without Framework)
Insert this to the top of your .html.erb files:
<script src="https://cdn.jsdelivr.net/npm/apexcharts"></script>
<% require 'apexcharts' %>
<% include ApexCharts::Helper %>
You can then generate the static html page with e.g.
$ erb sample.html.erb > sample.html
Roadmap
- Support other ruby frameworks (hanami, roda, cuba, middleman, etc.)
- v0.1.x
- Add more features (e.g. gradient line, background image, etc.)
- v0.2.x
- Replace dependency
smart_kvwithdry-schema - Display warnings on browser console on development instead of error page when
schema doesn't meet
- Replace dependency
Contributing
Everyone is encouraged to help improve this project by:
- Reporting bugs
- Fixing bugs and submiting pull requests
- Fixing documentation
- Suggesting new features
- Implementing todos on Roadmap above
License
The gem is available as open source under the terms of the
MIT License.
Like the charts?
Consider donating to the author of ApexCharts.JS to support his awesome library.
This project wouldn't be possible without it.