elevation_event_calendar 1.0.0

data/CHANGELOG.rdoc

@@ -0,0 +1,27 @@
+== 2009-12-09 / Version 2.1
+* Added the 'use_all_day' option. If this is set to true (by default it is false), it will check for an 'all_day' boolean field when displaying an event. If it is an all day event, or the event is multiple days, then it will display as usual. Otherwise it will display without a background color bar.
+* Added a --use-all-day option to the generator
+* Note, if updating, you will need to slightly change your helper. The block parameters passed to the calendar method are now in an argument hash. (More flexible, and future changes won't have this problem.) See the example in README for more.
+    calendar event_calendar_options do |args|
+      event = args[:event]
+      ...
+    end
+* Javascript handles highlighting non-all-day events
+* Re-factored javascript to be unobtrusive
+* JQuery works the same as the Prototype version
+* Minor changes to the stylesheet as a result of the new display option
+* A helper method for displaying an event's time
+
+== 2009-11-23 / Version 2
+* Complete rewrite of the calendar's HTML generation and styling
+* Event rows are now table cells which span the desired number of columns
+* The width can be set arbitrarily, or it can be left to resize with the containing element
+* Removes the use of background images for displaying the grid
+* Increased ability to style calendar days
+* Removed legacy options, comments, and code
+* Caution, not backwards compatible with some of Version 1's options
+
+== 2009-11-11 / Version 1
+* The initial EventCalendar Rails Plugin
+* Most bugs and issues have been resolved
+* Works, but isn't as flexible as desired

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Elevation
+
+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.rdoc

@@ -0,0 +1,247 @@
+==EventCalendar
+
+Easily show multiple, overlapping events across calendar days and rows.
+
+See http://dev.elevationblog.com/2009/7/23/event-calendar-rails-plugin for a screenshot.
+
+After install, the "calendar" method will be available within your views.
+
+To customize the look, modify the included stylesheet and/or change the default options.
+
+
+==Install
+
+  script/plugin install git://github.com/elevation/event_calendar.git
+
+To generate the necessary static files AND the example below:
+
+  script/generate event_calendar
+
+Options:
+
+* --static-only: Only generate the stylesheet and javascript
+* --use-jquery: Generate jquery javascript
+* --use-all-day: Include an 'all_day' field on events, and display appropriately
+
+You can change the default event model name (Event) and view name (Calendar) by passing in two name arguments:
+
+  script/generate event_calendar EventModel ViewName
+  
+
+==Generated Files
+
+Make sure to include the stylesheet and javascript in your layout/view.
+
+====Static files
+
+  public/stylesheets/event_calendar.css
+  public/javascripts/event_calendar.js
+
+Unless the --static-only option is given, the following will be generated. Names will differ if name arguments were passed to the generator.
+
+====db/migrate/XXXX_create_events.rb
+
+  class CreateEvents < ActiveRecord::Migration
+    def self.up
+      create_table :events do |t|
+        t.string :name
+        t.datetime :start_at
+        t.datetime :end_at
+
+        t.timestamps
+      end
+    end
+
+    def self.down
+      drop_table :events
+    end
+  end
+  
+At minimum we need to have start_at and end_at fields.
+
+If the '--use-all-day' option is passed to the generator, it will also add a boolean all_day field.
+
+An event can also have a *color* field (hex value stored as a string) which determines the color of the event.
+Or simply override the default virtual attribute on the model. For example, if events are associated to a calendar model, then the events can get their color from the calendar.
+
+====app/models/event.rb
+  
+  class Event < ActiveRecord::Base
+    has_event_calendar
+  end
+
+====config/routes.rb
+
+  map.calendar "/calendar/:year/:month", :controller => "calendar", :action => "index", :year => Time.now.year, :month => Time.now.month
+
+====app/controllers/calendar_controller.rb
+  
+  class CalendarController < ApplicationController
+
+    def index
+      @month = params[:month].to_i
+      @year = params[:year].to_i
+
+      @shown_month = Date.civil(@year, @month)
+
+      @event_strips = Event.event_strips_for_month(@shown_month)
+    end
+
+  end
+
+====app/helpers/calendar_helper.rb
+
+Some helper methods are created, but you could put this in the view. The key is our calendar method, which takes some options.
+
+  module CalendarHelper
+    def month_link(month_date)
+      link_to(I18n.localize(month_date, :format => "%B"), {:month => month_date.month, :year => month_date.year})
+    end
+  
+    # custom options for this calendar
+    def event_calendar_options
+      { 
+        :year => @year,
+        :month => @month,
+        :event_strips => @event_strips,
+        :month_name_text => I18n.localize(@shown_month, :format => "%B %Y"),
+        :previous_month_text => "<< " + month_link(@shown_month.last_month),
+        :next_month_text => month_link(@shown_month.next_month) + " >>"
+      }
+    end
+
+    def event_calendar
+      calendar event_calendar_options do |args|
+        event = args[:event]
+        %(<a href="/events/#{event.id}" title="#{h(event.name)}">#{h(event.name)}</a>)
+      end
+    end
+  end
+  
+Notice you can pass in a block to the calendar method. In this example I'm passing a link to the event details, and displaying the event's name.
+
+====app/views/calendar/index.html.erb
+
+Then in calendar view, simply:
+
+  <%= event_calendar %>
+
+
+==Default Options
+
+The default options for the calendar are:
+
+  defaults = {
+    :year => Time.zone.now.year,
+    :month => Time.zone.now.month,
+    :abbrev => true,
+    :first_day_of_week => 0, # See note below when setting this
+    :show_today => true,
+    :month_name_text => Time.zone.now.strftime("%B %Y"),
+    :previous_month_text => nil,
+    :next_month_text => nil,
+    :event_strips => [],
+    
+    # it would be nice to have these in the CSS file
+    # but they are needed to perform height calculations
+    :width => nil,
+    :height => 500, 
+    :day_names_height => 18,
+    :day_nums_height => 18,
+    :event_height => 18,
+    :event_margin => 1,
+    :event_padding_top => 1,
+    
+    :use_all_day => false,
+    :use_javascript => true,
+    :link_to_day_action => false
+  }
+  
+You can override any of these by passing your options to the calendar method. In the above example, update the event_calendar_options helper method.
+
+====Details
+
+* See the notes in the plugin's calendar_helper.rb for more info.
+
+* *width*: Optional, if none is given it will stretch to the containing element.
+
+* *height*: Defaults to 500px. This is the approx minimum total height of the calendar. It could be greater if a calendar row(s) need to stretch to fit additional events.
+
+* *use_all_day*: If set to true, will check for an 'all_day' boolean field when displaying an event. If it is an all day event, or the event is multiple days, then it will display as usual. Otherwise it will display without a background color bar.
+
+  Helper/View:
+    :use_all_day => true
+  
+  If using this option, you probably want to also show times for non-all-day events:
+    calendar event_calendar_options do |args|
+      event, day = args[:event], args[:day]
+      html = %(<a href="/events/#{event.id}" title="#{h(event.name)}">)
+      html << display_event_time(event, day)
+      html << %(#{h(event.name)}</a>)
+      html
+    end
+
+* *use_javascript*: If set to false, it won't add custom HTML data attributes that are needed for javascript highlighting. (Note, custom attributes will be valid in HTML 5.) The actual javascript is unobtrusive and found in the event_calendar.js file.
+
+* *link_to_day_action*: Will make the calendar's day numbers links to the given Rails action. Note, you'll probably want a corresponding route, controller action, and view to go with this action. Example:
+  
+  Helper/View calendar option:
+    :link_to_day_action => "day"
+  
+  Route (the controller is the same as your other calendar route):
+    map.calendar_day "/calendar/:year/:month/:day", :controller => "calendar", :action => "day"
+
+
+==Notes
+
+* If you want to change the <b>first day of the week</b> from the default of Sunday (0), then set the new value in an instance variable and pass it to event_strips_for_month (in the controller), and to the event calendar options (in the helper/view).
+
+  Controller:
+    @first_day_of_week = 1
+    @event_strips = Event.event_strips_for_month(@shown_month, @first_day_of_week)
+  
+  Helper/View calendar options:
+    :first_day_of_week => @first_day_of_week
+    
+* If you need access to the events, not just the event strips, then instead of calling event_strips_for_month call these 3 methods:
+
+    start_d, end_d = Event.get_start_and_end_dates(@shown_month) # optionally pass in @first_day_of_week
+    @events = Event.events_for_date_range(start_d, end_d)
+    @event_strips = Event.create_event_strips(start_d, end_d, @events)
+
+* The event <b>select color</b> is set in the event_calendar.js file.
+
+==il8n
+
+To localize month and day names, add the following to your localization file(s) in config/locales:
+
+  date -> formats, day_names, abbr_day_names, month_names, abbr_month_names
+  
+For example, in es.yml:
+
+  es:
+    date:
+      formats:
+        default: "%e/%m/%Y"
+
+      day_names: [Domingo, Lunes, Martes, Miércoles, Jueves, Viernes, Sábado]
+      abbr_day_names: [Dom, Lun, Mar, Mie, Jue, Vie, Sab]
+
+      # Don't forget the nil at the beginning; there's no such thing as a 0th month
+      month_names: [~, Enero, Febrero, Marzo, Abril, Mayo, Junio, Julio, Agosto, Septiembre, Octubre, Noviembre, Diciembre]
+      abbr_month_names: [~, Ene, Feb, Mar, Abr, May, Jun, Jul, Ago, Sep, Oct, Nov, Dic]
+  
+
+==Contributors
+
+* Jeff Schuil
+* See commit history for list of additional contributors.
+* Thanks to those who have added features, fixed bugs, and/or reported issues.
+
+== History
+
+* Though EventCalendar has diverged greatly, it was...
+* Originally based off of James Urquhart's http://www.cuppadev.co.uk/webdev/making-a-real-calendar-in-rails/
+* This in turn started as Geoffrey Grosenbach's CalendarHelper.
+
+Copyright (c) 2009 Elevation, released under the MIT license

data/Rakefile

@@ -0,0 +1,23 @@
+require 'rake'
+require 'rake/testtask'
+require 'rake/rdoctask'
+
+desc 'Default: run unit tests.'
+task :default => :test
+
+desc 'Test the event_calendar plugin.'
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = true
+end
+
+desc 'Generate documentation for the event_calendar plugin.'
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'EventCalendar'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/generators/event_calendar/USAGE

@@ -0,0 +1,20 @@
+Usage:
+
+    script/generate event_calendar [EVENT_MODEL VIEW_NAME]
+
+  This will create:
+      
+    # static files
+      public/stylesheets/event_calendar.css
+      public/javascripts/event_calendar.js
+      
+    # Unless --static-only option is given
+    # MVC and supporting files (depending on model and view name)
+      app/models/event.rb
+      app/controllers/calendar_controller.rb
+      app/views/calendar
+      app/views/calendar/index.html.erb
+      app/helpers/calendar_helper.rb
+      db/migrate
+      db/migrate/XXXX_create_events.rb
+      route map.calendar

data/generators/event_calendar/event_calendar_generator.rb

@@ -0,0 +1,50 @@
+require File.expand_path(File.dirname(__FILE__) + "/lib/insert_routes.rb")
+
+class EventCalendarGenerator < Rails::Generator::Base
+  default_options :static_only => false,
+                  :use_jquery =>  false,
+                  :use_all_day => false
+  
+  attr_reader :class_name, :view_name
+  
+  def initialize(args, runtime_options = {})
+    super
+    usage if args.length > 0 and args.length < 2
+    @class_name = (args.shift || "event").underscore
+    @view_name = (args.shift || "calendar").underscore
+  end
+  
+  def manifest
+    record do |m|
+      # static files
+      m.file "stylesheet.css", "public/stylesheets/event_calendar.css"
+      
+			script = options[:use_jquery] ? 'jq_javascript.js' : 'javascript.js'
+		  m.file script, "public/javascripts/event_calendar.js"
+      
+      # MVC and other supporting files
+      unless options[:static_only]
+        m.template "model.rb.erb", File.join("app/models", "#{@class_name}.rb")
+        m.template "controller.rb.erb", File.join("app/controllers", "#{@view_name}_controller.rb")
+        m.directory File.join("app/views", @view_name)
+        m.template "view.html.erb", File.join("app/views", @view_name, "index.html.erb")
+        m.template "helper.rb.erb", File.join("app/helpers", "#{@view_name}_helper.rb")        
+        m.migration_template "migration.rb.erb", "db/migrate", :migration_file_name => "create_#{@class_name.pluralize}"
+        m.route_name(@view_name, "/#{@view_name}/:year/:month", ":controller => '#{@view_name}', :action => 'index', :year => Time.zone.now.year, :month => Time.zone.now.month")
+      end
+    end
+  end
+  
+  protected
+  
+  def add_options!(opt)
+    opt.separator ''
+    opt.separator 'Options:'
+    opt.on("--static-only",
+      "Only generate the static files. (stylesheet, javascript, and images)") { |v| options[:static_only] = v }
+    opt.on("--use-jquery",
+      "Use jquery template file when generating the javascript.") { |v| options[:use_jquery] = v }
+    opt.on("--use-all-day",
+      "Include an 'all_day' field on events, and display appropriately.") { |v| options[:use_all_day] = v }
+  end
+end

data/generators/event_calendar/lib/insert_routes.rb

@@ -0,0 +1,55 @@
+# Adapted from Restful Authentication generator
+Rails::Generator::Commands::Create.class_eval do
+  def route_resource(*resources)
+    resource_list = resources.map { |r| r.to_sym.inspect }.join(', ')
+    sentinel = 'ActionController::Routing::Routes.draw do |map|'
+
+    logger.route "map.resource #{resource_list}"
+    unless options[:pretend]
+      gsub_file 'config/routes.rb', /(#{Regexp.escape(sentinel)})/mi do |match|
+        "#{match}\n  map.resource #{resource_list}\n"
+      end
+    end
+  end
+  
+  def route_name(name, path, route_options)
+    sentinel = 'ActionController::Routing::Routes.draw do |map|'
+    
+    logger.route "map.#{name} '#{path}', #{route_options}"
+    unless options[:pretend]
+      gsub_file 'config/routes.rb', /(#{Regexp.escape(sentinel)})/mi do |match|
+        "#{match}\n  map.#{name} '#{path}', #{route_options}"
+      end
+    end
+  end
+end
+
+Rails::Generator::Commands::Destroy.class_eval do
+  def route_resource(*resources)
+    resource_list = resources.map { |r| r.to_sym.inspect }.join(', ')
+    look_for = "\n  map.resource #{resource_list}\n"
+    logger.route "map.resource #{resource_list}"
+    unless options[:pretend]
+      gsub_file 'config/routes.rb', /(#{look_for})/mi, ''
+    end
+  end
+  
+  def route_name(name, path, route_options)
+    look_for =   "\n  map.#{name} '#{path}', #{route_options}"
+    logger.route "map.#{name} '#{path}', #{route_options}"
+    unless options[:pretend]
+      gsub_file    'config/routes.rb', /(#{look_for})/mi, ''
+    end
+  end
+end
+
+Rails::Generator::Commands::List.class_eval do
+  def route_resource(*resources)
+    resource_list = resources.map { |r| r.to_sym.inspect }.join(', ')
+    logger.route "map.resource #{resource_list}"
+  end
+  
+  def route_name(name, path, route_options)
+    logger.route "map.#{name} '#{path}', #{route_options}"
+  end
+end