scheduled_resource 0.0.1

data/lib/scheduled_resource.rb

@@ -0,0 +1,262 @@
+# scheduled_resource.rb
+# Copyright (c) 2008-2015 Mike Cannon (michael.j.cannon@gmail.com)
+#   (http://github.com/emeyekayee/scheduled_resource)
+# MIT License.
+#
+
+require 'scheduled_resource/version'
+require 'scheduled_resource/resource_use_block'
+require 'scheduled_resource/helper'
+
+require 'z_time_header'
+require 'z_time_header_day'
+require 'z_time_header_hour'
+require 'z_time_label'
+require 'z_time_label_day'
+require 'z_time_label_hour'
+
+# A "scheduled resource" is something that can be used for one thing at a time.
+#
+# Example: A Room (resource) is scheduled for a meeting (resource use block)
+# titled "Weekly Staff Meeting" tomorrow from 9am to 11am.
+#
+# Class SchedResource manages class names, id's and labels for a
+# schedule.  An instance ties together:
+#
+#  1. A resource class (eg Room),
+#  2. An id, and
+#  3. Strings / html snippets (eg, label, title) for the DOM.
+#
+# The id (2 above) is used to
+#
+# a) select a resource <em>instance</em> and
+#
+# b) select instances of the <em>resource use block</em> class (eg Meeting).
+#
+# The id <em>may</em> be a database id but need not be.
+# It is used by class methods
+# <tt>get_all_blocks()</tt> of model use-block classes.
+# Not tying this to a database id allows a little extra flexibility in
+# configuration.
+#
+# Items 1 and 2 are are combined (with a '_') to form "tags" (ids) for the DOM.
+#
+# See also:              ResourceUseBlock.
+#
+#--
+# Config is loaded from config/schedule.yml:
+# all_resources::      Resources in display order.
+# rsrcs_by_kind::      A hash with resources grouped by kind (resource class).
+# rsrc_of_tag::        Indexed by text tag: kind_subid.
+# \visible_time::       Span of time window.
+#++
+#
+# When queried with an array of ids and a time interval, the class
+# method <tt>get_all_blocks(ids, t1, t2)</tt> of a <em>resource use</em>
+# model returns a list of "use blocks", each with a starttime, endtime
+# and descriptions of that use.
+#
+# This method invokes that method on each of the <em>resource use</em>
+# classes.  It returns a hash where:
+#   Key     is a Resource (rsrc);
+#   Value   is an array of use-block instances (rubs).
+#
+class ScheduledResource
+
+  CONFIG_FILE = "config/resource_schedule.yml"
+
+  class_attribute :config
+
+  # (SchedResource protocol) Returns a hash where each key is an
+  # <tt>rid</tt> and the value is an array of resource use
+  # blocks in the interval <tt>t1...t2</tt>, ordered by
+  # <tt>starttime</tt>.
+  #
+  # What <em>in</em> means depends on <em>inc</em>.  If inc(remental) is 
+  # false, the client is building the interval from scratch.  If "hi", it is
+  # an addition to an existing interval on the high side.  Similarly
+  # for "lo".  This is to avoid re-transmitting blocks that span the
+  # current time boundaries on the client.
+  #
+  # Here the resource is a channel and the use blocks are programs.
+  # 
+  # ==== Parameters
+  # * <tt>rids</tt> - A list of schedules resource ids (strings).
+  # * <tt>t1</tt>   - Start time.
+  # * <tt>t2</tt>   - End time.
+  # * <tt>inc</tt>  - One of nil, "lo", "hi" (See above).
+  #
+  # ==== Returns
+  # * <tt>Hash</tt> - Each key is an <tt>rid</tt> and the value is an array of resource use blocks in the interval, ordered by <tt>starttime</tt>.
+  def self.get_all_blocks(t1, t2, inc)
+    blockss = {}
+
+    config[:rsrcs_by_kind].each do |kind, rsrcs|
+      rub_class = block_class_for_resource_name kind
+      rids      = rsrcs.map{ |r| r.sub_id }
+      ru_blkss  = rub_class.get_all_blocks rids, t1, t2, inc
+
+      add_rubs_of_kind kind, ru_blkss, blockss
+    end
+
+    blockss
+  end
+
+  
+  # ==== Parameters
+  # * <tt>name</tt>  - The class name (string) of a schedule resource.
+  #
+  # ==== Returns
+  # * <tt>Class</tt> - The class representing the <em>use</em> of that resource for an interval of time.
+  def self.block_class_for_resource_name( name )
+    config[:block_class_for_resource_kind][name]
+  end
+
+
+  # ==== Returns
+  # * <tt>Array[SchedResource]</tt> - List of all configured SchedResources .
+  def self.resource_list; config[:all_resources] end
+
+  # ==== Returns
+  # * <tt>Time</tt> - The configured width of the visible time window.
+  def self.visible_time;  config[:visible_time] end
+
+
+  #--
+  # Restore configuration from session.
+  #
+  # When we depend on data in the configuration to satisfy a query we are not
+  # being RESTful.  On the other hand we are not maintaining changeable state
+  # here -- it's just a cache.  If there <em>were</em> changeable state it
+  # would likely be kept, eg, in a per-user table in the database.
+  #++
+  def self.ensure_config( session ) # :nodoc:
+    return if (self.config ||= session[:schedule_config])
+
+    config_from_yaml( session )
+  end
+
+
+  # ToDo: Generalize this so configuration can be loaded on per-user.
+  # Process configuration file.
+  def self.config_from_yaml( session )
+    config_from_yaml1
+    config_from_yaml2 session
+    config
+  end
+
+
+  private
+  # A caching one-of-each-sort constructor.
+  #
+  # ==== Parameters
+  # * <tt>kind</tt>   - Class name (string) of a scheduled resource.
+  # * <tt>sub_id</tt> - Id (string), selecting a resource instance.  The two are combined and used as a unique tag in the DOM as id and class attributes as well as in server code.
+  def self.get_for( kind, sub_id )
+    tag = compose_tag( kind, sub_id )
+    config[:rsrc_of_tag][ tag ] || self.new( kind, sub_id )
+  end
+
+  def self.compose_tag( kind, sub_id ); "#{kind}_#{sub_id}" end
+
+  def self.config_from_yaml1()
+    self.config = { all_resources: [],
+                    rsrc_of_tag: {},
+                    block_class_for_resource_kind: {}
+                   }
+    yml = YAML.load_file CONFIG_FILE
+
+    yml['ResourceKinds'].each do |key, val| # {"Channel" => <#Class Program>...}
+      config[:block_class_for_resource_kind][key] = eval val
+    end
+
+    if (rkls = yml['Resources'])        # Resource Kind Lists, eg
+      rkls.each do |rkl|                # ["TimeheaderHour", "Hour0"]
+        rkl = rkl.split(/[, ]+/)        # ["Channel",    "702", "703",... ]
+        rk  = rkl.shift
+        add_resources rkl.map{ |sub_id| make_resource_of_kind(rk, sub_id) }
+      end
+    end
+
+    vt = yml['visibleTime']
+    config[:visible_time]   = vt ? (eval vt) : 3.hours
+
+    t0 = yml['timeRangeMin']
+    config[:time_range_min] = t0 ? (eval t0) : (Time.now - 1.week)
+
+    tn = yml['timeRangeMax']
+    config[:time_range_max] = tn ? (eval tn) : (Time.now - 1.week)
+
+    config
+  end
+
+  
+  def self.add_resources(rsrcs)
+    rs = config[:all_resources]
+    rsrcs.each{ |rsrc| rs.include?( rsrc ) || rs << rsrc }
+  end
+
+
+  def self.config_from_yaml2( session )
+    config[:rsrcs_by_kind] = resource_list.group_by{ |r| r.kind }
+
+    config[:rsrcs_by_kind].each do |kind, rsrcs|
+      klass = kind.constantize
+      rsrcs.each {|rsrc| klass.decorate_resource rsrc }
+    end
+
+    session[:schedule_config] = config
+  end
+
+  def self.make_resource_of_kind( klass, rid )
+    klass = eval klass if klass.class == String
+    get_for( klass.name, rid )
+  end
+
+  def self.add_rubs_of_kind( kind, ru_blkss, blockss )
+    ru_blkss.each do |rid, blks|
+      rsrc = get_for( kind, rid )
+      rubs = blks.map{ |blk| ResourceUseBlock.new rsrc, blk }
+      blockss[ rsrc ] = rubs
+    end
+  end
+
+
+  public
+
+  # Instance methods
+  def initialize( kind, sub_id ) # :nodoc:
+    @tag = self.class.send( :compose_tag, kind, sub_id )
+    @label = @title = nil
+    config[:rsrc_of_tag][@tag] = self
+  end
+
+  # ==== Returns
+  # * <tt>String</tt> - The class name of the scheduled resource.
+  def kind()    @tag.sub( /_.*/, '' )          end
+
+  # ==== Returns
+  # * <tt>String</tt> - The <tt>rid</tt> (abstract id) of the SchedResource.
+  def sub_id()  @tag.sub( /.*_/, '' )          end
+
+  def to_s() # :nodoc:
+    @tag
+  end 
+
+  def inspect() # :nodoc:
+    "<#SchedResource \"#{@tag}\">"
+  end 
+
+  attr_accessor :label, :title
+  def label();     @label || @tag end
+
+  def label=(val)
+    @label = val
+  end
+
+  def title();     @title || @tag end
+
+  # ==== Returns
+  # * <tt>String</tt> - CSS classes automatically generated for the DOM row representing this SchedResource.
+  def css_classes_for_row(); "rsrcRow #{self.kind}row #{@tag}row #{self.kind}Row #{@tag}Row" end # Row + row -- really?
+end

