apexcharts 0.1.5 → 0.1.10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 430b940ba031ce379c1d35a6685ba8ad19d62922c91d9d8a806779f1c4282bbd
-  data.tar.gz: 5d1bae083b7c949b1d0a984bcb43e64096558cdcf550df3b8a507eec58e64405
+  metadata.gz: 7da6c272c62c024c2e24180a80a69760efa4ba6703dd1fae81dc7119a2115ac1
+  data.tar.gz: 50bbebd360a73a13ebf328de39acef58d6c59270c136e58563eaa6f1a0764db8
 SHA512:
-  metadata.gz: fc51493d941efd81893b7a847e7939149897b0c8c44f87a04a4d00f5466d5c629862353aad59e7a3df0bcab768926e674bb2f3a00b1b2adf6f987b324a540002
-  data.tar.gz: 272c361ad29c2b5456d62b7339809cbd1e664de015275eecd043127211627732b9ce50df5f68df2b5ce8d11a316fc208037f7a8bd4ac4383aaedd25712449bec
+  metadata.gz: de01a99814d9234441f6b4964239e9882f7676dd3749df05ffc995669a9bb74d4c29a57c4c839b37f9d2c675d0f8e72b8ad26f8d0f95d130a401777258c50f65
+  data.tar.gz: b57b96bc2bdcedadc007a093c7253a8ddb63d74dddbb58eb678e006e881a34d53ce26d1b623c7b25529845726832fd491c644b13ff3cf7a79794e8f5336f0834

data/README.md

@@ -1,19 +1,127 @@
 <p align="center">
-  <img src="images/apexcharts.rb.png" height="170">
+  <img src="images/apexcharts.rb.png" height="150" />
 </p>
 
 <p align="center">
-  <a href="https://github.com/styd/apexcharts.rb/blob/master/LICENSE"><img src="https://img.shields.io/badge/License-MIT-brightgreen.svg" alt="License"></a>
-  <a href="https://travis-ci.org/styd/apexcharts.rb"><img src="https://travis-ci.org/styd/apexcharts.rb.svg?branch=master" alt="Build Status" /></a>
-  <a href="https://rubygems.org/gems/apexcharts"><img src="https://badge.fury.io/rb/apexcharts.svg" alt="Gem Version" /></a>
+  <a href="https://rubygems.org/gems/apexcharts">
+    <img src="https://img.shields.io/gem/v/apexcharts.svg?label=apexcharts" alt="Gem Version" />
+  </a>
+  <a href="https://github.com/styd/apexcharts.rb/actions">
+    <img src="https://github.com/styd/apexcharts.rb/workflows/build-test/badge.svg?branch=master" alt="Build Test Status" />
+  </a>
+  <a href="https://rubygems.org/gems/apexcharts">
+    <img alt="Downloads" src="https://img.shields.io/gem/dt/apexcharts">
+  </a>
+  <img src="https://img.shields.io/github/commit-activity/m/styd/apexcharts.rb.svg?label=commits" alt="Commits" />
+  <a href="https://github.com/styd/apexcharts.rb/blob/master/LICENSE">
+    <img src="https://img.shields.io/badge/License-MIT-brightgreen.svg" alt="License">
+  </a>
+  <a href="https://codeclimate.com/github/styd/apexcharts.rb/maintainability">
+    <img src="https://api.codeclimate.com/v1/badges/07a4f59e67abfeae21cb/maintainability" />
+  </a>
+  <a href="https://codebeat.co/projects/github-com-styd-apexcharts-rb-master">
+    <img alt="codebeat badge" src="https://codebeat.co/badges/7be581d6-e74a-406b-ae76-65605a2bff78" />
+  </a>
+  <a href='https://coveralls.io/github/styd/apexcharts.rb?branch=master'>
+    <img src='https://coveralls.io/repos/github/styd/apexcharts.rb/badge.svg?branch=master' alt='Coverage Status' />
+  </a>
+  <a href='http://clayallsopp.github.io/readme-score/?url=styd/apexcharts.rb'>
+    <img src='http://readme-score-api.herokuapp.com/score.svg?url=styd/apexcharts.rb' alt='README Score' />
+  </a>
 </p>
 
 
