amcharts.rb 3.1.1.0.pre → 3.1.1.0

checksums.yaml

@@ -1,15 +1,15 @@
 ---
 !binary "U0hBMQ==":
   metadata.gz: !binary |-
-    ODI4YjFhOTIzMTI5N2Q4ZTc0OWU2MTQ5MGE5ZjkwM2IxN2Q1Zjk2Zg==
+    ODVlZmZmZjJiZmUxOWU4NmYzYzg5NGYzNTM3ZWMyZjIzYzM0OWQ3Mw==
   data.tar.gz: !binary |-
-    ZDA0YWM4MTY0MWM0MDlmYzY0ZTRiYTIyMDFkNTYwMjc2OWI5ZjNmNQ==
+    YjIxZTAwYTFkNmRlODhlODFiYjgwZDVkNjk1M2FhYjRkZWUwZmRiYw==
 SHA512:
   metadata.gz: !binary |-
-    N2QyMGI3YTllNzZiOTU5ZDMzZmYzODc3ODFkZWJkM2FmNWY4ZGQ3ZDdmOWQy
-    OWY2Y2NlNTFhZDVhMzU3NDFjMGI0Njg1MTI3OWFjNWFhYzU3N2NhYTI5Njhm
-    ZGZlMmExNWI1MTlhZjYyY2NlMTNiYzEyMzk5Yjc2MDhkOTk0YTE=
+    MWNkNjlkMjVmZDRkM2EyZDc1NDk5MDQ3OGRkYWJjOWU3OTM1OWNkYjUzOTE2
+    OGJiZDljMGE2ZTc5YTJmMmU2NzA0ZDMwYmFiY2M1NWQxMTY4YzA4YTRiMzc3
+    ZDZjZGI1OGUyZTVmYjhiMWRjYjljZGE5OGQyMTJkYjU1ZGI2ODQ=
   data.tar.gz: !binary |-
-    MGI2NmI0ZGM1YjIxYjgyNWVlYzc4ZjhkODJjMTBkYjU0ZWVjNGRkMTg2NDc3
-    M2ZiMDYyMjJlM2EzNzI2ZDVhZWI2ZDliZDc1YjdjZTMyMzg1NjU5MTk0MjUw
-    ODg4NjcwYTE0ZDJhYWVjZDYxNmVhOWRhYTgwY2JlOTc0Y2UyNWQ=
+    ODhkNGVlNTM1ZjA5MTBhN2I1NzYwODAyOThmYjgwY2Q0MTMwNGVlOGZmMzgx
+    ZDA5MTYwZTIwYTc4ZTQ4OGIzMTg5YzdlNWZjYWU3MmVlNTBmNDU1NzlhOGUw
+    M2NmNGQ5MjA4YWMxNWI3OTFlYTRmMDFmNjViYTM0NmRlZTdkNmI=

data/.gitignore

@@ -1,6 +1,7 @@
 *.gem
 *.rbc
 .bundle
+.DS_Store
 .config
 .idea
 .yardoc

data/README.md

@@ -1,6 +1,69 @@
-# Amcharts.rb
+# AmCharts.rb
 