data/lib/scheduled_resource/helper.rb

@@ -0,0 +1,65 @@
+# Using ScheduledResource as a module here for namespacing (in transition).
+class ScheduledResource
+
+  module Helper
+
+    def ensure_schedule_config
+      meth = params[:reset] ? :config_from_yaml : :ensure_config
+      ScheduledResource.send( meth, session )
+    end
+
+    def default_time_param
+      t_now = Time.now
+      t_now.change :min => (t_now.min/15) * 15
+    end
+
+    def set_schedule_query_params(p = params)
+      @t1 = p[:t1] || default_time_param
+      @t2 = p[:t2] || @t1 + ScheduledResource.visible_time
+      @inc= p[:inc]
+    end
+
+    # Set up instance variables for render templates or returned json
+    #  params:  @t1:      time-inverval start
+    #           @t2:      time-inverval end
+    #           @inc:     incremental update?  One of: nil, 'lo', 'hi'
+    #
+    #  creates: @rsrcs    ordered resource list
+    #           @blockss: lists of use-blocks, keyed by resource
+    def get_data_for_time_span()
+      set_schedule_query_params
+
+      @t1 = Time.at(@t1.to_i)
+      @t2 = Time.at(@t2.to_i)
+
+      @rsrcs = ScheduledResource.resource_list
+
+      @blockss = ScheduledResource.get_all_blocks(@t1, @t2, @inc)
+
+      json_adjustments
+    end
+
+    def min_time;  ScheduledResource.config[:time_range_min].to_i end
+    def max_time;  ScheduledResource.config[:time_range_max].to_i end
+
+    # Always send starttime/endtime attributes as Integer values (UTC) -- they are
+    # used to size and place the blocks.  Timezone is configured separately in the
+    # ZTime* classes (config/resource_schedule.yml).
+    def json_adjustments
+      @blockss.each do |rsrc, blocks|
+        blocks.each do |block|
+          block.starttime =  block.starttime.to_i
+          block.endtime   =  block.endtime.to_i
+        end
+      end
+      @blockss['meta'] = {
+        rsrcs: @rsrcs, min_time: min_time, max_time: max_time,
+        t1: @t1.to_i, t2: @t2.to_i, inc: @inc,
+      }
+    end
+
+
+
+  end
+
+end

data/lib/scheduled_resource/resource_use_block.rb

@@ -0,0 +1,33 @@
+# Using ScheduledResource as a module here for namespacing (in transition).
+class ScheduledResource
+
+  #                       ResourceUseBlock
+  #
+  # Represents the USE of a resource for an interval of time.
+  #
+  #  Resource X UseModel X [startime..endtime];
+  #   |         | Example -- tv:
+  #   |         |   Program   [ belongs_to :channel    ]
+  #   |         |   Timelabel [ belongs_to :timeheader ]
+  #   |
+  #   | Example -- tv: Channel, TimeHeader
+  #
+  class ResourceUseBlock
+
+    delegate  :kind,      :to => :@rsrc
+
+    delegate  :starttime=, :endtime=,  
+                        :starttime,  :endtime,
+              # No longer used by view templates...
+              #  :title,      :subtitle, :description,     :stars,
+              #  :airdate,    :category, :previouslyshown,
+              :to => :@blk
+
+    def initialize(rsrc, blk)
+      @rsrc = rsrc
+      @blk = blk
+    end
+
+  end
+
+end

data/lib/scheduled_resource/version.rb

@@ -0,0 +1,3 @@
+class ScheduledResource
+  VERSION = "0.0.1"
+end

data/lib/z_time_header.rb

@@ -0,0 +1,20 @@
+# This is a base for ScheduledResource classes (see below) for timezone-aware time
+# headers.  The timezone is specified by the last component of the resource id
+# (rid).  Eg, for 'Day_-8' the timezone is ActiveSupport::TimeZone.new(-8)
+
+
+class ZTimeHeader
+
+  # (For ScheduledResource protocol)  This method lets us set display attributes
+  # on the instance in a way specific to the resource-class and rid.
+  # 
+  # ==== Parameters
+  # * <tt>rsrc</tt> - A ScheduledResource instance. 
+  def self.decorate_resource( rsrc )
+    rid = rsrc.sub_id
+
+    rsrc.label = 'Time'   # Overridden, presumably
+    rsrc.title = rid
+  end
+
+end

data/lib/z_time_header_day.rb

