radiant-event_calendar-extension 1.0.0

data/README.md

@@ -0,0 +1,198 @@
+# Event Calendar Extension for Radiant
+
+This extension lets your radiant site present calendar events in various useful ways. The events can be administered directly or retrieved by subscription to ical and caldav services including Google Calendar, and can be served as RSS, Ical or JSON feeds as well as through a broad set of radius tags on your normal pages. This extension supports a wide range of uses from a basic display of forthcoming events through to a full calendar aggregation and mapping service.
+
+The calendaring functionality comes from [ri_cal](http://github.com/rubyredrick/ri_cal) and supports proper recurrence and duration. We also recognise all-day events and pass through notes and urls: the ical subscription and redistribution should be fully RFC2445 compliant. It is not yet a full CalDAV client, and we don't have proper support for principals, groups or availability. 
+
+See the [event_map](http://github.com/spanner/radiant-event_map-extension) extension for googlemapping of events and [taggable_events](http://github.com/spanner/radiant-taggable_events-extension) for more fine-grained tagging and retrieval options. A `reader_events` extension is also in the works for reader-submitted calendar events, but [reader](http://github.com/spanner/radiant-reader-extension) will need to be updated for 0.9 first.
+
+## Requirements
+
+Radiant 0.9, share_layouts and the `ri_cal` gem to handle iCal data. It's declared in the extension so this should do it:
+
+	sudo rake gems:install
+	
+This is compatible with `multi_site` and with the [sites](http://github.com/spanner/radiant-event_map-extension "spanner's radiant-event_map-extension at master - GitHub") extension. With the latter everything will be site-scoped.
+
+There is a 0.81 tag in the repository for the last version good with radiant 0.8.1 and `scoped_admin`.
+
+## Installation
+
+Should be straightforward:
+
+	script/extension install event_calendar
+
+## Configuration
+
+There are a few optional config settings:
+
+* `event_calendar.icals_path` is the directory (under /public/) holding the calendar subscription files. Default is `icals`.
+* `event_calendar.default_refresh_interval` is the period, in seconds, after which the calendar subscriptions are refreshed. Default is one hour. Set to zero to refresh only in the admin interface. 
+* `event_calendar.layout` is the name of the layout that EventsController will use (see below)
+* `event_calendar.filename_prefix` is an optional prefix for ics filenames
+* `event_calendar.cached?` determines whether the EventsController pages are cached by Rack::Cache. EventCalendarPages are always cached like other pages.
+* `event_calendar.cache_duration` determines for how long.
+
+Each calendar subscription will have its own address and authentication settings.
+
+## Usage
+
+### Subscribing to a calendar
+
+1. Create a calendar source. You can do that by publishing a feed from your desktop calendar application, by making a google calendar public or by setting up a CalDAV calendar and persuading all the right people to subscribe to it.
+2. Find the ical subscription address of your calendar.
+3. Choose 'new calendar' in the radiant admin menu and enter the address and any authentication information you need to get at it. See below for notes about connecting to CalDAV. In the case of an ical file or google calendar you should only need an address. Give the calendar a slug, just as you would for a page, and optionally a category. Let's say you call it 'test'.
+4. Your calendar should appear in the subscription list. Click through to browse its events and make sure everything is as it should be.
+
+### Adding events manually
+
+Should be obvious. There are a few points to remember:
+
+* Event venues are expected to be reused, so they present as a list with the option to add a new one. 
+* The postcode field is a convenience for geocoding purposes. You can leave it blank unless you're mapping and your locations are a bit odd.
+* Recurrence is for the repetition of identical separate events. A single event that spans several days only needs to have the right start and end times.
+* End times are optional: an event with just a start time is just listed where it begins.
+
+### Displaying events with the EventsController
+
+The events controller uses `share_layouts` to define various page parts that your layout can bring in. To use it, create a layout with any or all of these parts:
+
+* `title` is the page title and can also be shown with `r:title`
+* `events` is a formatted list of events with date stamps and descriptions
+* `continuing_events` is a compact list of events that have already begun but which continue into the period being shown
+* `calendar` is a usual calendar block with links to months and days. Days without events are not linked.
+* `pagination` is the usual will_paginate block.
+* `faceting` here only gives the option to remove any date filters that have been applied. If you add the `taggable_events` extension it gets more useful.
+
+You will find minimal styling of some of these parts in `/stylesheets/sass/calendar.sass`,
+
+Set the config entry `event_calendar.layout` to the name of your layout and point a browser at /calendar to see what you've got.
+
+Here's a basic sample layout that should just work:
+
+	<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
+	    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+
+	<html xmlns="http://www.w3.org/1999/xhtml" lang="en">
+	  <head>
+	    <title><r:title /></title>
+		<link rel="stylesheet" href="/stylesheets/event_calendar.css" />
+	  </head>
+	  <body>
+        <h1 id="pagetitle"><r:title /></h1>
+		<r:content part="faceting" />
+        <r:content part="calendar" />
+        <r:content part="events" />
+        <r:content part="continuing_events" />
+		<r:content part="pagination" />
+	  </body>
+	</html>
+
+One quirk that might go away: at the moment if there are few new events then the continuing events are moved into the events page part. Most layouts work better that way.
+
+### Displaying events with an EventCalendar page
+
+Set up a new page at /events/ with the type 'EventCalendar'. To show a pageable calendar view of the current month, all you need is this:
+
+	<r:events:as_calendar month="now" month_links="true" />
+	
+Or to show a list of all events in the next six months:
+
+	<p><r:calendars:summary /></p>
+	
+	<div class="event_list">
+	  <r:events:each calendar_months="6">
+	    <r:event:header name="date">
+	      <h2 id="<r:event:year />_<r:event:month />"><r:event:month /> <r:event:year /></h2>
+	    </r:event:header>
+		<p id="event_<r:event:id />">
+		  <acronym class="date">
+		    <r:event:day_ordinal />
+		  </acronym>
+		  <r:event:link class="title" />
+		  <r:event:if_location>
+		    <span class="location"><r:event:location /></span>
+		  </r:event:if_location>
+		  <r:event:if_description>
+		    <br />
+		    <span class="description"><r:event:description /></span>
+		  </r:event:if_description>
+		</p>
+	  </r:events:each>
+	</div>	
+
+Note that the `event:header` tag only shows when it changes, which in this case gives you a non-repeating date slip. For more about the available radius tags, see the extension wiki or the 'available tags' documentation.
+
+If you have another column in your layout, try adding this:
+
+	<r:events:as_calendar calendar_months="6" date_links="true" compact="true" />
+
+For clickable thumbnails of coming months.
+
+## Notes
+
+This is developing quite quickly at the moment but it's in production use on one big and several small sites. If there are bugs they will be fixed immediately.
+
+### Compatibility
+
+I've tested this with Darwin Calendar Server (on Ubuntu), with Google Calendar and with feeds published from iCal on a mac. It should work just as well with iCal server on OS X Server, and in theory any other CalDav-compliant back end. See http://caldav.calconnect.org/ for more possibilities.
+
+### Connecting to Google Calendar
+
+Create a calendar in your Google Calendar account. Call it 'public', or whatever you like, and tick the box marked 'make this calendar public'.
+
+Click on 'calendar settings' from the drop-down menu next to the name of the public calendar, and look towards the bottom for the 'Calendar Address' section. Click on 'ical' and the address that pops up is your subscription address. You shouldn't need anything else.
+
+### Connecting to CalDAV
+
+We aren't really doing CalDAV properly here, but taking advantage of its compatibility with the simpler ical standard. A simple GET to addresses under /calendar will return a file in ical format, which is what we get and parse. As a passive display client, that's all we need, but it does mean that so far we can't display groups properly, or interact with principals, or take proper advantage of the more collaborative functions of CalDAV.
+
+The address for your calendar will either look like this:
+
+	https://[calendar.server.com]:8443/calendars/users/[someone]/calendar/
+	
+or like this:
+
+	https://[calendar.server.com]:8443/calendars/users/[someone]/1D09F977-2F27-4E87-954D-FFED95A70BC0/
+
+but note that the port and protocol will depend on your server setup. The best way to find these addresses is to visit the calendar server in a normal web browser, log in as the authorised person, and cut and paste the address of the calendar you want. You may also be able to get the right address out of iCal or sunbird but some trial and error will be involved.
+
+The best way to think of these addresses under /calendar/ is as the read-only version. The address that you will subscribe to in your desktop calendar application is the read-write version and will look slightly different:
+
+	https://[calendar.server.com]:8443/principals/users/[someone]/
+
+is all you need to put into iCal, for example: it will handle subcalendars and GUIDs without bothering you for details.
+
+### Setting up a CalDAV server
+
+It's not nice. There are three main options:
+
+* OS X Server has an excellent built-in ICal server
+* [Darwin Calendar Server](https://trac.calendarserver.org/wiki) is the open-source version of that. It's written mostly in Python and distinctly quirky, but once set up it works very well.
+* Use a Google calendar and endure a bit of sync bother to get it on the desktop.
+* er
+* That's it unless you speak Java, in which case there are [several](http://caldav.calconnect.org/implementations/servers.html) other [good options](http://www.bedework.org/bedework/).
+
+See [http://caldav.calconnect.org/](http://caldav.calconnect.org/) for news and background information.
+
+### Quirks
+
+Calendars are only refreshed if they're accessed. The `event_calendar.default_refresh_interval` setting is really a cache duration: on the next request after that interval, we go back to the original source. If that gets too slow for the end user who triggers the refresh then I'll need to add a calendar-refresh rake task that can be crontabbed, but so far it seems to work well enough.
+
+If you're administering your calendars in iCal, the first calendar you set up will be accessible at the simple /users/uid/calendar address but after that you'll have to get the GUIDs. You can get-info on a calendar to get a subscription address but if it's long it may be truncated.
+
+OS X 10.6 promises to handle all this a lot better. On Windows you're pretty much confined to Sunbird at the moment. There is a project to [hook Outlook up](http://openconnector.org/) to CalDAV but it seems to have stalled.
+
+## Bugs and features
+
+[Github issues](http://github.com/radiant/radiant-event-calendar-extension/issues) please, or for little things an email or github message is fine.
+
+## Author & Copyright
+
+Originally created by Loren Johnson - see www.hellovenado.com - and then taken over by the radiant team. Currently maintained by Will at spanner.org.
+
+Released under the same terms as Radiant and/or Rails.
+
+
+
+

data/Rakefile

@@ -0,0 +1,139 @@
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "radiant-event_calendar-extension"
+    gem.summary = %Q{Event Calendar Extension for Radiant CMS}
+    gem.description = %Q{An event calendar extension that administers events locally or draws them from any ical or CalDAV publishers (Google Calendar, .Mac, Darwin Calendar Server, etc.)}
+    gem.email = "will@spanner.org"
+    gem.homepage = "http://github.com/radiant/radiant-event_calendar-extension"
+    gem.authors = ["spanner"]
+    gem.add_dependency "radiant", ">= 0.9.0"
+    gem.add_dependency "ri_cal"
+    gem.add_dependency "chronic"
+    gem.add_dependency "uuidtools"
+  end
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. This is only required if you plan to package event_calendar as a gem."
+end
+
+# In rails 1.2, plugins aren't available in the path until they're loaded.
+# Check to see if the rspec plugin is installed first and require
+# it if it is.  If not, use the gem version.
+
+# Determine where the RSpec plugin is by loading the boot
+unless defined? RADIANT_ROOT
+  ENV["RAILS_ENV"] = "test"
+  case
+  when ENV["RADIANT_ENV_FILE"]
+    require File.dirname(ENV["RADIANT_ENV_FILE"]) + "/boot"
+  when File.dirname(__FILE__) =~ %r{vendor/radiant/vendor/extensions}
+    require "#{File.expand_path(File.dirname(__FILE__) + "/../../../../../")}/config/boot"
+  else
+    require "#{File.expand_path(File.dirname(__FILE__) + "/../../../")}/config/boot"
+  end
+end
+
+require 'rake'
+require 'rake/rdoctask'
+require 'rake/testtask'
+
+rspec_base = File.expand_path(RADIANT_ROOT + '/vendor/plugins/rspec/lib')
+$LOAD_PATH.unshift(rspec_base) if File.exist?(rspec_base)
+require 'spec/rake/spectask'
+require 'cucumber'
+require 'cucumber/rake/task'
+
+# Cleanup the RADIANT_ROOT constant so specs will load the environment
+Object.send(:remove_const, :RADIANT_ROOT)
+
+extension_root = File.expand_path(File.dirname(__FILE__))
+
+task :default => :spec
+task :stats => "spec:statsetup"
+
+desc "Run all specs in spec directory"
+Spec::Rake::SpecTask.new(:spec) do |t|
+  t.spec_opts = ['--options', "\"#{extension_root}/spec/spec.opts\""]
+  t.spec_files = FileList['spec/**/*_spec.rb']
+end
+
+task :features => 'spec:integration'
+
+namespace :spec do
+  desc "Run all specs in spec directory with RCov"
+  Spec::Rake::SpecTask.new(:rcov) do |t|
+    t.spec_opts = ['--options', "\"#{extension_root}/spec/spec.opts\""]
+    t.spec_files = FileList['spec/**/*_spec.rb']
+    t.rcov = true
+    t.rcov_opts = ['--exclude', 'spec', '--rails']
+  end
+  
+  desc "Print Specdoc for all specs"
+  Spec::Rake::SpecTask.new(:doc) do |t|
+    t.spec_opts = ["--format", "specdoc", "--dry-run"]
+    t.spec_files = FileList['spec/**/*_spec.rb']
+  end
+
+  [:models, :controllers, :views, :helpers].each do |sub|
+    desc "Run the specs under spec/#{sub}"
+    Spec::Rake::SpecTask.new(sub) do |t|
+      t.spec_opts = ['--options', "\"#{extension_root}/spec/spec.opts\""]
+      t.spec_files = FileList["spec/#{sub}/**/*_spec.rb"]
+    end
+  end
+  
+  desc "Run the Cucumber features"
+  Cucumber::Rake::Task.new(:integration) do |t|
+    t.fork = true
+    t.cucumber_opts = ['--format', (ENV['CUCUMBER_FORMAT'] || 'pretty')]
+    # t.feature_pattern = "#{extension_root}/features/**/*.feature"
+    t.profile = "default"
+  end
+
+  # Setup specs for stats
+  task :statsetup do
+    require 'code_statistics'
+    ::STATS_DIRECTORIES << %w(Model\ specs spec/models)
+    ::STATS_DIRECTORIES << %w(View\ specs spec/views)
+    ::STATS_DIRECTORIES << %w(Controller\ specs spec/controllers)
+    ::STATS_DIRECTORIES << %w(Helper\ specs spec/views)
+    ::CodeStatistics::TEST_TYPES << "Model specs"
+    ::CodeStatistics::TEST_TYPES << "View specs"
+    ::CodeStatistics::TEST_TYPES << "Controller specs"
+    ::CodeStatistics::TEST_TYPES << "Helper specs"
+    ::STATS_DIRECTORIES.delete_if {|a| a[0] =~ /test/}
+  end
+
+  namespace :db do
+    namespace :fixtures do
+      desc "Load fixtures (from spec/fixtures) into the current environment's database.  Load specific fixtures using FIXTURES=x,y"
+      task :load => :environment do
+        require 'active_record/fixtures'
+        ActiveRecord::Base.establish_connection(RAILS_ENV.to_sym)
+        (ENV['FIXTURES'] ? ENV['FIXTURES'].split(/,/) : Dir.glob(File.join(RAILS_ROOT, 'spec', 'fixtures', '*.{yml,csv}'))).each do |fixture_file|
+          Fixtures.create_fixtures('spec/fixtures', File.basename(fixture_file, '.*'))
+        end
+      end
+    end
+  end
+end
+
+desc 'Generate documentation for the event_calendar extension.'
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'EventCalendarExtension'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+# For extensions that are in transition
+desc 'Test the event_calendar extension.'
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = true
+end
+
+# Load any custom rakefiles for extension
+Dir[File.dirname(__FILE__) + '/tasks/*.rake'].sort.each { |f| require f }

data/VERSION

@@ -0,0 +1 @@
+1.0.0

data/app/controllers/admin/calendars_controller.rb

@@ -0,0 +1,18 @@
+class Admin::CalendarsController < Admin::ResourceController
+  paginate_models
+  before_filter :check_refreshments, :only => [:index, :show]
+
+  def show
+    @calendar = Calendar.find(params[:id])
+    @year = params[:year] ? params[:year].to_i : Date.today.year
+    @month = params[:month] ? params[:month].to_i : Date.today.month
+    response_for :singular
+  end
+  
+protected
+
+  def check_refreshments
+    Ical.check_refreshments
+  end
+
+end

data/app/controllers/admin/event_venues_controller.rb

@@ -0,0 +1,3 @@
+class Admin::EventVenuesController < Admin::ResourceController
+
+end

data/app/controllers/admin/events_controller.rb

@@ -0,0 +1,9 @@
+class Admin::EventsController < Admin::ResourceController
+  paginate_models :per_page => 20
+  
+  def load_models
+    finder = params[:all] ? Event.all : Event.future_and_current
+    self.models = finder.paginate(pagination_parameters)
+  end
+
+end

data/app/controllers/admin/icals_controller.rb

@@ -0,0 +1,26 @@
+class Admin::IcalsController < Admin::ResourceController
+
+  def refresh_all
+    # This is the correct line for the agent to run.  
+    # Calendar::refresh_all
+    
+    # We'll keep using this so we can keep an eye on the downlaod status until an agent and proper error checking is implemented.
+    @icals = Ical.find(:all)
+    @icals.each do |ical|
+      ical.refresh
+    end
+    flash[:notice] = "iCal subscription refresh complete."
+    redirect_to admin_calendars_path
+  end 
+  
+  def refresh
+    ical = Ical.find(params[:id])
+    if ical.refresh
+      flash[:notice] = ical.calendar.name + " calendar refreshed from iCal subscription ."
+    else
+      flash[:notice] = "Error parsing " + ical.calendar.name + " calendar from iCal subscription."
+    end
+    redirect_to :back
+  end
+  
+end

data/app/controllers/events_controller.rb

@@ -0,0 +1,201 @@
+class EventsController < SiteController
+  require "uri"
+  
+  helper_method :events, :all_events, :continuing_events, :period, :calendars, :list_description
+  helper_method :url_for_date, :url_for_month, :url_without_period, :calendar_parameters, :month_name, :short_month_name, :day_names
+  before_filter :numerical_parameters
+  
+  radiant_layout { |controller| controller.layout_for :event_calendar }
+  no_login_required
+
+  # delivers designated lists of events in minimal formats
+
+  def index
+    @seen_events = {}
+    respond_to do |format|
+      format.html {
+        if Radiant::Config['event_calendar:cached?']
+          timeout = Radiant::Config['event_calendar:cache_duration'] || self.class.cache_timeout
+          expires_in timeout.to_i, :public => true, :private => false
+        else
+          expires_now
+        end
+      }
+      format.js {
+        render :json => events.to_json
+      }
+      format.rss {
+        render :layout => false
+      }
+      format.ics {
+        headers["Content-disposition"] = %{attachment; filename="#{filename}.ics"}
+        render :layout => false
+      }
+    end
+  end
+  
+  def period
+    return @period if @period
+    this = Date.today
+    if params[:mday]
+      start = Date.civil(params[:year] || this.year, params[:month] || this.month, params[:mday])
+      @period = CalendarPeriod.between(start, start.to_datetime.end_of_day)
+    elsif params[:month]
+      start = Date.civil(params[:year] || this.year, params[:month])
+      @period = CalendarPeriod.between(start, start.to_datetime.end_of_month)
+    elsif params[:year]
+      start = Date.civil(params[:year])
+      @period = CalendarPeriod.between(start, start.to_datetime.end_of_year)
+    end
+  end
+  
+  def calendars
+    return @calendars if @calendars
+    if params[:calendar_id]
+      @calendars = [Calendar.find(params[:calendar_id])]
+    elsif params[:slug]
+      @calendars = Calendar.with_slugs(params[:slug])
+    elsif params[:category]
+      @calendars = Calendar.in_category(params[:category])
+    end
+  end
+  
+  def events
+    @events ||= event_finder.paginate(pagination_parameters)
+  end
+  
+  def all_events
+    @all_events ||= event_finder.all
+  end
+  
+  def event_finder
+    ef = Event.scoped
+    if period
+      if period.bounded?
+        ef = ef.between(period.start, period.finish) 
+      elsif period.start
+        ef = ef.after(period.start) 
+      else
+        ef = ef.before(period.finish) 
+      end
+    else
+      ef = ef.future
+    end
+    ef = ef.approved if Radiant::Config['event_calendar.require_approval']
+    ef = ef.in_calendars(calendars) if calendars
+    ef
+  end
+  
+  def continuing_events
+    return @continuing_events if @continuing_events
+    if period && period.start
+      @continuing_events = Event.unfinished(period.start).by_end_date
+    else
+      @continuing_events = Event.unfinished(Time.now).by_end_date
+    end
+  end
+  
+  def list_description
+    return @description if @description
+    parts = []
+    parts << (period ? period.description : "coming up")
+    parts << "in #{calendars.to_sentence}" if calendars
+    @description = parts.join(' ')
+  end
+      
+  def url_for_date(date)
+    url_for(url_parts({
+      :mday => date.mday,
+      :month => month_name(date.month).downcase,
+      :year => date.year
+    }))
+  end
+  
+  def url_for_month(date)
+    url_for(url_parts({
+      :mday => nil,
+      :month => month_name(date.month).downcase,
+      :year => date.year
+    }))
+  end
+  
+  def url_without_period
+    url_for(url_parts({
+      :mday => nil,
+      :month => nil,
+      :year => nil
+    }))
+  end
+  
+  def query_string
+    url_parts.map{|p| "#{p}=params[p]" }.join("&amp;")
+  end
+  
+  def filename
+    url_parts.map{|p| params[p] }.join("_")
+  end
+  
+  # this is broken down to provide chain points for other extensions that add more ways to filter
+  # eg, to start with, taggable_events
+
+  def calendar_parameters
+    url_parts
+  end
+  
+  def url_parts(amendments={})
+    parts = params.slice(*calendar_parameter_names)   # Hash#slice is defined in will_paginate/lib/core_ext
+    parts.merge(amendments)
+  end
+  
+  def calendar_parameter_names
+    [:year, :month, :mday, :category, :slug, :calendar_id]
+  end
+  
+  def month_name(month)
+    month_names[month]
+  end
+  
+  def short_month_name(month)
+    short_month_names[month]
+  end
+  
+  def day_names
+    return @day_names if @day_names
+    @day_names ||= Date::DAYNAMES.dup
+    @day_names.push(@day_names.shift) # Class::Date and ActiveSupport::CoreExtensions::Time::Calculations have different ideas of when is the start of the week. We've gone for the rails standard.  
+    @day_names
+  end
+  
+protected
+  
+  def short_month_names
+    @short_month_names ||= Date::ABBR_MONTHNAMES.dup
+  end
+  
+  def month_names
+    @month_names ||= Date::MONTHNAMES.dup
+  end
+  
+  # months can be passed around either as names or numbers
+  # any date part can be 'now' or 'next' for ease of linking
+  # and everything is converted to_i to save clutter later
+  
+  def numerical_parameters
+    if params[:month] && month_names.include?(params[:month].titlecase)
+      params[:month] = month_names.index(params[:month].titlecase)
+    end
+    [:year, :month, :mday].select{|p| params[p] }.each do |p|
+      params[p] = Date.today.send(p) if params[p] == 'now'
+      params[p] = (Date.today + 1.send(p == :mday ? :day : p)).send(p) if params[p] == 'next'
+      params[p] = params[p].to_i
+    end
+  end
+  
+  def pagination_parameters
+    {
+      :page => (params[:p] || 1).to_i, 
+      :per_page => (params[:pp] || Radiant::Config['event_calendar.per_page'] || 10).to_i
+    }
+  end
+  
+end