-TODO: Write a gem description
+Ruby on Rails wrapper for creating AmCharts charts.
+
+## Usage
+
+A chart is represented by a subclass of `AmCharts::Chart` (ie. `Pie` or `Serial`), which is initialized with a data collection (should be an array
+of homogeneous hashes), and some settings passed into a block:
+
+    chart = AmCharts::Chart::Serial.new(data) do |c|
+      add_title 'My Fancy Chart', size: 18
+      loading_indicator!
+
+      c.dimensions = '800x600'
+
+      legends.new do |l|
+        l.position = 'right'
+        l.value_text = '[[percents]]%'
+      end
+
+      scrollbar {}
+    end
+
+The setup block accepts a number of methods for ease of setting up a chart, and accepts any other assignment method as a setting
+that will be passed directly to AmCharts when the chart is rendered. Chart components including graphs, legends, axes, scrollbars and
+cursors can also be added and configured using inner blocks. Listeners can also be defined in a similar manner.
+
+Values in the setup block can be numeric or string literals (which will be passed along as is); symbols (which will be
+given to `I18n.t` before being rendered); procs (which will be executed); or the `function()` method (which will act as
+a literal javascript function).
+
+An `AmCharts::Chart` object can then be rendered using the `amcharts` helper:
+
+    amcharts(chart, 'id-of-container')
+
+If the container ID given doesn't already exist in the page, it will be automatically created before the chart is rendered
+by AmCharts.
+
+### Chart setup methods
+* `add_title(text, options: {})`: Adds a title element to the chart. `options` can be used to specify `size`, `bold` (`true`
+or `false`), `alpha` (`0..1`), and/or `color` (a hex color code).
+* `loading_indicator!`: Displays a loading indicator over the chart until it has completed rendering. The indicator makes use of
+an I18n key (`chart_data_loading`) and an image (`amcharts/loading.gif`) which both can be customized within your application.
+* `detach_legend(div: true)`: Makes the legend (if present) render in a separate div. `div` can either be `true` (which will
+cause the legend div to be given an ID the same as the main div, with a "_legend" suffix), or the ID you want to give the div.
+* `dimensions=('widthxheight')`: Allows width and height to be specified in one line
+
+### Notes about defining a chart
+* Serial charts need to have their `graphs` defined on setup (this also allows multiple graphs to be defined; ie. for a multi-line chart).
+Graphs are initialized with `(name, type)`, where `type` is a [type of graph](http://docs.amcharts.com/javascriptcharts/AmGraph#type)
+that AmCharts is aware of (`:column`, `:line`, `:step`, etc.)
+
+        AmCharts::Chart::Serial.new(data) do
+          [:col1, :col2, :col3].each do |column|
+          graphs.new(column, :smoothedLine) do |g|
+            g.title = column
+          end
+        end
+
+* Pie charts do not use `graphs`, as they get their values directly from the given data set.
+
+## Using a Commercial AmCharts license
+
+If you have purchased the commercial version of AmCharts, place the amcharts.js file it comes with inside a
+`javascripts/amcharts` directory within `(app|lib|vendor)/assets`, so that it will be used instead of the free
+version that is included in this gem.
 
 ## Installation
 
@@ -16,10 +79,6 @@ Or install it yourself as:
 
     $ gem install amcharts.rb
 
-## Usage
-
-TODO: Write usage instructions here
-
 ## Contributing
 
 1. Fork it
@@ -27,3 +86,8 @@ TODO: Write usage instructions here
 3. Commit your changes (`git commit -am 'Add some feature'`)
 4. Push to the branch (`git push origin my-new-feature`)
 5. Create new Pull Request
+
+## Acknowledgments
+
+* Built upon the excellent [AmCharts Javascript V3](http://www.amcharts.com/javascript-charts/) charting package.
+* Special thanks to [TalentNest](http://github.com/talentnest), who sponsored this gem's development.

data/Rakefile

@@ -1 +1,5 @@
 require "bundler/gem_tasks"
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+task :default => :spec

data/amcharts.rb.gemspec

@@ -4,20 +4,22 @@ $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 require 'amcharts/version'
 
 Gem::Specification.new do |spec|
-  spec.name          = "amcharts.rb"
+  spec.name          = 'amcharts.rb'
   spec.version       = AmCharts::VERSION
-  spec.authors       = ["Daniel Vandersluis"]
-  spec.email         = ["dvandersluis@selfmgmt.com"]
+  spec.authors       = ['Daniel Vandersluis']
+  spec.email         = ['dvandersluis@selfmgmt.com']
   spec.description   = %q{Ruby wrapper for Amcharts}
   spec.summary       = %q{Wrapper for Amcharts 3 Javascript charts}
-  spec.homepage      = "https://github.com/dvandersluis/amcharts.rb"
-  spec.license       = "MIT"
+  spec.homepage      = 'https://github.com/dvandersluis/amcharts.rb'
+  spec.license       = 'MIT'
 
   spec.files         = `git ls-files`.split($/)
   spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
   spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
-  spec.require_paths = ["lib"]
+  spec.require_paths = %w(lib)
 
-  spec.add_development_dependency "bundler", "~> 1.3"
-  spec.add_development_dependency "rake"
+  spec.add_dependency 'rails', '> 3.0.0'
+  spec.add_dependency 'collection_of', '>= 1.0.3'
+  spec.add_development_dependency 'bundler', '~> 1.3'
+  spec.add_development_dependency 'rake'
 end

data/app/assets/javascripts/amcharts.js

@@ -0,0 +1,119 @@
+/*
+ *= require amcharts/amcharts
+*/
+
+// Add indexOf and getElementsByClassName methods
+// See: http://stackoverflow.com/questions/13261506/getelementsbyclassname-in-ie8
+(function() {
+  var indexOf = [].indexOf || function(prop) {
+    for (var i = 0; i < this.length; i++) {
+      if (this[i] === prop) return i;
+    }
+    return -1;
+  };
+  window.getElementsByClassName = function(className,context) {
+    if (context.getElementsByClassName) return context.getElementsByClassName(className);
+    var elems = document.querySelectorAll ? context.querySelectorAll("." + className) : (function() {
+      var all = context.getElementsByTagName("*"),
+        elements = [],
+        i = 0;
+      for (; i < all.length; i++) {
+        if (all[i].className && (" " + all[i].className + " ").indexOf(" " + className + " ") > -1 && indexOf.call(elements,all[i]) === -1) elements.push(all[i]);
+      }
+      return elements;
+    })();
+    return elems;
+  };
+})();
+
+function add_container_if_needed(id, width, height)
+{
+  var container = document.getElementById(id);
+
+  if (!container)
+  {
+    container = document.createElement("DIV");
+    container.className = 'chart';
+    container.id = id;
+    container.style.width = width + 'px';
+    container.style.height = height + 'px';
+
+    // Add the container before the last script
+    var scripts = document.getElementsByTagName('script');
+    var this_script = scripts[scripts.length - 1];
+    this_script.parentNode.insertBefore(container, this_script);
+  }
+
+  return container;
+}
+
+function add_loading_indicator(container, width, height, message, image_path)
+{
+  var wrapper = document.createElement("DIV"),
+      blanket = document.createElement("DIV"),
+      blanket_container = document.createElement("DIV"),
+      blanket_outer = document.createElement("DIV"),
+      blanket_inner = document.createElement("DIV"),
+      loading_div = document.createElement("DIV"),
+      loading_image = document.createElement("IMG"),
+      loading = document.createTextNode(message);
+
+  wrapper.className = 'chart-wrapper';
+  wrapper.style.width = width + 'px';
+  wrapper.style.minHeight = height + 'px';
+
+  blanket.className = 'chart-blanket';
+
+  loading_div.className = 'chart-loading';
+  loading_image.className = 'chart-loading-image';
+  loading_image.src = image_path;
+
+  container.parentNode.insertBefore(wrapper, container);
+
+  blanket_container.appendChild(blanket_outer)
+  blanket_outer.appendChild(blanket_inner);
+  blanket_inner.appendChild(loading_div);
+  loading_div.appendChild(loading);
+  blanket_inner.appendChild(loading_image);
+
+  blanket.appendChild(blanket_container);
+  wrapper.appendChild(blanket);
+  wrapper.appendChild(container);
+}
+
+function hide_loading_indicator(chart)
+{
+  var container = chart.container.div;
+  var wrapper = container;
+  while ((" " + wrapper.className + " ").indexOf(" chart-wrapper ") < 0)
+  {
+    wrapper = wrapper.parentElement;
+  }
+
+  getElementsByClassName('chart-blanket', wrapper)[0].style.display = 'none';
+}
+
+function add_legend_div(id, main_div)
+{
+  var legend = document.getElementById(id);
+
+  if (!legend)
+  {
+    legend = document.createElement("DIV");
+    legend.className = 'chart-legend';
+    legend.id = id;
+    legend.style.width = main_div.getWidth() + 'px';
+
+    var wrapper = main_div.parentNode;
+    if(main_div.nextSibling)
+    {
+      wrapper.insertBefore(legend, main_div.nextSibling);
+    }
+    else
+    {
+      wrapper.appendChild(legend);
+    }
+  }
+
+  return legend;
+}

data/app/assets/stylesheets/amcharts.css

@@ -0,0 +1,39 @@
+.chart-wrapper
+{
+  position: relative;
+}
+
+.chart-wrapper .chart-blanket
+{
+  width: 100%;
+  height: 100%;
+  position: absolute;
+  top: 0;
+  left: 0;
+  z-index: 10000;
+  background: white;
+}
+
+.chart-wrapper .chart-blanket > div
+{
+  position: relative;
+  width: 100%;
+  height: 100%;
+  overflow-x: hidden;
+}
+
+.chart-wrapper .chart-blanket > div > div
+{
+  float: left;
+  position: relative;
+  left: 50%;
+  top: 50%;
+  margin-top: -18px;
+}
+
+.chart-wrapper .chart-blanket > div > div > div
+{
+  position: relative;
+  right: 50%;
+  text-align: center;
+}

data/app/helpers/amcharts/amcharts_helper.rb

@@ -0,0 +1,24 @@
+module AmCharts
+  module AmChartsHelper
+    def amchart(chart, container)
+      # Load necessary JS and CSSfiles, without loading one more than once
+      @loaded_amchart_files ||= { js: [], css: []}
+
+      js_files = ['amcharts', "amcharts/#{chart.type}"] - @loaded_amchart_files[:js]
+      css_files = ['amcharts'] - @loaded_amchart_files[:css]
+
+      @loaded_amchart_files[:js] += js_files
+      @loaded_amchart_files[:css] += css_files
+
+      content_for(:javascript) { javascript_include_tag(*js_files) }
+      content_for(:stylesheets) { stylesheet_link_tag(*css_files) }
+
+      # Render the chart builder
+      builder = AmCharts::ChartBuilder.new(chart, self)
+      chart.container = container
+      javascript_tag do
+        builder.render_js('chart_builder', template_type: :file, locals: { chart: chart, container: container })
+      end
+    end
+  end
+end

data/app/views/amcharts/_collection.erb

@@ -0,0 +1,5 @@
+<% collection.each.with_index do |obj, index| -%>
+  <%= builder.render_js('object', template_type: :layout, object: obj, locals: local_assigns.merge(var: "#{name}#{index}")) do |obj, var| %>
+    <%= yield(obj, var) rescue nil %>
+  <% end %>
+<% end %>

data/app/views/amcharts/_data.erb

@@ -0,0 +1,10 @@
+<% if chart.pie? %>
+  chart.valueField = '<%= chart.value_field %>';
+  chart.titleField = '<%= chart.title_field %>';
+<% else %>
+  <%#= render(layout: 'amcharts/collection', object: chart.graphs, locals: { builder: builder, name: :graph, type: 'AmGraph' }) do |obj, var| %>
+  <%= builder.render_js('collection', template_type: :layout, object: chart.graphs, locals: { name: :graph, type: 'AmGraph' }) do |obj, var| %>
+    <%= var %>.valueField = '<%= obj.value_field %>';
+    <%= var %>.type = '<%= obj.type %>';
+  <% end %>
+<% end %>

data/app/views/amcharts/_legend.erb

@@ -0,0 +1,4 @@
+var legend = new AmCharts.AmLegend;
+<% builder.render_settings(legend, 'legend') %>
+<%= yield(legend, 'legend') rescue nil %>
+chart.addLegend(legend, <%= builder.to_js(div) %>);

data/app/views/amcharts/_listener.erb

@@ -0,0 +1 @@
+chart.addListener(<%= builder.to_js(type.to_s) %>, function() { return <%= method %>.apply(null, [chart]) });

data/app/views/amcharts/_object.erb

@@ -0,0 +1,12 @@
+<% if object %>
+  <% var = local_assigns.fetch(:var, name) %>
+  <% method = local_assigns.fetch(:method, "add#{name.to_s.camelize}") %>
+  <% js_object = local_assigns.fetch(:js_object, "new AmCharts.#{local_assigns.fetch(:type, name.to_s.camelize)}") %>
+
+  var <%= var %> = <%= js_object %>;
+  <% builder.render_settings(object, var.to_s) %>
+  <%= yield(object, var) rescue nil %>
+  <% if method %>
+    chart.<%= method %>(<%= var %>);
+  <% end %>
+<% end %>

data/app/views/amcharts/_settings.erb

@@ -0,0 +1 @@
+<%= name %>.<%= key.camelize(:lower) %> = <%= builder.to_js(value) %>;

data/app/views/amcharts/_title.erb

@@ -0,0 +1 @@
+chart.addTitle(<%= builder.to_js(title) %>, <%= builder.to_js(options[:size]) %>, <%= builder.to_js(options[:color]) %>, <%= builder.to_js(options[:alpha]) %>, <%= builder.to_js(options[:bold]) %>);

data/app/views/amcharts/chart_builder.erb

@@ -0,0 +1,36 @@
+// If the container element doesn't already exist, create it
+var container = add_container_if_needed('<%= container %>', <%= chart.width %>, <%= chart.height %>);
+
+<% if chart.loading_indicator? %>
+  add_loading_indicator(container, <%= chart.width %>, <%= chart.height %>, <%= builder.to_js(:chart_data_loading) %>, '<%= escape_javascript asset_path('amcharts/loading.gif') %>');
+<% end %>
+
+<% if chart.legend_div %>
+  add_legend_div('<%= chart.legend_div == true ? "#{container}_legend" : chart.legend_div %>', container);
+<% end %>
+
+AmCharts.ready(function() {
+  var chart_data = <%= builder.to_js(chart.data) %>;
+  var chart = new <%= chart.amchart_type %>;
+
+  chart.dataProvider = chart_data;
+  chart.categoryField = '<%= chart.category_field %>';
+  chart.pathToImages = '<%= escape_javascript asset_path('amcharts/') %>';
+
+  <% builder.render_settings(chart, 'chart') %>
+
+  <% builder.render_data %>
+
+  <% builder.render_legend %>
+
+  <% builder.render_component(chart.category_axis, name: :category_axis, js_object: 'chart.categoryAxis', method: false) %>
+  <% builder.render_component(chart.value_axes, name: :value_axis) %>
+  <% builder.render_component(chart.cursor, name: :chart_cursor) %>
+  <% builder.render_component(chart.scrollbar, name: :chart_scrollbar) %>
+
+  <% builder.render_title %>
+
+  <% builder.render_listeners %>
+
+  chart.write('<%= container %>');
+});

data/lib/amcharts.rb

@@ -1,9 +1,29 @@
+require 'collection_of'
 require "amcharts/version"
+require_relative '../app/helpers/amcharts/amcharts_helper'
 
 module AmCharts
-  if defined?(Rails)
-    class Engine < ::Rails::Engine
+  autoload :Axis,         'amcharts/axis'
+  autoload :Chart,        'amcharts/chart'
+  autoload :ChartBuilder, 'amcharts/chart_builder'
+  autoload :Cursor,       'amcharts/cursor'
+  autoload :Graph,        'amcharts/graph'
+  autoload :Legend,       'amcharts/legend'
+  autoload :Listener,     'amcharts/listener'
+  autoload :ScrollBar,    'amcharts/scroll_bar'
+  autoload :Settings,     'amcharts/settings'
+  autoload :UsesSettings, 'amcharts/uses_settings'
 
-    end
+  ActiveSupport::Inflector.inflections do |inflect|
+    inflect.acronym "AmCharts"
   end
+
+  Engine = Class.new(::Rails::Engine) do
+    # Load the Amcharts helper when loading ActionView
+    initializer 'amcharts.action_controller' do |app|
+      ActiveSupport.on_load :action_controller do
+        helper AmCharts::AmChartsHelper
+      end
+    end
+  end if defined?(Rails)
 end