volt-highcharts 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: c3d80171d3265558b6ae56c93561728293fbaf8e
+  data.tar.gz: 625467100a4c7cd3aa655cb3674ee42d0a825a64
+SHA512:
+  metadata.gz: e56df08f4f33341d83895f5cb9973393c73079149f4432a95ff8ebe67493e96d9ce6ab0311e2fc3c00f879d8455ca9f914c6e165575cf5f73a20d19825a6f5fd
+  data.tar.gz: c1911fe995e81aef5efc4b1281eb63f44ed5e82295f6c4c51125d0b8b3d9ed4cc1165574a35d290e533132787767576646a22f8319584553124b77bb9fb34191

data/.rspec

@@ -0,0 +1,2 @@
+--format documentation
+--color

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in volt-highcharts.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2015 balmoral
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,133 @@
+# Volt::Highcharts
+
+A Volt component wrapping the Highcharts javascript charting tool.
+
+Highcharts is free for non-commercial use.
+
+http://www.highcharts.com/products/highcharts
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'volt-highcharts'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install volt-highcharts
+
+## Usage
+
+First include the gem in the project's Gemfile:
+
+```gem 'volt-highcharts'```
+
+Next add volt-highcharts to the dependencies.rb file:
+
+```component 'highcharts'```
+
+Pass a Ruby hash containing chart options in the appropriate view html file:
+
+```html
+<:highcharts chart="{{ chart_options }}" />
+```
+
+where `chart_options` is provided by your controller or model. Any object which responds to #to_h may be used, including of course a Volt::Model.
+
+Documentation for Highcharts options can be found at: http://api.highcharts.com/highcharts#chart.
+
+At present only a copy of the chart options are passed to Highcharts so the binding will not update the chart automatically.
+ 
+For convenience, the last chart added can simply be accessed as ```page._chart```, wrapped by Opal's Native().
+ 
+To query or modify multiple chart(s) on the page a unique :id should be set in each chart's options. 
+
+For example:
+```
+    def fruit_chart_options
+      {
+        # to identity the chart in volt
+        id: 'fruit_chart',
+        
+        # highcharts options
+        chart: {
+          type: 'bar'
+        },
+        title: {
+          text: 'Fruit Consumption'
+        },
+        xAxis: {
+          categories: %w(Apples Bananas Oranges)
+        },
+        yAxis: {
+          title: {
+              text: 'Fruit eaten'
+          }
+        },
+        series: [
+          {
+            name: 'Jane',
+            data: [1, 0, 4]
+          },
+          {
+            name: 'John',
+            data: [5, 7, 3]
+          },
+          ...
+        ]
+      }
+    end
+```
+
+You can later find the chart in page._charts, the elements of which are Volt::Model's each having an _id and a _chart attribute.
+
+For example, in your controller you might have a method to return the native chart:
+```
+  def find_chart(id)
+    # NB use detect, not find
+    e = page._charts.detect { |e| e._id == id }
+    e ? e._chart : nil
+  end
+```
+If you only have one chart on the page use ```page._chart```.
+
+You can dynamically query or modify the chart(s) using Opal's Native() or inline scripting.
+
+The chart object(s) found in ```page._chart``` and ```page._charts``` have been wrapped in Opal's Native(). This is because Volt::Model and Volt::ArrayModel can only hold Ruby objects.   
+
+Opal's Native() wraps a JS object to provide access to properties and functions in the JS object via Ruby method calls. As of writing (July 30, 2015) Native has not yet been documented. If you prefer to use backticks or %x{} to inline JS code you can get the JS object using #to_n.
+
+For example, to change a series in a chart using Native(), you might do:
+```
+  def update_sales
+    e = page._charts.find { |e| e._id == 'sales' }
+    series = Native(e._chart.series)
+    Native(series[0]).setData(sales_data.to_n)
+  end
+```
+The equivalent using backticks is:
+```
+  def update_sales
+    native_chart = page._chart.to_n # get the native JS chart
+    native_data = sales_data.to_n # get native sales data
+    `native_chart.series[0].setData(native_data)`
+  end
+```
+
+Always use #to_n to convert Ruby data to JS when passing to Highcharts.
+
+In the future we hope to provide a fully wrapped Ruby implementation of Highcharts.
+
+## Contributing
+
+The author is new to things javascript, opal and volt, so contributions and suggestions are very welcome.
+ 
+1. Fork it ( http://github.com/balmoral/volt-highcharts/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+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

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/app/highcharts/config/dependencies.rb

@@ -0,0 +1,2 @@
+# Component dependencies
+javascript_file 'http://code.highcharts.com/highcharts.js'

data/app/highcharts/config/initializers/boot.rb

@@ -0,0 +1,14 @@
+# Place any code you want to run when the component is included on the client
+# or server.
+
+# To include code only on the client use:
+# if RUBY_PLATFORM == 'opal'
+#
+# To include code only on the server, use:
+# unless RUBY_PLATFORM == 'opal'
+# ^^ this will not send compile in code in the conditional to the client.
+# ^^ this include code required in the conditional.
+
+if RUBY_PLATFORM == 'opal'
+  require 'native'
+end

data/app/highcharts/config/routes.rb

@@ -0,0 +1 @@
+# Component routes

data/app/highcharts/controllers/main_controller.rb

@@ -0,0 +1,72 @@
+module Highcharts
+  class MainController < Volt::ModelController
+
+    def index_ready
+      Volt.logger.debug("#{self.class.name}##{__method__}:#{__LINE__} : #{Time.now}")
+
+      # Get the containing html element.
+      container = self.container
+      Volt.logger.debug("#{self.class.name}##{__method__}:#{__LINE__} : container='#{container}'")
+
+      opts = attrs.chart ? attrs.chart.to_h : missing_chart
+
+      # If the view hasn't set a container id then
+      # use the id in the chart options if present
+      # otherwise to a random id.
+      id = `$(container).prop("id")`
+      Volt.logger.debug("#{self.class.name}##{__method__}:#{__LINE__} : initial container id is '#{id}'")
+      unless id == nil || id == 'undefined'
+        id = opts[:id] || random_id
+        Volt.logger.debug("#{self.class.name}##{__method__}:#{__LINE__} : char container id is undefined - setting to '#{id}'")
+        `$(container).prop("id", id)`
+      end
+
+      # If :renderTo has been set in the options then it
+      # should match the id of the container, otherwise
+      # a Highcharts error #13 will occur. It should be
+      # unique in the page. We do not check here.
+      #
+      # If :renderTo has not been set in the options then
+      # it will be set here to the container id.
+      unless opts[:chart] && opts[:chart][:renderTo]
+        Volt.logger.debug("#{self.class.name}##{__method__}:#{__LINE__} : setting opts[:chart][:renderTo]='#{id}'")
+        (opts[:chart] ||= {})[:renderTo] = id
+      end
+
+      # Render the chart and add it to the page._charts.
+      # _charts ia an array of Volt::Models with an id and a chart attribute.
+      @id = opts[:id] || id
+      chart = Native(`new Highcharts.Chart( #{opts.to_n} )`) # needs to wrapped for Volt::Model
+      page._charts << Volt::Model.new({id: @id, chart: chart})
+      page._chart = chart # a simple way for later access
+      page._chart_id = id # so we know whether it's me
+      Volt.logger.debug("#{self.class.name}##{__method__}:#{__LINE__} : page._charts='#{page._charts}' page._charts.size=#{page._charts.size}")
+    end
+
+    def before_index_remove
+      Volt.logger.debug("#{self.class.name}##{__method__}:#{__LINE__} #{Time.now}")
+      # clear all references to this chart
+      i = page._charts.find_index { |e| e._id == @id }
+      if i
+        deleted = page._charts.delete_at(i)
+        Volt.logger.debug("#{self.class.name}##{__method__}:#{__LINE__} : deleted='#{deleted}' page._charts.size=#{page._charts.size}")
+        deleted._chart.destroy
+        deleted._chart = nil
+      end
+      page._chart = nil if page._chart_id == @id
+      @id = nil
+    end
+
+    private
+
+    # generate a unique id for chart container
+    def random_id
+      "highcharts#{(rand * 1000000000).to_i}"
+    end
+
+    def missing_chart
+      { chart: { title: 'no chart attribute set for :highcharts component' } }
+    end
+
+  end
+end

data/app/highcharts/views/main/index.html

@@ -0,0 +1,2 @@
+<:Body>
+

data/lib/volt/highcharts/version.rb

@@ -0,0 +1,5 @@
+module Volt
+  module Highcharts
+    VERSION = '0.1.0'
+  end
+end

data/lib/volt/highcharts.rb

@@ -0,0 +1,18 @@
+# If you need to require in code in the gem's app folder, keep in mind that
+# the app is not on the load path when the gem is required.  Use
+# app/{gemname}/config/initializers/boot.rb to require in client or server
+# code.
+#
+# Also, in volt apps, you typically use the lib folder in the
+# app/{componentname} folder instead of this lib folder.  This lib folder is
+# for setting up gem code when Bundler.require is called. (or the gem is
+# required.)
+#
+# If you need to configure volt in some way, you can add a Volt.configure block
+# in this file.
+
+module Volt
+  module Highcharts
+    # Your code goes here...
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,14 @@
+# Volt sets up rspec and capybara for testing.
+require 'volt/spec/setup'
+Volt.spec_setup
+
+RSpec.configure do |config|
+  config.run_all_when_everything_filtered = true
+  config.filter_run :focus
+
+  # Run specs in random order to surface order dependencies. If you find an
+  # order dependency and want to debug it, you can fix the order by providing
+  # the seed, which is printed after each run.
+  #     --seed 1234
+  config.order = 'random'
+end

data/spec/volt/highcharts_spec.rb

@@ -0,0 +1,11 @@
+require 'spec_helper'
+
+describe Volt::Highcharts do
+  it 'should have a version number' do
+    expect(Volt::Highcharts::VERSION).not_to be nil
+  end
+
+  it 'should do something useful' do
+    expect(false).to be true
+  end
+end

data/volt-highcharts.gemspec

@@ -0,0 +1,23 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'volt/highcharts/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "volt-highcharts"
+  spec.version       = Volt::Highcharts::VERSION
+  spec.authors       = ["Colin Gunn"]
+  spec.email         = ["colgunn@icloud.com"]
+  spec.summary       = %q{Volt component wrapping Highcharts JavaScript library.}
+  spec.homepage      = "https://github.com/balmoral/volt-highcharts"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  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.add_development_dependency "volt", "~> 0.9.5.pre3"
+  # spec.add_development_dependency 'rspec', '~> 3.2.0'
+  # spec.add_development_dependency "rake"
+end

metadata

@@ -0,0 +1,62 @@
+--- !ruby/object:Gem::Specification
+name: volt-highcharts
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Colin Gunn
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2015-07-30 00:00:00.000000000 Z
+dependencies: []
+description: 
+email:
+- colgunn@icloud.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- app/highcharts/config/dependencies.rb
+- app/highcharts/config/initializers/boot.rb
+- app/highcharts/config/routes.rb
+- app/highcharts/controllers/main_controller.rb
+- app/highcharts/views/main/index.html
+- lib/volt/highcharts.rb
+- lib/volt/highcharts/version.rb
+- spec/spec_helper.rb
+- spec/volt/highcharts_spec.rb
+- volt-highcharts.gemspec
+homepage: https://github.com/balmoral/volt-highcharts
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.4.6
+signing_key: 
+specification_version: 4
+summary: Volt component wrapping Highcharts JavaScript library.
+test_files:
+- spec/spec_helper.rb
+- spec/volt/highcharts_spec.rb
+has_rdoc: