event_calendar 0.0.0 → 0.0.1

data/README.rdoc

@@ -1,17 +1,43 @@
 = event_calendar
 
-Generates HTML event calendars with ruby
+Generates HTML event calendars
 
-INCOMPLETE
 
 == Installation
 
-  gem install event_calendar --source http://gemcutter.org
+  gem install event_calendar
+
 
 == Usage
 
-  @calendar = Calendar.new(2009, 10, :events => Event.all)
-  puts @calendar.to_html
+=== Basic
+
+  @event_calendar = EventCalendar.new(2009, 10, :events => Event.all)
+  puts @event_calendar.to_html
+
+=== Options
+
+The <tt>EventCalendar.new</tt> method accepts a hash or block of options, for example:
+
+  @event_calendar = EventCalendar.new(2009, 10, :id => 'calendar', :events => Event.all)
+  
+  @event_calendar = EventCalendar.new(2009, 10) do |c|
+    c.id = 'calendar'
+    c.events = Event.all
+  end
+
+See the documentation for the <tt>EventCalendar</tt> class at http://rdoc.info/projects/shuber/event_calendar for a list of available options.
+
+=== Assets
+
+  rake event_calendar:generate:css      # Generates css for the event calendar
+  rake event_calendar:generate:js       # Generates js for the event calendar
+  rake event_calendar:generate:sandbox  # Creates a sandbox in the current working directory for testing
+
+==== Note
+
+The default css was built on YUI (See http://developer.yahoo.com/yui) and javascript on Prototype (See http://www.prototypejs.org).
+
 
 == Note on Patches/Pull Requests
  
@@ -24,6 +50,14 @@ INCOMPLETE
    bump version in a commit by itself I can ignore when I pull)
 * Send me a pull request. Bonus points for topic branches.
 
+
+== TODO
+
+* Break Markaby template down into sections so that it's easier to overwrite certain parts
+* Dynamic height calculations for calendar days in JavaScript
+* jQuery support
+
+
 == Copyright
 
 Copyright (c) 2009 Sean Huber. See MIT-LICENSE for details.

data/Rakefile

@@ -1,26 +1,6 @@
 require 'rubygems'
 require 'rake'
 
-begin
-  require 'jeweler'
-  Jeweler::Tasks.new do |gem|
-    gem.name = 'event_calendar'
-    gem.summary = 'Generates HTML event calendars'
-    gem.description = 'Generates HTML event calendars'
-    gem.email = 'shuber@huberry.com'
-    gem.homepage = 'http://github.com/shuber/event_calendar'
-    gem.authors = ['Sean Huber']
-    gem.add_dependency 'activesupport'
-    gem.add_dependency 'markaby'
-    gem.add_dependency 'haml'
-    gem.add_development_dependency 'shoulda'
-    gem.add_development_dependency 'timecop'
-    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
-  end
-rescue LoadError
-  puts 'Jeweler (or a dependency) not available. Install it with: sudo gem install jeweler'
-end
-
 require 'rake/testtask'
 Rake::TestTask.new(:test) do |test|
   test.libs << 'lib' << 'test'
@@ -41,20 +21,12 @@ rescue LoadError
   end
 end
 
-task :test => :check_dependencies
-
 task :default => :test
 
 require 'rake/rdoctask'
 Rake::RDocTask.new do |rdoc|
-  if File.exist?('VERSION')
-    version = File.read('VERSION')
-  else
-    version = ""
-  end
-
   rdoc.rdoc_dir = 'rdoc'
-  rdoc.title = "event_calendar #{version}"
+  rdoc.title = "event_calendar"
   rdoc.rdoc_files.include('README*')
   rdoc.rdoc_files.include('lib/**/*.rb')
 end

data/assets/javascripts/{calendar.js → event_calendar.prototype.js}

@@ -1,4 +1,4 @@
-var Calendar = Class.create({
+var EventCalendar = Class.create({
 
   options: $H({ 
     events_css_path: '.event', 
@@ -16,7 +16,7 @@ var Calendar = Class.create({
       this.add_hover_behavior_to_event(event);
     }.bind(this));
     
-    Calendar.instances.push(this);
+    EventCalendar.instances.push(this);
   },
   
   add_fields_to_event: function(event) {
@@ -52,4 +52,4 @@ var Calendar = Class.create({
   
 });
 
-Calendar.instances = [];
+EventCalendar.instances = [];

data/assets/stylesheets/{calendar.css → event_calendar.css}

@@ -1,22 +1,22 @@
-.calendar table {
+.event_calendar table {
   border-collapse: collapse;
   margin: 0;
   width: 100%; }
-  .calendar table td {
+  .event_calendar table td {
     border-bottom: 0px solid transparent !important;
     width: 14.285%; }
-.calendar .days {
+.event_calendar .days {
   position: relative; }
-  .calendar .days table.grid {
+  .event_calendar .days table.grid {
     z-index: 1; }
-  .calendar .days .events {
+  .event_calendar .days .events {
     left: 0px;
     position: absolute;
     table-layout: fixed;
     text-align: left;
     top: 0px;
     z-index: 2; }
-    .calendar .days .events td {
+    .event_calendar .days .events td {
       border-bottom-width: 0px;
       border-left-width: 0px;
       border-color: transparent;
@@ -24,47 +24,47 @@
       padding: 0;
       text-overflow: ellipsis;
       white-space: nowrap; }
-      .calendar .days .events td a {
+      .event_calendar .days .events td a {
         background-color: transparent;
         cursor: pointer;
         display: block;
         padding: 1px 3px;
         text-decoration: none; }
-      .calendar .days .events td .fields {
+      .event_calendar .days .events td .fields {
         display: none; }
-    .calendar .days .events tr.grid td {
+    .event_calendar .days .events tr.grid td {
       border-top-width: 0px;
       height: 0px; }
 
-.calendar {
+.event_calendar {
   border-bottom: 1px solid #d4d5d4; }
-  .calendar table td {
+  .event_calendar table td {
     border-color: #d4d5d4;
     border-width: 1px; }
-  .calendar .navigation td {
+  .event_calendar .navigation td {
     border-color: transparent; }
-  .calendar table.grid {
+  .event_calendar table.grid {
     background-color: #fefffe;
     height: 125px; }
-  .calendar .label {
+  .event_calendar .label {
     background-color: #ebede2;
     border-top-width: 1px;
     color: black; }
-  .calendar .header .label {
+  .event_calendar .header .label {
     background-color: #2f302f;
     color: white; }
-  .calendar .days .events td {
+  .event_calendar .days .events td {
     border-top-width: 3px; }
-    .calendar .days .events td a {
+    .event_calendar .days .events td a {
       background-color: #9aac9a;
       color: white;
       -khtml-border-radius: 5px;
       -moz-border-radius: 5px;
       -webkit-border-radius: 5px;
       border-radius: 5px; }
-    .calendar .days .events td:hover a, .calendar .days .events td.hover a {
+    .event_calendar .days .events td:hover a, .event_calendar .days .events td.hover a {
       background-color: #6f7f6f; }
-    .calendar .days .events td.continuation a {
+    .event_calendar .days .events td.continuation a {
       -khtml-border-radius-bottomleft: 0px;
       -moz-border-radius-bottomleft: 0px;
       -webkit-border-bottom-left-radius: 0px;
@@ -73,7 +73,7 @@
       -moz-border-radius-topleft: 0px;
       -webkit-border-top-left-radius: 0px;
       border-top-left-radius: 0px; }
-    .calendar .days .events td.continued a {
+    .event_calendar .days .events td.continued a {
       -khtml-border-radius-bottomright: 0px;
       -moz-border-radius-bottomright: 0px;
       -webkit-border-bottom-right-radius: 0px;

data/lib/event_calendar.rb

@@ -1,22 +1,52 @@
-require 'activesupport'
+require 'active_support'
 require 'markaby'
 require 'haml'
-require 'calendar/event'
-require 'calendar/week'
+require 'event_calendar/event'
+require 'event_calendar/week'
 
+# Adds an <tt>:events</tt> <tt>attr_accessor</tt> to the <tt>Date</tt> object.
 Date.class_eval { attr_accessor :events }
 
-class Calendar
+# Generates HTML calendars
+class EventCalendar
 
   extend ActiveSupport::Memoizable
   
   undef_method :id
   
-  attr_accessor :events, :month, :options, :year
+  attr_accessor :events, :options
+  attr_reader :month, :year
   
+  # The default options used when generating event calendars
+  #
+  #   :id                  =>  The HTML id of the generated container div for this event calendar. Defaults to 'event_calendar'.
+  #   :beginning_of_week   =>  The day number to use as the beginning of the week. For example, 0 is for Sunday, 1 is for Monday, etc.
+  #                            Defaults to 0.
+  #   :day_label *         =>  The label to use for each day. Defaults to the day number.
+  #   :event_class **      =>  The HTML class to add to each event. Defaults to nil.
+  #   :event_id **         =>  The id (object_id or database id) of an event. Defaults to :id.
+  #   :event_title **      =>  The title of an event. Defaults to :title.
+  #   :event_start **      =>  The start date or datetime of an event. Defaults to :starts_at.
+  #   :event_end **        =>  The end date or datetime of an event. Defaults to :ends_at.
+  #   :event_url **        =>  The url of an event to use as the HTML href attribute. Defaults to '#'.
+  #   :event_output **     =>  The HTML to output for an event. Defaults to a link to the :event_url using the :event_title
+  #                            as its label and title attributes.
+  #   :event_fields **     =>  The event fields to output as hidden attributes into the calendar so that they can be accessed with
+  #                            javascript. Defaults to [:id, :title, :start, :end].
+  #   :events              =>  An array of events to display in the calendar. Defaults to [].
+  #   :header_label *      =>  The label to use as the header of the calendar. Defaults to the month name and year like 'October 2009'.
+  #   :header_day_label *  =>  The label to use as the header of each day. Defaults to the abbreviated day name like 'Thu'.
+  #   :navigation_label *  =>  The label to use as the inner HTML for the navigation links. Defaults to the full month name like 'November'.
+  #   :navigation_url      =>  A proc which returns the url to use as the HTML href attribute for the previous and next month links. 
+  #                            This proc is passed a date object representing the first day of the previous or next months. Defaults to '#'.
+  #   :template            =>  A path to the Markaby template file to use when rendering the calendar. Defaults to the 'event_calendar/template.mab'
+  #                            file found in this directory.
+  #
+  # *  See the EventCalendar.evaluate_date_format_option method for possible values.
+  # ** See the Event#evaluate_option method for possible values.
   def self.default_options
     @default_options ||= {
-      :id                 => 'calendar',
+      :id                 => 'event_calendar',
       :beginning_of_week  => 0,
       :day_label          => proc { |date| date.strftime('%d').gsub(/^0/, '') },
       :event_class        => nil,
@@ -24,42 +54,81 @@ class Calendar
       :event_title        => :title,
       :event_start        => :starts_at,
       :event_end          => :ends_at,
-      :event_output       => proc { |event| "<a href=\"#\" title=\"#{event.title}\">#{event.title}</a>" },
+      :event_url          => '#',
+      :event_output       => proc { |event| "<a href=\"#{event.url}\" title=\"#{event.title}\">#{event.title}</a>" },
       :event_fields       => [:id, :title, :start, :end],
       :events             => [],
       :header_label       => '%B %Y',
       :header_day_label   => '%a',
       :navigation_label   => '%B',
       :navigation_url     => proc { |date| '#' },
-      :template           => File.join(File.dirname(__FILE__), 'calendar', 'template.mab')
+      :template           => File.join(File.dirname(__FILE__), 'event_calendar', 'template.mab')
     }
   end
   
+  # Optionally accepts a <tt>year</tt> as the first argument, a <tt>month</tt> (integer) as the second argument, and a
+  # hash of options as the third argument. It also accepts a block which it passes itself to.
+  #
+  # For example:
+  #
+  #   @event_calendar = EventCalendar.new
+  #
+  #   @event_calendar = EventCalendar.new(2009, 10, :id => 'calendar', :events => Event.all)
+  #   
+  #   @event_calendar = EventCalendar.new(2009, 10) do |c|
+  #     c.id = 'calendar'
+  #     c.events = Event.all
+  #   end
   def initialize(year = Time.now.year, month = Time.now.month, options = {})
-    self.year, self.month, self.options = year, month, self.class.default_options.merge(options)
-    self.events = self.options.delete(:events).collect { |event| Event.new(event, self.options) }.sort_by(&:start)
+    @year, @month, self.options = year, month, self.class.default_options.merge(options)
+    @events = self.options.delete(:events).collect { |event| Event.new(event, self.options) }.sort_by(&:start)
     yield self if block_given?
   end
   
+  # Returns a date object representing the first day of this <tt>EventCalendar</tt> instance's specified <tt>year</tt> and <tt>month</tt>.
   def date
     Date.civil(year, month, 1)
   end
   memoize :date
   
+  # Looks up the specified option representing a date format and returns the evaluated the result.
+  #
+  # This is used inside the <tt>Markaby</tt> template. For example, we have an option <tt>:header_label</tt> which
+  # represents the content at the top of the calendar that outputs the month name and year by default, like 
+  # "October 2009".
+  #
+  # Inside the template, we call <tt>event_calendar.evaluate_date_format_option(:header_label, event_calendar.date)</tt>.
+  #
+  # If <tt>options[:header_label]</tt> is a string, it takes <tt>event_calendar.date</tt> and calls <tt>strftime(options[:header_label])</tt>
+  # on it.
+  #
+  # If it's a symbol, it takes <tt>event_calendar.date</tt> and calls <tt>send(options[:header_label])</tt> on it.
+  #
+  # If it's a proc, it calls the proc and passes <tt>event_calendar.date</tt> to it. You can pass any number of args to this method
+  # and they'll passed to the proc.
+  #
+  # Any other value for <tt>options[:header_label]</tt> is simply returned.
   def evaluate_date_format_option(option, *args)
     value = self.send(option)
     case value
-    when String
-      args.first.strftime(value)
-    when Symbol
-      args.first.send(value)
-    when Proc
-      value.call(*args)
-    else
-      value
+      when String
+        args.first.strftime(value)
+      when Symbol
+        args.first.send(value)
+      when Proc
+        value.call(*args)
+      else
+        value
     end
   end
   
+  # Allows you to read and write options using method notation.
+  #
+  # For example:
+  #
+  #   @event_calendar = EventCalendar.new(2009, 10)
+  #   @event_calendar.template = '/path/to/some/other/template.mab'
+  #   puts @event_calendar.beginning_of_week
   def method_missing(method, *args)
     if method.to_s =~ /^([^=]+)(=?)$/ && options.has_key?($1.to_sym)
       options[$1.to_sym] = args.first unless $2.empty?
@@ -69,13 +138,30 @@ class Calendar
     end
   end
   
+  # Returns the HTML representation of this <tt>EventCalendar</tt>.
+  #
+  # aliased as <tt>to_html</tt>
   def to_s
-    date(:reload)
-    weeks(:reload)
     render
   end
   alias_method :to_html, :to_s
   
+  # Returns an array of week objects which contain date objects for every day that this calendar displays.
+  # It may contain a few days from the previous and next months.
+  #
+  # The <tt>EventCalendar::Week</tt> class inherits from <tt>Array</tt>.
+  #
+  # For example:
+  #
+  #   puts EventCalendar.new(2009, 10).weeks.inspect
+  #
+  #   # [
+  #   #   [Sun, 27 Sep 2009, Mon, 28 Sep 2009, Tue, 29 Sep 2009, Wed, 30 Sep 2009, Thu, 01 Oct 2009, Fri, 02 Oct 2009, Sat, 03 Oct 2009],
+  #   #   [Sun, 04 Oct 2009, Mon, 05 Oct 2009, Tue, 06 Oct 2009, Wed, 07 Oct 2009, Thu, 08 Oct 2009, Fri, 09 Oct 2009, Sat, 10 Oct 2009],
+  #   #   [Sun, 11 Oct 2009, Mon, 12 Oct 2009, Tue, 13 Oct 2009, Wed, 14 Oct 2009, Thu, 15 Oct 2009, Fri, 16 Oct 2009, Sat, 17 Oct 2009],
+  #   #   [Sun, 18 Oct 2009, Mon, 19 Oct 2009, Tue, 20 Oct 2009, Wed, 21 Oct 2009, Thu, 22 Oct 2009, Fri, 23 Oct 2009, Sat, 24 Oct 2009],
+  #   #   [Sun, 25 Oct 2009, Mon, 26 Oct 2009, Tue, 27 Oct 2009, Wed, 28 Oct 2009, Thu, 29 Oct 2009, Fri, 30 Oct 2009, Sat, 31 Oct 2009]
+  #   # ]
   def weeks
     days_in_month = Time.days_in_month(month, year)
     starting_day = date.beginning_of_week() -1.day + beginning_of_week.days
@@ -86,12 +172,17 @@ class Calendar
   
   protected
     
+    # Generates the HTML representation of this <tt>EventCalendar</tt>. The default implementation calls
+    # <tt>render_with_markaby</tt>.
     def render
       render_with_markaby
     end
+    memoize :render
     
+    # Reads the template file specified in <tt>options[:template]</tt> and evaluates it with <tt>Markaby</tt>,
+    # passing this <tt>EventCalendar</tt> instance as the <tt>event_calendar</tt> local variable.
     def render_with_markaby
-      Markaby::Builder.new(:calendar => self, :template => File.read(template)) { eval(template) }.to_s
+      Markaby::Builder.new(:event_calendar => self, :template => File.exists?(template) ? File.read(template) : template) { eval(template) }.to_s
     end
     
 end

data/lib/event_calendar/event.rb

@@ -0,0 +1,74 @@
+class EventCalendar
+  
+  # Provides conveniece methods for calculating dates and spans for an event. Stores the real event object for
+  # proxying all other method calls to it.
+  class Event
+    
+    undef_method :id
+    
+    attr_accessor :options
+    attr_reader :event
+    
+    # Accepts a real event object which it stores to proxy method calls to, and a hash of options obtained from the
+    # <tt>EventCalendar</tt> instance.
+    def initialize(event, options)
+      @event, @options = event, options
+    end
+    
+    # Calculates the number of days this day takes up on a calendar (rounding up).
+    # Optionally accepts <tt>week_start</tt> and <tt>week_end</tt> dates to calculate how many days an event takes
+    # up in a single week. For example, if an event started on a Friday and ended the following Wednesday, calling
+    # <tt>@event.days(the_sunday_after_the_event_starts)</tt> would return 4.
+    def days(week_start = start_date, week_end = end_date)
+      (end_date > week_end ? week_end : end_date) - (start_date < week_start ? week_start : start_date) + 1
+    end
+    
+    # Returns the end date of the event. If the event stores its end as a datetime then it is converted to a date.
+    def end_date
+      self.end.to_date
+    end
+    
+    # Returns the start date of the event. If the event stores its start as a datetime then it is converted to a date.
+    def start_date
+      start.to_date
+    end
+    
+    # Allows you to read options starting with <tt>:event_</tt> using method notation.
+    #
+    # For example: calling <tt>@event.title</tt> will return the value of <tt>@event.options[:event_title]</tt> if
+    # that option exists.
+    #
+    # All other calls are delegated to the real <tt>:event</tt> object.
+    def method_missing(method, *args)
+      option = "event_#{method}".to_sym
+      if @options.has_key?(option)
+        evaluate_option(option)
+      else
+        @event.send(method, *args)
+      end
+    end
+    
+    protected
+    
+      # Looks up the specified option returns the evaluated the result.
+      #
+      # If the value of the option is a symbol, then it calls <tt>@event.send(value)</tt>
+      #
+      # If the value of the option is a proc, then it calls the proc and passes the current <tt>Event</tt>
+      # instance as an argument.
+      #
+      # Any other value is simply returned.
+      def evaluate_option(option)
+        value = @options[option]
+        case value
+          when Symbol
+            @event.send(value)
+          when Proc
+            value.call(self)
+          else
+            value
+        end
+      end
+      
+  end
+end