-## What is this?
-
-ApexCharts.rb is a ruby gem that wraps a JavaScript charting library called with the same name,
-[apexcharts.js](https://github.com/apexcharts/apexcharts.js), that's going to give you
-a beautiful, interactive, and responsive charts for your ruby app.
+## About 
+
+> ApexCharts.RB is a ruby charting library that's going to give your ruby app beautiful,
+> interactive, and responsive charts powered by [ApexCharts.JS]. On top of those sweet
+> advantages, you'll also get extra features that you can't get by just including ApexCharts.JS
+> to your ruby app, namely **view/template helpers for creating charts**, **options shortcuts**,
+> **application wide default options**, **reusable custom theme palette**, and so on.
+
+
+## Trusted By
+
+Organization/Company                                                   | Use Case
+-----------------------------------------------------------------------|------------------------------------------------------------------
+<img src="/images/users/copient-health.png" width="143" height="40" /> | Reports/charts related to Operating Room utilization statistics
+<img src="/images/users/bilendo.png" width="202" height="40" />        | Enterprise dashboards to visualize account receivables data
+<img src="/images/users/ventrata.png" width="180" height="40" />       | Ticket sales for clients (visitor attractions and tour operators)
+
+> If your organization/company uses ApexCharts.RB in production, please comment on
+> [this issue](https://github.com/styd/apexcharts.rb/issues/34).
+
+
+## Supported By
+
+<a href="https://www.jetbrains.com/?from=ApexCharts.RB">
+  <img src="images/supporters/jetbrains.svg" title="Grants 1 License for All Products Pack" width="120" height="120" />
+</a>
+
+
+## README Versions
+
+This README might not be for the version you use.  
+Choose the right README:
+
+> [v0.1.10] | [v0.1.9] | [v0.1.8] | [v0.1.7] | [v0.1.6] | [v0.1.5] | [v0.1.4] | [v0.1.3] | [v0.1.2] | [v0.1.1]
+
+## Table of Contents
+
+- [About](#about)
+- [Trusted By](#trusted-by)
+- [Supported By](#supported-by)
+- [README Versions](#readme-versions)
+- [Table of Contents](#table-of-contents)
+- [Usage](#usage)
+  - [Cartesian Charts](#cartesian-charts)
+    - [Line Chart](#line-chart)
+    - [Stepline Chart](#stepline-chart)
+    - [Area Chart](#area-chart)
+    - [Column Chart](#column-chart)
+    - [Bar Chart](#bar-chart)
+    - [Range Bar Chart](#range-bar-chart)
+    - [Scatter Chart](#scatter-chart)
+    - [Candlestick Chart](#candlestick-chart)
+    - [Mixed Charts](#mixed-charts)
+    - [Syncing Charts](#syncing-charts)
+    - [Brush Chart](#brush-chart)
+    - [Annotations](#annotations)
+  - [Heatmap Chart](#heatmap-chart)
+  - [Radar Chart](#radar-chart)
+  - [Bubble Chart](#bubble-chart)
+  - [Polar Charts](#polar-charts)
+    - [Pie Chart](#pie-chart)
+    - [Donut Chart](#donut-chart)
+    - [Radial Bar Chart](#radial-bar-chart)
+- [Data Formats](#data-formats)
+  - [Cartesian Charts](#cartesian-charts-1)
+    - [Candlestick Chart](#candlestick-chart-1)
+  - [Heatmap Chart](#heatmap-chart-1)
+  - [Radar Chart](#radar-chart-1)
+  - [Bubble Chart](#bubble-chart-1)
+  - [Polar Charts](#polar-charts-1)
+- [Options](#options)
+  - [Global Options](#global-options)
+  - [Formatter Function](#formatter-function)
+  - [Defer Chart Rendering](#defer-chart-rendering)
+- [Reusable Custom Palette](#reusable-custom-palette)
+  - [Global Palette](#global-palette)
+  - [Local Palette](#local-palette)
+- [Use Alongside Other Charting Libraries](#use-alongside-other-charting-libraries)
+  - [Alongside Chartkick](#alongside-chartkick)
+    - [Chartkick (Chart.js) and ApexCharts](#chartkick-chartjs-and-apexcharts)
+    - [Chartkick (Google Charts) and ApexCharts](#chartkick-google-charts-and-apexcharts)
+    - [Chartkick (Highcharts) and ApexCharts](#chartkick-highcharts-and-apexcharts)
+- [Installation](#installation)
+- [Web Support](#web-support)
+  - [Rails](#rails)
+  - [Sinatra](#sinatra)
+  - [Plain HTML+ERB (Without Framework)](#plain-htmlerb-without-framework)
+- [Roadmap](#roadmap)
+- [Contributing](#contributing)
+- [License](#license)
+- [Like the charts?](#like-the-charts)
 
 
 ## Usage
@@ -101,6 +209,33 @@ Example options used for cartesian charts:
 ![Example Bar Chart](images/bar_chart.gif)
 
 
+#### Range Bar Chart
+
+```erb
+<% 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') %>
+```
+![Example Range Bar Chart](images/range_bar_chart.gif)
+
+
 #### Scatter Chart
 
 ```erb
@@ -110,6 +245,7 @@ Example options used for cartesian charts:
 
 
 #### 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.  
@@ -120,13 +256,18 @@ Given:
 <%
   require 'date'
 
-  def ohlc(ary)
-    [rand(ary.min..ary.max), ary.max, ary.min, rand(ary.min..ary.max)]
+  def candlestick_data
+    @acc = rand(6570..6650)
+    60.times.map {|i| [Date.today - 60 + i, ohlc] }.to_h
   end
 
-  candlestick_data = 50.times.map do |i|
-    [Date.today - 50 + i, ohlc(Array.new(2){ rand(6570..6650) })]
-  end.to_h
+  def ohlc
+    open = @acc + rand(-20..20)
+    high = open + rand(0..100)
+    low = open - rand(0..100)
+    @acc = close = open + rand(-((high-low)/3)..((high-low)/2))
+    [open, high, low, close]
+  end
 
   candlestick_options = {
     plot_options: {
@@ -146,9 +287,6 @@ You can make candlestick chart with this:
 ```
 ![Example Candlestick Chart](images/candlestick_chart.gif)
 
-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
 
@@ -176,7 +314,8 @@ you can do this:
 
 #### Syncing Charts
 
-You can synchronize charts by using `syncing_charts` or `synchronized_charts` methods. For example:
+You can synchronize charts by using `syncing_charts` or `synchronized_charts` methods. For
+example:
 ```erb
 <%= syncing_charts(chart: {toolbar: false}, height: 250, style: 'display: inline-block; width: 32%;') do %>
   <% mixed_charts(theme: 'palette4', data_labels: false) do %>
@@ -309,6 +448,7 @@ Also called `circle_chart`.
 ## Data Formats
 
 ### Cartesian Charts
+
 The data format for line, stepline, area, column, bar, and scatter
 charts should be in following format **per-series**:
 
@@ -331,6 +471,7 @@ or this:
 ```
 
 #### 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):
 
@@ -353,6 +494,7 @@ or this:
 ```
 
 ### 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.
@@ -376,6 +518,7 @@ or this:
 ```
 
 ### 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.
@@ -400,6 +543,7 @@ or this:
 
 
 ### Bubble Chart
+
 Bubble chart is similar to scatter chart, only they have one more value
 for bubble size:
 
@@ -412,10 +556,220 @@ for bubble size:
 ```
 
 ### 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](https://apexcharts.com/docs/options/),
+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
+
+```ruby
+title: { text: "Some title" }
+```
+In ApexCharts.RB you can write
+```ruby
+title: "Some title"
+```
+if you just want to add the text.
+
+`xtitle` and `ytitle` are even greater shortcuts. Instead of
+```ruby
+xaxis: { title: { text: "x title" } }
+```
+you can write
+```ruby
+xtitle: "x title"
+```
+
+```ruby
+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 use default options globally, you can specify config for default options before calling
+your charts. In Rails, put it in `initializers` directory. For example:
+
+```ruby
+# config/initializers/apexcharts.rb
+
+ApexCharts.config.default_options = {
+  data_labels: false,
+  tootip: true,
+  theme: 'my-theme'
+}
+```
+
+All charts will then automatically pick up these global options, which can be overwritten
+individually by any options passed to the relevant chart helper.
+
+### Formatter Function
+
+To use a _simple_ formatter function (e.g. formatter in `tooltip`, `data_labels`, and `labels`),
+you can add [functionable-json](https://github.com/styd/functionable-json) to your Gemfile and
+use it like so:
+
+```erb
+<%= area_chart series, tooltip: {y: {formatter: function(val) { return '$' + parseFloat(val).toLocaleString() }}} %>
+```
+
+Or, without the _functionable-json_ gem, use function as object as follows:
+
+```erb
+<%= area_chart series, tooltip: {y: {formatter: {function: {args: "val", body: "return '$' + parseFloat(val).toLocaleString();"}} }} %>
+```
+
+
+### Defer Chart Rendering
+
+It's possible to defer chart rendering by passing the argument `defer: true` as options.
+
+```erb
+<%= line_chart series, defer: true %>
+```
+
+
+## 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:
+
+```ruby
+# config/initializers/apexcharts.rb
+ApexCharts::Theme.create "rainbow", ["#ff0000", "#00ff00", "#0000ff"]
+```
+
+and later somewhere in your app views:
+
+```ruby
+# 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:
+
+```ruby
+ApexCharts::Theme.destroy "rainbow"
+```
+
+
+## Use Alongside Other Charting Libraries
+
+You can prefix the helper methods name with your chosen words to avoid name clashing with
+other charting libraries (e.g. chartkick, google_charts, etc.) you already use. Just set
+the `APEXCHARTS_PREFIX` environment variable to a string before you start your app server,
+say, 'awesome\_' and then on your views/templates use the chart helpers as `awesome_line_chart`,
+`awesome_area_chart`, and so on. `create_palette` and `destroy_palette` are left as is (not
+prefixed) as other libraries don't seem to have anything similar to them.
+
+Besides setting the environtment variable, if you just want a quick prefix, you can instead
+do this on your _Gemfile_:
+
+```ruby
+gem 'apexcharts', require: 'apex_charts/prefix_with_apex'
+```
+
+and you'll get `apex_line_chart`, `apex_area_chart`, etc.
+
+The prefix you set only applies to the outer chart helpers. The inner chart helpers is not
+prefixed. For example:
+
+```erb
+<%= awesome_syncing_chart(syncing_options) do %>
+  <% combo_chart(mixed_options) do %>
+    <% line_chart(line_series) %>
+    <% area_chart(area_series) %>
+  <% end %>
+<% end %>
+```
+
+### Alongside Chartkick
+
+Given:
+
+```erb
+<% series = [
+  {name: 'Verified', data: @verified_users},
+  {name: 'Unverified', data: @unverified_users}
+] %>
+<% options = {
+  legend: 'bottom', title: 'Users Grouped By Week For The Last 1 Year',
+  ytitle: 'Users', width: '100%', height: '300px'
+} %>
+```
+
+#### Chartkick (Chart.js) and ApexCharts
+
+```erb
+<div style="display: inline-block; width: 48%;">
+  <%= area_chart(series, {**options, adapter: 'chartjs'}) %>
+</div>
+<div style="display: inline-block; width: 48%;">
+  <%= apex_area_chart(series, options) %>
+</div>
+```
+
+![Chartkick (Chart.js) And ApexCharts](images/chartkick-chartjs-and-apexcharts.gif)
+
+#### Chartkick (Google Charts) and ApexCharts
+
+```erb
+<div style="display: inline-block; width: 48%;">
+  <%= area_chart(series, {**options, adapter: 'google'}) %>
+</div>
+
+<div style="display: inline-block; width: 48%;">
+  <%= apex_area_chart(series, options) %>
+</div>
+```
+
+![Chartkick (Google Charts) And ApexCharts](images/chartkick-google-and-apexcharts.gif)
+
+#### Chartkick (Highcharts) and ApexCharts
+
+```erb
+<div style="display: inline-block; width: 48%;">
+  <%= area_chart(series, {**options, adapter: 'highcharts'}) %>
+</div>
+
+<div style="display: inline-block; width: 48%;">
+  <%= apex_area_chart(series, options) %>
+</div>
+```
+
+![Chartkick (Highcharts) And ApexCharts](images/chartkick-highcharts-and-apexcharts.gif)
+
+
 ## Installation
 Add this line to your application's Gemfile:
 
@@ -433,53 +787,117 @@ $ bundle
 ## Web Support
 
 ### Rails
-After installing the gem, require it in your `app/assets/javascripts/application.js`.
+
+Require it in your `app/assets/javascripts/application.js`.
 ```js
-//= require 'apexcharts'
+//= require apexcharts
 ```
 
 Or, if you use `webpacker`, you can run:
 ```bash
-yarn add apexcharts
+$ yarn add apexcharts
 ```
 and then require it in your `app/javascript/packs/application.js`.
 ```js
-require("apexcharts")
+// AMD
+window.ApexCharts = require("apexcharts") // expose to window
+
+// or
+// ES6
+import ApexCharts from 'apexcharts'
+window.ApexCharts = ApexCharts
 ```
 
-### HTML+ERB
-After installing the gem, insert this to the top of your .html.erb files:
+### Sinatra
+
+Require it after you `require 'sinatra/base'` and add helper `Sinatra::ApexCharts` in the
+class that inherits from `Sinatra::Base`.
+
+```ruby
+require 'sinatra/base'
+require 'apexcharts'
 
-```html+erb
+class SimpleApp < Sinatra::Base
+  helpers Sinatra::ApexCharts
+end
+```
+
+To add the asset (ApexCharts.JS), include a script tag in your template
+as follows:
+
+```ruby
+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](examples/sinatra/sample.rb).
+
+
+### Plain HTML+ERB (Without Framework)
+
+Insert this to the top of your .html.erb files:
+
+```erb
 <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.
+
+```bash
+$ erb sample.html.erb > sample.html
 ```
 
 
-## TODOs
-- Replace dependency `smart_kv` with `dry-schema`
-- Create reusable theme palette
-- Add more features (e.g. gradient line, background image, etc.)
-- Range bar chart
-- Support other ruby frameworks (sinatra, hanami, etc.)
+## 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_kv` with `dry-schema`
+  - Display warnings on browser console on development instead of error page when
+    schema doesn't meet
 
 
 ## 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 above
+- Implementing todos on Roadmap above
 
 
 ## License
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
 
+The gem is available as open source under the terms of the
+[MIT License](https://opensource.org/licenses/MIT).
+
+
+## Articles
+
+- [Rails em 8 minutos: Criando gráficos incríveis com ApexCharts](https://onebitcode.com/graficos-incriveis-no-ruby-on-rails/)
+- [【Rails】 5分でApexChart.jsを導入する方法](https://qiita.com/syukan3/items/aa741df278f628087a3c)
+
+
+[ApexCharts.JS]: https://github.com/apexcharts/apexcharts.js
 
-## Like the charts?
-Consider donating to the author of apexcharts.js to support his awesome library.
-This project wouldn't be possible without it.
 
-Become a sponsor on [Patreon](https://patreon.com/junedchhipa).  
-One time donation on [PayPal](https://paypal.me/junedchhipa)
+[v0.1.10]: https://github.com/styd/apexcharts.rb/blob/v0.1.10/README.md
+[v0.1.9]: https://github.com/styd/apexcharts.rb/blob/v0.1.9/README.md
+[v0.1.8]: https://github.com/styd/apexcharts.rb/blob/v0.1.8/README.md
+[v0.1.7]: https://github.com/styd/apexcharts.rb/blob/v0.1.7/README.md
+[v0.1.6]: https://github.com/styd/apexcharts.rb/blob/v0.1.6/README.md
+[v0.1.5]: https://github.com/styd/apexcharts.rb/blob/v0.1.5/README.md
+[v0.1.4]: https://github.com/styd/apexcharts.rb/blob/v0.1.4/README.md
+[v0.1.3]: https://github.com/styd/apexcharts.rb/blob/v0.1.3/README.md
+[v0.1.2]: https://github.com/styd/apexcharts.rb/blob/v0.1.2/README.md
+[v0.1.1]: https://github.com/styd/apexcharts.rb/blob/v0.1.1/README.md