@@ -0,0 +1,16 @@
+
+class ZTimeHeaderDay < ZTimeHeader
+
+  # (For ScheduledResource protocol)  This method lets us set display attributes
+  # on the instance in a way specific to the resource-class and rid.
+  # 
+  # ==== Parameters
+  # * <tt>rsrc</tt> - A ScheduledResource instance. 
+  def self.decorate_resource( rsrc )
+    rid = rsrc.sub_id
+
+    rsrc.label = "Day"
+    rsrc.title = rid
+  end
+
+end

data/lib/z_time_header_hour.rb

@@ -0,0 +1,15 @@
+class ZTimeHeaderHour < ZTimeHeader
+
+  # (For ScheduledResource protocol)  This method lets us set display attributes
+  # on the instance in a way specific to the resource-class and rid.
+  # 
+  # ==== Parameters
+  # * <tt>rsrc</tt> - A ScheduledResource instance. 
+  def self.decorate_resource( rsrc )
+    rid = rsrc.sub_id
+
+    rsrc.label = "Hour"
+    rsrc.title = rid
+  end
+
+end

data/lib/z_time_label.rb

@@ -0,0 +1,88 @@
+# For ScheduledResource protocol.  This is a base UseBlock class for ZTimeHeader
+# use-block subclasses.  These are timezone-aware time headers (rows) and labels
+# (use-blocks).  The timezone is specified by the last component of the resource
+# id (rid).  Eg, for '-8' the timezone is ActiveSupport::TimeZone.new(-8)
+
+class ZTimeLabel
+  attr_accessor :starttime, :endtime, :css_classes, :title
+
+  class_attribute :label, :format, :t_block # t_block (if used) set by subclass
+
+  # Parameters are TimeWithZone or similar
+  def initialize( starttime, endtime )
+    @starttime, @endtime = starttime, endtime
+  end
+
+
+  # (ScheduledResource protocol) Returns a hash where each key is an
+  # <tt>rid</tt> and the value is an array of ZTimeLabels (use
+  # blocks) in the interval <tt>t1...t2</tt>, ordered by
+  # <tt>starttime</tt>.
+  #
+  # What <em>in</em> means depends on *inc*.  If inc(remental) is
+  # nil/false, client is building the interval from scratch.  If "hi", it is
+  # an addition to an existing interval on the high side.  Similarly
+  # for "lo".  This is to avoid re-transmitting blocks that span the
+  # current time boundaries on the client.
+  #
+  # Here the resource is a ZTimeHeader and the use-blocks are ZTimeLabels.
+  #
+  # ==== Parameters
+  # * <tt>rids</tt> - A list of schedules resource ids (strings).
+  # * <tt>t1</tt>   - Start time.
+  # * <tt>t2</tt>   - End time.
+  # * <tt>inc</tt>  - One of nil, "lo", "hi" (See above).
+  #
+  # ==== Returns
+  # * <tt>Hash</tt> - Each key is a <tt>rid</tt> such as Hour0
+  # and the value is an array of Timelabels in the interval, ordered by
+  # <tt>starttime</tt>.
+  def self.get_all_blocks(ids, t1, t2, inc)
+    h = {}
+    ids.each{|id| h[id] = get_timeblocks(id, t1, t2, inc)}
+    h
+  end
+
+
+  def self.get_timeblocks(id, t1, t2, inc)
+    tz = tz_from_rid( id )
+    
+    t1 = floor( tz.at(t1) )
+    t1 = end_for_start(t1)  if inc == 'hi'
+
+    t2 = tz.at(t2)
+    t2 = floor( t2 ) - 1    if inc == 'lo'
+
+    enum_for( :time_blocks_starting_through, t1, t2 ).to_a
+  end
+
+ 
+  def self.time_blocks_starting_through( starttime, limit )
+    while starttime <= limit do  # Hmm... I would have guessed '<' over '<='...
+      endtime = end_for_start starttime
+      yield new( starttime, endtime )
+      starttime = endtime
+    end
+  end
+
+
+  TZ_INT_MAP = {
+    -8 => ActiveSupport::TimeZone.new('Pacific Time (US & Canada)' ), # P
+    -7 => ActiveSupport::TimeZone.new('Mountain Time (US & Canada)'), # M
+    -6 => ActiveSupport::TimeZone.new('Central Time (US & Canada)' ), # C
+    -5 => ActiveSupport::TimeZone.new('Eastern Time (US & Canada)' ), # E
+                }
+
+  def self.tz_from_rid( rid )
+    # ActiveSupport::TimeZone.new offset_from_rid(rid)
+    TZ_INT_MAP[ offset_from_rid(rid) ] || TZ_INT_MAP[-8]
+  end
+
+  def self.offset_from_rid( rid )
+    (rid.split('_').last || '').to_i
+  end
+
+  def self.end_for_start(t) t + 1 end  # Overridden.
+  def self.floor(t)         t     end  # Overridden.
+
+end