acts_as_dashboard 0.1.0

data/lib/acts_as_dashboard/short_messages_widget.rb

@@ -0,0 +1,25 @@
+module ActsAsDashboard
+  class ShortMessagesWidget < ActsAsDashboard::Widget
+    @@default_max_data_items = 5
+
+    attr_reader :max_data_items
+
+    def initialize(options = {})
+      options.delete :type
+
+      self.type           = :short_messages
+      self.max_data_items = options[:max_data_items] || @@default_max_data_items
+
+      super
+    end
+
+    def max_data_items=(max_data_items)
+      raise ArgumentError, 'The "max_data_items" argument must be a Fixnum.' unless max_data_items.is_a? Fixnum
+      @max_data_items = max_data_items
+    end
+
+    def attributes
+      super.merge(:max_data_items => @max_data_items)
+    end
+  end
+end

data/lib/acts_as_dashboard/widget.rb

@@ -0,0 +1,55 @@
+module ActsAsDashboard
+  class Widget
+    attr_reader :type
+    attr_reader :name
+    attr_reader :title
+    attr_reader :block
+    attr_reader :update_interval
+
+    def initialize(options = {})
+      self.type             = options[:type]            if options[:type]
+      self.name             = options[:name]            if options[:name]
+      self.title            = options[:title]           if options[:title]
+      self.block            = options[:block]           if options[:block]
+      self.update_interval  = options[:update_interval] if options[:update_interval]
+    end
+
+    def type=(type)
+      raise ArgumentError, 'The "type" argument must be a Symbol.' unless type.is_a? Symbol
+      @type = type
+    end
+
+    def name=(name)
+      raise ArgumentError, 'The "name" argument must be a Symbol.' unless name.is_a? Symbol
+      @name = name
+    end
+
+    def title=(title)
+      raise ArgumentError, 'The "title" argument must be a String.' unless title.is_a? String
+      @title = title
+    end
+
+    def block=(block)
+      raise ArgumentError, 'The "block" argument must be a Proc.' unless block.is_a? Proc
+      @block = block
+    end
+
+    def data(&block)
+      self.block = block
+    end
+
+    def update_interval=(update_interval)
+      raise ArgumentError, 'The "update_interval" argument must be a Fixnum or String.' unless [Fixnum, String].include? update_interval.class
+      @update_interval = update_interval
+    end
+
+    def attributes
+      {
+        :type             => @type,
+        :name             => @name,
+        :title            => @title,
+        :update_interval  => @update_interval,
+      }
+    end
+  end
+end

data/lib/acts_as_dashboard.rb

@@ -0,0 +1,17 @@
+class ActionController::Base
+  class << self
+    def inherited_with_acts_as_dashboard_include(child)
+      inherited_without_acts_as_dashboard_include child
+
+      child.send :include, ActsAsDashboard
+    end
+
+    alias_method_chain :inherited, :acts_as_dashboard_include
+  end
+end
+
+module ActsAsDashboard
+  def self.included(base)
+    base.extend ClassMethods
+  end
+end

data/spec/acts_as_dashboard/class_method_specs.rb

