edave-gcal4ruby 0.6.0

data/CHANGELOG

@@ -0,0 +1,85 @@
+=CHANGELOG
+==version 0.6.0
+* Updated Service to work with multiple types of GData4Ruby services
+==version 0.5.5 
+* Fixed calendar::find method.  Thanks to AB <a.berezovskiy@gmail.com>.
+* Improved recurrence handling.  Thanks to John Paul Narowski <jnarowski@gmail.com>.
+* Fixed documentation bug for event reminders.
+* Changed license to LGPLv3.
+==version 0.5.4
+* Fixed Serviceto_iframe bgcolor bug
+==version 0.5.3
+* Fixed bug when loading event attributes when initializing
+==version 0.5.2
+* Fixed calendar.public functionality for making calendars publicly viewable.
+* Fixed to_iframe output methods
+* Fixed issue with creating new events
+==version 0.5.1
+* Minor fixes to to_iframe methods
+==version 0.5.0 - MAJOR CHANGES
+* Now using GData4Ruby library as base class for service, calendar, and event objects.  This removed the base.rb class, which is now inherited from
+  GData4ruby
+* Added 'events' method to service to get all events for an account.
+* Major interface changes to find methods - these are not backwards compatible changes.
+* Changed Eventfind default behavior to search all calendars.
+* Major interface changes to to_iframe methods - these are not backwards compatible changes.
+* Added support for multiple reminders.
+* Improved object relationship for events.  Events are now service-centric, i.e. events are instantiated with a service object.
+* Event calendar is now set through a 'calendar' attribute.
+* Fixes to event recurrence handling and display.
+* Added support for reminders with recurring events.
+* Numerous improvements to performance.
+* Calendar objects no longer have to query ACL feed to determine editability.
+* Added support for event statuses: cancelled, tentative or confirmed.
+==version 0.3.2
+* Updated the Event.find method to support finding all events by passing :all as the query term.
+==version 0.3.1
+* Fixed Event.find method to work with secondary calendars and google apps accounts.  Fix provided by groesser3.
+* Added max results to Calendar.find.
+==version 0.3.0
+* Rewrote Event.find to improve performance significantly.
+* Added improvements to event recurrence handling, including loading existing recurrences, changing recurring events to non recurring and vice versa.
+* Added support for initialization attributes to Event, Calendar, Service and Recurrence.
+* Fixed query string typo in Event.find.  Fix provided by nat.lownes.
+==version 0.2.11
+* Added support for GML elements in calendar events.  Fix provided by nat.lownes.
+* Fixed event status bug where cancelled events were marked confirmed.  Fix provided by rifraf.
+==version 0.2.10
+* Fixed library support for Google Hosted Apps accounts running in forced SSL mode.
+==version 0.2.9
+* Fixed small SSL redirect bug due to variable misnaming in base.rb.  Fix provided by JohnMetta
+==version 0.2.8
+* Merged changes from edruder and h13ronim from the unofficial github repo - http://github.com/h13ronim/gcal4ruby/commits/master
+==version 0.2.7
+* Added fix for finding events in calendars that have more than 25 entries
+==version 0.2.6
+* Added fix for updated google calendar XML per http://cookingandcoding.wordpress.com/2009/06/08/new-ruby-google-calendar-api-gem-gcal4ruby/comment-183
+==version 0.2.5
+* Added calendar color support to to_iframe methods in Calendar and Service.
+==version 0.2.4
+* Fixed bug with ACL check in Calendarload
+==version 0.2.3
+* Implemented to_iframe method for calendars and services to output embeddable iframe text.
+* Added switch to turn off ACL check for public calendars.  Can increase effeciency if turned off.
+==version 0.2.2
+* Fixed URL encoding problem in Event.find method.
+* cleaned up Event.find method to allow for finding events by id
+* updated Calendar.find method to add params hash
+* added 'published', 'updated', and 'edited' attributes
+==version 0.2.1
+* fixed Event.find calendar specification
+==version 0.2.0
+* Fixed redirect URI query params problem
+* Updated syntax for finding events to include most google api parameters,  Non-backwards compatible.
+==version 0.1.4
+* Added additional search criteria for Event.find
+==version 0.1.3
+* Added support for authenticating with Google Hosted Apps accounts
+* Added flag to indicate whether a calendar is editable
+* Added handling to gracefully throw error when trying to create event on a non-editable (shared) calendar
+==version 0.1.2
+* Fixed to_xml dump problem with hidden and selected attributes
+==version 0.1.1
+* Added all_day indicator to event to indicate an all day event
+==version 0.1.0
+* Initial Version

data/README

@@ -0,0 +1,103 @@
+=GCal4Ruby
+
+==Introduction
+GCal4Ruby is a full featured wrapper for the google calendar API.  GCal4Ruby implements
+all of the functionality available through the Google Calnedar API, including permissions,
+attendees, reminders and event recurrence.  
+
+==Author and Contact Information
+GCal4Ruby was created and is maintained by {Mike Reich}[mailto:mike@seabourneconsulting.com] 
+and is licenses under the LGPL v3.  Feel free to use and update, but be sure to contribute your
+code back to the project and attribute as required by the license.  You can find the text of the LGPL 
+here: http://www.gnu.org/licenses/lgpl.html.
+
+===Website
+http://cookingandcoding.com/gcal4ruby/
+
+==Description
+GCal4Ruby has three major components: the service, calendar and event objects.  Each service
+has many calendars, which in turn have many events.  Each service is the representation of a
+google account, and thus must be successfully authenticated using valid Google Calendar
+account credentials.  
+
+==Examples
+Below are some common usage examples.  For more examples, check the documentation.
+===Service
+# Authenticate with the AuthSub service (quickest, dirtiest)
+    service = Service.new
+    service.authenticate({:username => "user@gmail.com", :password => "password"})
+
+# Authenticate using OAuth (more setup, easier for an app)
+	service = Service.new({:GData4RubyService => :OAuthService})
+	service.authenticate(my_oauth_accesstoken)
+
+# Get Calendar List
+    calendars = service.calendars
+
+===Calendar
+All usages assume a successfully authenticated Service.
+1. Create a new Calendar
+    cal = Calendar.new(service)
+
+2. Find a calendar by ID
+    cal = Calendar.find(service, {:id => cal_id})
+
+3. Get all calendar events
+    cal = Calendar.find(service, {:id => cal_id})
+    events = cal.events
+
+4. Find an existing calendar by title
+    cal = Calendar.find(service, {:title => "New Calendar"})
+
+5. Find all calendars containing a search term
+    cal = Calendar.find(service, "Soccer Team")
+===Event
+All usages assume a successfully authenticated Service and valid Calendar.
+1. Create a new Event
+    event = Event.new(service, {:calendar => cal, :title => "Soccer Game", :start => Time.parse("12-06-2009 at 12:30 PM"), :end => Time.parse("12-06-2009 at 1:30 PM"), :where => "Merry Playfields"})
+    event.save
+
+2. Find an existing Event by title
+    event = Event.find(service, {:title => "Soccer Game"})
+
+3. Find an existing Event by ID
+    event = Event.find(service, {:id => event.id})
+
+4. Find all events containing the search term
+    event = Event.find(service, "Soccer Game")
+
+5. Find all events on a calendar containing the search term
+    event = Event.find(service, "Soccer Game", {:calendar => cal.id})
+
+6. Find events within a date range
+    event = Event.find(service, "Soccer Game", {'start-min' => Time.parse("01/01/2010").utc.xmlschema, 'start-max' => Time.parse("06/01/2010").utc.xmlschema})
+
+7. Create a recurring event for every saturday
+    event = Event.new(service)
+    event.title = "Baseball Game"
+    event.calendar = cal
+    event.where = "Municipal Stadium"
+    event.recurrence = Recurrence.new
+    event.recurrence.start_time = Time.parse("06/20/2009 at 4:30 PM")
+    event.recurrence.end_time = Time.parse("06/20/2009 at 6:30 PM")
+    event.recurrence.frequency = {"weekly" => ["SA"]}
+    event.save 
+
+8. Create an event with a 15 minute email reminder
+    event = Event.new(service)
+    event.calendar = cal
+    event.title = "Dinner with Kate"
+    event.start_time = Time.parse("06/20/2009 at 5 pm")
+    event.end_time = Time.parse("06/20/2009 at 8 pm")
+    event.where = "Luigi's"
+    event.reminder = {:minutes => 15, :method => 'email'}
+    event.save
+
+9. Create an event with attendees
+    event = Event.new(service)
+    event.calendar = cal
+    event.title = "Dinner with Kate"
+    event.start_time = Time.parse("06/20/2009 at 5 pm")
+    event.end_time = Time.parse("06/20/2009 at 8 pm")
+    event.attendees => {:name => "Kate", :email => "kate@gmail.com"}
+    event.save

data/lib/gcal4ruby.rb

@@ -0,0 +1 @@
+require "gcal4ruby/service" 

data/lib/gcal4ruby/calendar.rb

@@ -0,0 +1,378 @@
+# Author:: Mike Reich (mike@seabourneconsulting.com)
+# Copyright:: Copyright (C) 2010 Mike Reich
+# License:: GPL v2
+#--
+# Licensed under the General Public License (GPL), Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#
+# Feel free to use and update, but be sure to contribute your
+# code back to the project and attribute as required by the license.
+#++
+require 'gdata4ruby/acl/access_rule'
+module GCal4Ruby
+  #The Calendar Class is the representation of a Google Calendar.  Each user account 
+  #can have multiple calendars.  You must have an authenticated Service object before 
+  #using the Calendar object.
+  #=Usage
+  #All usages assume a successfully authenticated Service.
+  #1. Create a new Calendar
+  #    cal = Calendar.new(service)
+  #
+  #2. Find a calendar by ID
+  #    cal = Calendar.find(service, {:id => cal_id})
+  #
+  #3. Get all calendar events
+  #    cal = Calendar.find(service, {:id => cal_id})
+  #    events = cal.events
+  #
+  #4. Find an existing calendar by title
+  #    cal = Calendar.find(service, {:title => "New Calendar"})
+  #
+  #5. Find all calendars containing a search term
+  #    cal = Calendar.find(service, "Soccer Team")
+  #
+  #After a calendar object has been created or loaded, you can change any of the 
+  #attributes like you would any other object.  Be sure to save the calendar to write changes
+  #to the Google Calendar service.
+  class Calendar < GData4Ruby::GDataObject
+    @@calendar_feed = "http://www.google.com/calendar/feeds/default/owncalendars/full/"
+    @@calendar_query_feed = "http://www.google.com/calendar/feeds/default/calendars/"
+    @@calendar_xml = "<entry xmlns='http://www.w3.org/2005/Atom' 
+         xmlns:gd='http://schemas.google.com/g/2005' 
+         xmlns:gCal='http://schemas.google.com/gCal/2005'>
+    <title type='text'></title>
+    <summary type='text'></summary>
+    <gCal:timezone value='America/Los_Angeles'></gCal:timezone>
+    <gCal:hidden value='false'></gCal:hidden>
+    <gCal:color value='#2952A3'></gCal:color>
+    <gd:where rel='' label='' valueString='Oakland'></gd:where>
+  </entry>"
+
+    #The calendar title
+    attr_accessor :title
+
+    #A short description of the calendar
+    attr_accessor :summary
+    
+    #Boolean value indicating the calendar visibility
+    attr_accessor :hidden
+    
+    #The calendar timezone[http://code.google.com/apis/calendar/docs/2.0/reference.html#gCaltimezone]
+    attr_accessor :timezone
+    
+    #The calendar color.  Must be one of these[http://code.google.com/apis/calendar/docs/2.0/reference.html#gCalcolor] values.
+    attr_accessor :color
+    
+    #The calendar geo location, if any
+    attr_accessor :where
+    
+    #A boolean value indicating whether the calendar appears by default when viewed online
+    attr_accessor :selected
+    
+    #A flag indicating whether the calendar is editable by this account 
+    attr_reader :editable
+    
+    #Accepts a Service object and an optional attributes hash for initialization.  Returns the new Calendar 
+    #if successful, otherwise raises the InvalidService error.
+    def initialize(service, attributes = {})
+      super(service, attributes)
+      if !service.is_a?(Service)
+        raise InvalidService
+      end
+      @xml = @@calendar_xml
+      @service ||= service
+      @exists = false
+      @title ||= ""
+      @summary ||= ""
+      @public ||= false
+      @hidden ||= false
+      @timezone ||= "America/Los_Angeles"
+      @color ||= "#2952A3"
+      @where ||= ""
+      attributes.each do |key, value|
+        if self.respond_to?("#{key}=")
+          self.send("#{key}=", value)
+        end
+      end
+      @debug ||= false
+      return true
+    end
+    
+    #Returns true if the calendar exists on the Google Calendar system (i.e. was 
+    #loaded or has been saved).  Otherwise returns false.
+    def exists?
+      return @exists
+    end
+    
+    #Returns true if the calendar is publically accessable, otherwise returns false.
+    def public?
+      return @public
+    end
+    
+    #Returns an array of Event objects corresponding to each event in the calendar.
+    def events
+      events = []
+      ret = service.send_request(GData4Ruby::Request.new(:get, @content_uri))
+      REXML::Document.new(ret.body).root.elements.each("entry"){}.map do |entry|
+        entry = GData4Ruby::Utils.add_namespaces(entry)
+        e = Event.new(service)
+        if e.load(entry.to_s)
+          events << e
+        end
+      end
+      return events
+    end
+    
+    
+    #Saves the calendar.
+    def save
+      public = @public
+      ret = super
+      return ret if public == @public
+      if public
+        log('setting calendar to public')
+        rule = GData4Ruby::ACL::AccessRule.new(service.gdata_service, self)
+        rule.role = 'http://schemas.google.com/gCal/2005#read'
+        rule.save
+      else
+        rule = GData4Ruby::ACL::AccessRule.find(service.gdata_service, self, {:user => 'default'})
+        rule.delete if rule
+      end
+      reload
+    end
+    
+    #Set the calendar to public (p = true) or private (p = false).  Publically viewable
+    #calendars can be accessed by anyone without having to log in to google calendar.  See
+    #Calendar#to_iframe on how to display a public calendar in a webpage.
+    def public=(p)
+      @public = p
+    end
+    
+    #Creates a new instance of the object
+    def create
+      return service.send_request(GData4Ruby::Request.new(:post, @@calendar_feed, to_xml()))
+    end
+    
+    #Finds a Calendar based on a text query or by an id.  Parameters are:
+    #*service*::  A valid Service object to search.
+    #*query*:: either a string containing a text query to search by, or a hash containing an +id+ key with an associated id to find, or a +query+ key containint a text query to search for, or a +title+ key containing a title to search.
+    #*args*:: a hash containing optional additional query paramters to use.  See http://code.google.com/apis/gdata/docs/2.0/reference.html#Queries for a full list of possible values.  Example: 
+    # {'max-results' => '100'}
+    #If an ID is specified, a single instance of the calendar is returned if found, otherwise false.
+    #If a query term or title text is specified, and array of matching results is returned, or an empty array if nothing
+    #was found.
+    def self.find(service, query, args = {})
+      raise ArgumentError, 'query must be a hash or string' if not query.is_a? Hash and not query.is_a? String
+      if query.is_a? Hash and query[:id]
+        id = query[:id]
+        #log("Finding by ID: #{id}")
+        d = service.send_request(GData4Ruby::Request.new(:get, id, {}))
+        #log(d.inspect)
+        if d
+          return get_instance(service, d)
+        end
+      else
+        #fugly, but Google doesn't provide a way to query the calendar feed directly
+        old_public = service.check_public
+        service.check_public = false
+        results = []
+        cals = service.calendars
+        cals.each do |cal|
+          if query.is_a?(Hash)
+            results << cal if query[:query] and cal.title.downcase.include? query[:query].downcase
+            results << cal if query[:title] and cal.title == query[:title]
+          else
+            results << cal if cal.title.downcase.include? query.downcase
+          end
+        end
+        service.check_public = old_public
+        return results
+      end
+      return false
+    end
+    
+    #Reloads the calendar objects information from the stored server version.  Returns true
+    #if successful, otherwise returns false.  Any information not saved will be overwritten.
+    def reload
+      return false if not @exists
+      t = Calendar.find(service, {:id => @id})
+      if t
+        load(t.to_xml)
+      else
+        return false
+      end
+    end
+    
+    #Returns the xml representation of the Calenar.
+    def to_xml
+      xml = REXML::Document.new(super)
+      xml.root.elements.each(){}.map do |ele|
+        case ele.name
+          when "summary"
+          ele.text = @summary
+          when "timezone"
+          ele.attributes["value"] = @timezone
+          when "hidden"
+          ele.attributes["value"] = @hidden.to_s
+          when "color"
+          ele.attributes["value"] = @color
+          when "selected"
+          ele.attributes["value"] = @selected.to_s
+        end
+      end
+      xml.to_s
+    end
+    
+    #Loads the Calendar with returned data from Google Calendar feed.  Returns true if successful.
+    def load(string)
+      super(string)
+      @exists = true
+      @xml = string
+      xml = REXML::Document.new(string)
+      xml.root.elements.each(){}.map do |ele|
+        case ele.name
+          when "id"
+          @id = ele.text.gsub("www.google.com/calendar/feeds/default/calendars/", "")
+          when 'summary'
+          @summary = ele.text
+          when "color"
+          @color = ele.attributes['value']
+          when 'hidden'
+          @hidden = ele.attributes["value"] == "true" ? true : false
+          when 'timezone'
+          @timezone = ele.attributes["value"]
+          when "selected"
+          @selected = ele.attributes["value"] == "true" ? true : false
+          when "link"
+          if ele.attributes['rel'] == 'edit'
+            @edit_feed = ele.attributes['href']
+          end
+          when 'accesslevel'
+          @editable = (ele.attributes["value"] == 'editor' or ele.attributes["value"] == 'owner' or ele.attributes["value"] == 'root')
+        end
+      end
+      
+      if service.check_public
+        log("Getting ACL Feed")
+        
+        # If the ACL URI doesn't exist, then its definitely not public
+        if (@acl_uri == nil)
+          @public = false
+          return true
+        end
+        
+        #rescue error on shared calenar ACL list access
+        begin 
+          log("ACL URI: #{@acl_uri}")
+          ret = service.send_request(GData4Ruby::Request.new(:get, @acl_uri))
+        rescue Exception => e
+          log("ACL Feed Get Failed: #{e.inspect}")
+          @public = false
+          return true
+        end
+        r = REXML::Document.new(ret.read_body)
+        r.root.elements.each("entry") do |ele|
+          e = GData4Ruby::ACL::AccessRule.new(service.gdata_service, self)
+          ele = GData4Ruby::Utils.add_namespaces(ele)
+          e.load(ele.to_s)
+          log('ACL Rule: '+e.inspect)
+          @public = (e.role.include? 'read' and e.user == 'default')
+          log('Public: '+@public.to_s)
+          break if @public
+        end
+      else
+        @public = false
+      end
+      return true
+    end
+    
+    #Helper function to return a formatted iframe embedded google calendar.  Parameters are:
+    #1. *params*: a hash of parameters that affect the display of the embedded calendar.  Accepts any parameter that the google iframe recognizes.  Here are the most common:
+    #   height:: the height of the embedded calendar in pixels
+    #   width:: the width of the embedded calendar in pixels
+    #   title:: the title to display
+    #   bgcolor:: the background color.  Limited choices, see google docs for allowable values.
+    #   color:: the color of the calendar elements.  Limited choices, see google docs for allowable values.
+    #   showTitle:: set to '0' to hide the title
+    #   showDate:: set to '0' to hide the current date
+    #   showNav:: set to '0 to hide the navigation tools
+    #   showPrint:: set to '0' to hide the print icon
+    #   showTabs:: set to '0' to hide the tabs
+    #   showCalendars:: set to '0' to hide the calendars selection drop down
+    #   showTz:: set to '0' to hide the timezone selection
+    #   border:: the border width in pixels
+    #   dates:: a range of dates to display in the format of 'yyyymmdd/yyyymmdd'.  Example: 20090820/20091001
+    #   privateKey:: use to display a private calendar.  You can find this key under the calendar settings pane of the Google Calendar website.
+    #   ctz:: The timezone to convert event times to
+    def to_iframe(params = {})
+      params[:height] ||= "600"
+      params[:width] ||= "600"
+      params[:title] ||= (self.title ? self.title : '')
+      params[:bgcolor] ||= "#FFFFFF"
+      params[:color] ||= "#2952A3"
+      params[:border] ||= "0"
+      params.each{|key, value| params[key] = CGI::escape(value)}
+      output = "#{params.to_a.collect{|a| a.join("=")}.join("&")}"
+      
+      output += "&src=#{id}"
+      
+      "<iframe src='#{service.create_url("www.google.com/calendar/embed?"+output)}' style='#{params[:border]} px solid;' width='#{params[:width]}' height='#{params[:height]}' frameborder='#{params[:border]}' scrolling='no'></iframe>"  
+    end
+    
+    #Helper function to return a specified calendar id as a formatted iframe embedded google calendar.  This function does not require loading the calendar information from the Google calendar
+    #service, but does require you know the google calendar id. 
+    #1. *id*: the unique google assigned id for the calendar to display.
+    #2. *params*: a hash of parameters that affect the display of the embedded calendar.  Accepts any parameter that the google iframe recognizes.  Here are the most common:
+    #   height:: the height of the embedded calendar in pixels
+    #   width:: the width of the embedded calendar in pixels
+    #   title:: the title to display
+    #   bgcolor:: the background color.  Limited choices, see google docs for allowable values.
+    #   color:: the color of the calendar elements.  Limited choices, see google docs for allowable values.
+    #   showTitle:: set to '0' to hide the title
+    #   showDate:: set to '0' to hide the current date
+    #   showNav:: set to '0 to hide the navigation tools
+    #   showPrint:: set to '0' to hide the print icon
+    #   showTabs:: set to '0' to hide the tabs
+    #   showCalendars:: set to '0' to hide the calendars selection drop down
+    #   showTz:: set to '0' to hide the timezone selection
+    #   border:: the border width in pixels
+    #   dates:: a range of dates to display in the format of 'yyyymmdd/yyyymmdd'.  Example: 20090820/20091001
+    #   privateKey:: use to display a private calendar.  You can find this key under the calendar settings pane of the Google Calendar website.
+    def self.to_iframe(id, params = {})
+      params[:height] ||= "600"
+      params[:width] ||= "600"
+      params[:bgcolor] ||= "#FFFFFF"
+      params[:color] ||= "#2952A3"
+      params[:border] ||= "0"
+      params.each{|key, value| params[key] = CGI::escape(value)}
+      output = "#{params.to_a.collect{|a| a.join("=")}.join("&")}"
+      
+      output += "&src=#{id}"
+      
+      "<iframe src='#{service.create_url("www.google.com/calendar/embed?"+output)}' style='#{params[:border]} px solid;' width='#{params[:width]}' height='#{params[:height]}' frameborder='#{params[:border]}' scrolling='no'></iframe>"  
+    end
+    
+    private
+    def self.get_instance(service, d)
+      if d.is_a? Net::HTTPOK
+        xml = REXML::Document.new(d.read_body).root
+        if xml.name == 'feed'
+          xml = xml.elements.each("entry"){}[0]
+        end
+      else
+        xml = d
+      end
+      ele = GData4Ruby::Utils::add_namespaces(xml)
+      cal = Calendar.new(service)
+      cal.load(ele.to_s)
+      cal
+    end
+  end 
+end