@@ -0,0 +1,188 @@
+require File.join File.dirname(__FILE__), '..', 'spec_helper'
+
+describe ActsAsDashboard::ClassMethods do
+  it 'makes its "dashboard_config" instance variable readable' do
+    class DashboardsController < ApplicationController
+      acts_as_dashboard
+    end
+
+    DashboardsController.dashboard_config.should be_a ActsAsDashboard::Config
+  end
+
+  describe '#acts_as_dashboard' do # {{{
+    before :each do
+      @config = mock ActsAsDashboard::Config
+      ActsAsDashboard::Config.stub(:new).and_return @config
+      ActionController::Routing::Routes.stub :add_named_route
+    end
+
+    it 'creates a Config object' do
+      ActsAsDashboard::Config.should_receive(:new).and_return @config
+
+      class DashboardsController < ApplicationController
+        acts_as_dashboard
+      end
+    end
+
+    it 'includes ActsAsDashboard::InstanceMethods' do
+      class DashboardsController < ApplicationController
+        acts_as_dashboard
+      end
+
+      DashboardsController.included_modules.should include ActsAsDashboard::InstanceMethods
+    end
+
+    it %Q(adds a named route for the dashboard's "show" action) do
+      ActionController::Routing::Routes.should_receive(:add_named_route).with(
+        'dashboard',
+        'dashboard',
+        :controller => :dashboards,
+        :action     => :show
+      )
+
+      class DashboardsController < ApplicationController
+        acts_as_dashboard
+      end
+    end
+
+    it %Q(adds a named route for the dashboard's "widget_data" action) do
+      ActionController::Routing::Routes.should_receive :add_named_route
+      ActionController::Routing::Routes.should_receive(:add_named_route).with(
+        'dashboard_widgets',
+        'dashboard/widgets/*path',
+        :controller => :dashboards,
+        :action     => :widget_data
+      )
+
+      class DashboardsController < ApplicationController
+        acts_as_dashboard
+      end
+    end
+  end # }}}
+
+  describe '#dashboard_number' do # {{{
+    def call_dashboard_number
+      DashboardsController.instance_eval do
+        dashboard_number {}
+      end
+    end
+
+    before :each do
+      class DashboardsController < ApplicationController
+        acts_as_dashboard
+      end
+
+      @widget = ActsAsDashboard::Widget.new :type => :number
+
+      @widget.stub(:instance_eval)
+      ActsAsDashboard::Widget.stub(:new).and_return @widget
+    end
+
+    it "raises an error if a Proc isn't provided" do
+      Proc.new {
+        class DashboardsController
+          dashboard_number
+        end
+      }.should raise_error ArgumentError, 'A Proc must be given.'
+    end
+
+    it 'creates a "number" Widget' do
+      ActsAsDashboard::Widget.should_receive(:new).with(:type => :number).and_return @widget
+      call_dashboard_number
+    end
+
+    it 'evaluates the given Proc within the widget' do
+      @widget.should_receive :instance_eval
+      call_dashboard_number
+    end
+
+    it 'adds the widget to its configuration' do
+      DashboardsController.dashboard_config.should_receive(:add_widget).with(@widget).and_return [@widget]
+      call_dashboard_number
+    end
+  end # }}}
+
+  describe '#dashboard_short_messages' do # {{{
+    def call_dashboard_short_messages
+      DashboardsController.instance_eval do
+        dashboard_short_messages {}
+      end
+    end
+
+    before :each do
+      class DashboardsController < ApplicationController
+        acts_as_dashboard
+      end
+
+      @widget = ActsAsDashboard::ShortMessagesWidget.new
+
+      @widget.stub(:instance_eval)
+      ActsAsDashboard::ShortMessagesWidget.stub(:new).and_return @widget
+    end
+
+    it "raises an error if a Proc isn't provided" do
+      Proc.new {
+        class DashboardsController
+          dashboard_short_messages
+        end
+      }.should raise_error ArgumentError, 'A Proc must be given.'
+    end
+
+    it 'creates a "short messages" Widget' do
+      ActsAsDashboard::ShortMessagesWidget.should_receive(:new).with(no_args).and_return @widget
+      call_dashboard_short_messages
+    end
+
+    it 'evaluates the given Proc within the widget' do
+      @widget.should_receive :instance_eval
+      call_dashboard_short_messages
+    end
+
+    it 'adds the widget to its configuration' do
+      DashboardsController.dashboard_config.should_receive(:add_widget).with(@widget).and_return [@widget]
+      call_dashboard_short_messages
+    end
+  end # }}}
+
+  describe '#dashboard_line_graph' do # {{{
+    def call_dashboard_line_graph
+      DashboardsController.instance_eval do
+        dashboard_line_graph {}
+      end
+    end
+
+    before :each do
+      class DashboardsController < ApplicationController
+        acts_as_dashboard
+      end
+
+      @widget = ActsAsDashboard::LineGraphWidget.new
+
+      @widget.stub(:instance_eval)
+      ActsAsDashboard::LineGraphWidget.stub(:new).and_return @widget
+    end
+
+    it "raises an error if a Proc isn't provided" do
+      Proc.new {
+        class DashboardsController
+          dashboard_line_graph
+        end
+      }.should raise_error ArgumentError, 'A Proc must be given.'
+    end
+
+    it 'creates a Line Graph Widget' do
+      ActsAsDashboard::LineGraphWidget.should_receive(:new).with(no_args).and_return @widget
+      call_dashboard_line_graph
+    end
+
+    it 'evaluates the given Proc within the widget' do
+      @widget.should_receive :instance_eval
+      call_dashboard_line_graph
+    end
+
+    it 'adds the widget to its configuration' do
+      DashboardsController.dashboard_config.should_receive(:add_widget).with(@widget).and_return [@widget]
+      call_dashboard_line_graph
+    end
+  end # }}}
+end

data/spec/acts_as_dashboard/config_spec.rb

@@ -0,0 +1,57 @@
+require File.join File.dirname(__FILE__), '..', 'spec_helper'
+
+describe ActsAsDashboard::Config do
+  describe 'initialization' do # {{{
+    it 'creates an array of widgets' do
+      config = ActsAsDashboard::Config.new
+      config.instance_variable_get(:@widgets).should == []
+    end
+  end # }}}
+
+  describe 'attributes' do # {{{
+    it 'returns the "widgets" attribute' do
+      config = ActsAsDashboard::Config.new
+      config.widgets.should equal config.instance_variable_get(:@widgets)
+    end
+  end # }}}
+
+  describe 'adding a widget' do # {{{
+    before :each do
+      @config = ActsAsDashboard::Config.new
+    end
+
+    it 'raises an exception if given an invalid value' do
+      Proc.new {@config.add_widget nil}.should raise_error ArgumentError,
+        'The "widget" argument must be an ActsAsDashboard::Widget.'
+    end
+
+    it 'is successful when given an ActsAsDashboard::Widget' do
+      widget = ActsAsDashboard::Widget.new
+
+      @config.widgets.should == []
+      @config.add_widget widget
+      @config.widgets.should == [widget]
+    end
+  end # }}}
+
+  describe 'finding a widget' do # {{{
+    before :each do
+      @config = ActsAsDashboard::Config.new
+    end
+
+    it 'raises an exception if given an invalid value' do
+      Proc.new {@config.find_widget nil}.should raise_error ArgumentError,
+        'The "name" argument must respond to #to_sym .'
+    end
+
+    it 'returns the widget with the given name' do
+      foo_widget = ActsAsDashboard::Widget.new :name => :foo
+      bar_widget = ActsAsDashboard::Widget.new :name => :bar
+
+      @config.add_widget foo_widget
+      @config.add_widget bar_widget
+
+      @config.find_widget(foo_widget.name).should equal foo_widget
+    end
+  end # }}}
+end

data/spec/acts_as_dashboard/instance_methods_spec.rb

@@ -0,0 +1,134 @@
+require File.join File.dirname(__FILE__), '..', 'spec_helper'
+
+class DashboardsController < ApplicationController
+  acts_as_dashboard
+end
+
+describe ActsAsDashboard::InstanceMethods do
+  it 'creates the "show" action for the controller' do
+    DashboardsController.action_methods.should include 'show'
+  end
+end
+
+describe DashboardsController, :type => :controller do
+  describe 'GET "show"' do # {{{
+    before :each do
+      @widget_attributes  = {:name => :some_name, :title => 'Some Title', :update_interval => '10s', :type => :number}
+      @json               = '[{"type":"number","title":"Some Title","name":"some_name","update_interval":"10s"}]'
+      @widget             = mock ActsAsDashboard::Widget, :attributes => @widget_attributes
+      @config             = mock ActsAsDashboard::Config, :widgets => [@widget]
+
+      controller.stub(:dashboard_config).and_return @config
+      controller.stub(:render)
+    end
+
+    it 'grabs the dashboard config' do
+      controller.should_receive(:dashboard_config).and_return @config
+      get :show
+    end
+
+    it "grabs each widget's attributes" do
+      @widget.should_receive(:attributes).and_return @widget_attributes
+      get :show
+    end
+
+    it "converts each widget's attributes to JSON" do
+      @widget_attributes.should_receive(:to_json).and_return @json
+      get :show
+    end
+
+    it 'assigns @json_widgets as a String of widget attributes in JSON' do
+      get :show
+      assigns[:json_widgets].should == @json
+    end
+
+    it 'assigns @dashboard_css_path as the path to the CSS script' do
+      get :show
+
+      assigns[:dashboard_css_path].should == File.expand_path(File.join(
+        File.dirname(__FILE__), '..', '..', 'lib', 'acts_as_dashboard', 'public', 'stylesheets', 'dashboard.css'
+      ))
+    end
+
+    it 'assigns @dashboard_css as the CSS for the dashboard' do
+      get :show
+
+      css_file = File.join File.dirname(__FILE__), '..', '..', 'lib', 'acts_as_dashboard', 'public', 'stylesheets', 'dashboard.css'
+      assigns[:dashboard_css].should == File.open(css_file).read
+    end
+
+    it 'assigns @dashboard_js_path as the path to the JavaScript script' do
+      get :show
+
+      assigns[:dashboard_js_path].should == File.expand_path(File.join(
+        File.dirname(__FILE__), '..', '..', 'lib', 'acts_as_dashboard', 'public', 'javascripts', 'dashboard.js'
+      ))
+    end
+
+    it 'assigns @dashboard_js_path as the JavaScript for the dashboard' do
+      get :show
+
+      js_file = File.join File.dirname(__FILE__), '..', '..', 'lib', 'acts_as_dashboard', 'public', 'javascripts', 'dashboard.js'
+      assigns[:dashboard_js].should == File.open(js_file).read
+    end
+
+    it 'renders the "show" view template within the gem' do
+      path_to_gem   = File.expand_path File.dirname(__FILE__) + '/../../'
+      path_to_view  = "#{path_to_gem}/lib/acts_as_dashboard/app/views/dashboards/show.html.erb"
+
+      controller.should_receive(:render).with(:file => path_to_view)
+      get :show
+    end
+  end # }}}
+
+  describe 'GET /widget/returns_ten' do # {{{
+    before :each do
+      @widget_name  = 'returns_ten'
+      @block        = Proc.new {10}
+      @widget       = mock ActsAsDashboard::Widget, :block => @block
+      @config       = mock ActsAsDashboard::Config, :find_widget => @widget
+      @params       = {:path => [@widget_name]}
+
+      controller.stub(:dashboard_config).and_return @config
+      controller.stub(:render)
+    end
+
+    describe 'when the widget exists' do # {{{
+      it 'finds the requested widget' do
+        @config.should_receive(:find_widget).with(@widget_name.to_s).and_return @widget
+        get :widget_data, @params
+      end
+
+      it "calls the widget's block" do
+        @block.should_receive(:call).with(no_args).and_return 10
+        get :widget_data, @params
+      end
+
+      it "renders the output from the widget's block as text" do
+        controller.should_receive(:render).with(:text => 10)
+        get :widget_data, @params
+      end
+    end # }}}
+
+    describe "when the widget doesn't exist" do # {{{
+      before :each do
+        @config.stub(:find_widget).and_return nil
+      end
+
+      it 'fails to find the widget' do
+        @config.should_receive(:find_widget).and_return nil
+
+        begin
+          get :widget_data, @params
+        rescue ActsAsDashboard::WidgetNotFound => e
+        end
+      end
+
+      it 'raises an ActsAsDashboard::WidgetNotFound error' do
+        Proc.new {
+          get :widget_data, @params
+        }.should raise_error ActsAsDashboard::WidgetNotFound, 'No widget named "returns_ten" found.'
+      end
+    end # }}}
+  end # }}}
+end

data/spec/acts_as_dashboard/line_graph_widget_spec.rb

@@ -0,0 +1,165 @@
+require File.join File.dirname(__FILE__), '..', 'spec_helper'
+require File.join File.dirname(__FILE__), '..', 'shared', 'widget_behaviours'
+
+describe ActsAsDashboard::LineGraphWidget do
+  it_should_behave_like 'an ActsAsDashboard Widget'
+
+  describe 'initialization' do # {{{
+    before :each do
+      @options = {
+        :width          => '400px',
+        :height         => '200px',
+        :line_colours   =>  %w(#4bb2c5 #c5b47f),
+        :x_axis         => :dates,
+      }
+    end
+
+    it 'removes the :type element from the given options' do
+      options = {:type => :something}
+      options.should_receive(:delete).with :type
+
+      widget = ActsAsDashboard::LineGraphWidget.new options
+    end
+
+    it 'sets its type to :line_graph' do
+      widget = ActsAsDashboard::LineGraphWidget.new
+      widget.type.should equal :line_graph
+    end
+
+    it 'sets its height to the given value' do
+      widget = ActsAsDashboard::LineGraphWidget.new :height => @options[:height]
+      widget.height.should == @options[:height]
+    end
+
+    it 'sets its height to the default value if no value is given' do
+      widget = ActsAsDashboard::LineGraphWidget.new
+      widget.height.should == ActsAsDashboard::LineGraphWidget.send(:class_variable_get, :@@default_height)
+    end
+
+    it 'sets its width to the given value' do
+      widget = ActsAsDashboard::LineGraphWidget.new :width => @options[:width]
+      widget.width.should == @options[:width]
+    end
+
+    it 'sets its width to the default value if no value is given' do
+      widget = ActsAsDashboard::LineGraphWidget.new
+      widget.width.should == ActsAsDashboard::LineGraphWidget.send(:class_variable_get, :@@default_width)
+    end
+
+    it 'sets its line colours to the given value' do
+      widget = ActsAsDashboard::LineGraphWidget.new :line_colours => @options[:line_colours]
+      widget.line_colours.should == @options[:line_colours]
+    end
+
+    describe 'when given the "line_colors" (American spelling) option' do # {{{
+      it 'copies the value to "line_colours"' do
+        options = {:line_colors => @options[:line_colours]}
+        widget = ActsAsDashboard::LineGraphWidget.new options
+        options[:line_colours].should equal @options[:line_colours]
+      end
+
+      it 'deletes the "line_colors" option' do
+        options = {:line_colors => @options[:line_colours]}
+        widget = ActsAsDashboard::LineGraphWidget.new options
+        options.should_not have_key :line_colors
+      end
+
+      it 'uses the value of "line_colors" as "line_colours"' do
+        widget = ActsAsDashboard::LineGraphWidget.new :line_colors => @options[:line_colours]
+        widget.line_colours.should == @options[:line_colours]
+      end
+    end # }}}
+
+    it 'sets its x-axis to the given value' do
+      widget = ActsAsDashboard::LineGraphWidget.new :x_axis => @options[:x_axis]
+      widget.x_axis.should == @options[:x_axis]
+    end
+
+    it 'sets its x-axis to the default value if no value is given' do
+      widget = ActsAsDashboard::LineGraphWidget.new
+      widget.x_axis.should == ActsAsDashboard::LineGraphWidget.send(:class_variable_get, :@@default_x_axis)
+    end
+  end # }}}
+
+  describe 'setting its "x_axis" attribute' do # {{{
+    it 'raises an error when given an invalid value' do
+      Proc.new {ActsAsDashboard::LineGraphWidget.new :x_axis => 'asdf'}.should raise_error ArgumentError,
+        'The "x_axis" argument must be one of the following symbols: dates, numbers'
+    end
+
+    it 'is successful when given :dates' do
+      widget = ActsAsDashboard::LineGraphWidget.new :x_axis => :dates
+      widget.x_axis.should equal :dates
+    end
+
+    it 'is successful when given :numbers' do
+      widget = ActsAsDashboard::LineGraphWidget.new :x_axis => :numbers
+      widget.x_axis.should equal :numbers
+    end
+  end # }}}
+
+  describe 'setting its "line_colours" attribute' do # {{{
+    it 'raises an error when not given an Array' do
+      Proc.new {ActsAsDashboard::LineGraphWidget.new.line_colours = 'fail'}.should raise_error ArgumentError,
+        'The "line_colours" argument must be an Array of Strings.'
+    end
+
+    it 'raises an error when not given an Array of Strings' do
+      Proc.new {ActsAsDashboard::LineGraphWidget.new.line_colours = [1]}.should raise_error ArgumentError,
+        'The "line_colours" argument must be an Array of Strings.'
+    end
+
+    it 'is successful when given an Array of Strings' do
+      line_colours    = %w(#4bb2c5 #c5b47f)
+      w                 = ActsAsDashboard::LineGraphWidget.new
+      w.line_colours  = line_colours
+
+      w.instance_variable_get(:@line_colours).should == line_colours
+    end
+  end # }}}
+
+  describe 'attributes' do # {{{
+    before :each do
+      @options = {
+        :name             => :some_counter,
+        :title            => 'Some Counter',
+        :block            => Proc.new {123},
+        :update_interval  => '10s',
+        :height           => '100px',
+        :width            => '200px',
+        :line_colours     => %w(#4bb2c5 #c5b47f),
+        :x_axis           => :dates,
+      }
+
+      @widget = ActsAsDashboard::LineGraphWidget.new @options
+    end
+
+    it 'are returned in a Hash' do
+      @options.delete :block    # Remove the "block" key because AAD::Widget#attributes doesn't return it on purpose.
+
+      @widget.attributes.should == @options.merge(:type => :line_graph)
+    end
+
+    it 'returns the "height" attribute' do
+      @widget.height.should equal @options[:height]
+    end
+
+    it 'returns the "width" attribute' do
+      @widget.width.should equal @options[:width]
+    end
+
+    it 'returns the "line_colours" attribute' do
+      @widget.line_colours.should equal @options[:line_colours]
+    end
+
+    describe 'when given the "line_colors" (American spelling) option' do # {{{
+      it 'returns the "line_colours" attribute' do
+        @widget.line_colors.should equal @options[:line_colours]
+      end
+    end # }}}
+
+    it 'returns the "x_axis" attribute' do
+      @widget.x_axis.should equal @options[:x_axis]
+    end
+  end # }}}
+end