intouch-gcal4ruby 0.5.7

data/CHANGELOG

@@ -0,0 +1,93 @@
+#=CHANGELOG
+#==version 0.5.8
+#* Calculate event feed URI instead of querying Google for content URI
+#* Expose calendar updated_at attribute
+#==version 0.5.7
+#* Support option to only get calendars with owner level access.
+#* Use https for all feeds.
+#==version 0.5.6
+#* Reformatted README. Thanks to SingAlong.
+#* Fixed recurrence time parsing when date only. Thanks to macovsky.
+#* Cleaned up gemspec.
+#==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 Service#to_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 Event#find 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 Calendar#load
+#==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.md

@@ -0,0 +1,131 @@
+#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](http://www.gnu.org/licenses/lgpl.html).
+
+##Website
+
+[http://cookingandcoding.com/gcal4ruby/](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
+
+1. Authenticate
+
+		service = Service.new
+    	service.authenticate("user@gmail.com", "password")
+
+2. Get Calendar List for all calendars
+
+    	calendars = service.calendars
+
+3. Get Calendar List for all calendars that the authenticated user has owner access level
+
+    	calendars = service.calendars(:only_owner_access_level => true)
+
+###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/calendar.rb

@@ -0,0 +1,375 @@
+# 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
+    ALL_CALENDARS_FEED = 'https://www.google.com/calendar/feeds/default/allcalendars/full'
+    OWN_CALENDARS_FEED = 'https://www.google.com/calendar/feeds/default/owncalendars/full'
+    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
+
+    #Timestamp when last updated
+    attr_reader :updated_at
+
+    #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
+      @updated_at = nil
+      @exists = false
+      @title ||= ""
+      @summary ||= ""
+      @public ||= false
+      @hidden ||= false
+      @timezone ||= "America/Los_Angeles"
+      @color ||= "#2952A3"
+      @where ||= ""
+      attributes.each do |key, value|
+        self.send("#{key}=", value)
+      end
+      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
+        puts 'setting calendar to public' if service.debug
+        rule = GData4Ruby::ACL::AccessRule.new(service, self)
+        rule.role = 'http://schemas.google.com/gCal/2005#read'
+        rule.save
+      else
+        rule = GData4Ruby::ACL::AccessRule.find(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, OWN_CALENDARS_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]
+        puts "id passed, finding calendar by id" if service.debug
+        puts "id = "+id if service.debug
+        d = service.send_request(GData4Ruby::Request.new(:get, "#{OWN_CALENDARS_FEED}/#{id}", {"If-Not-Match" => "*"}))
+        puts d.inspect if service.debug
+        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("http://www.google.com/calendar/feeds/default/calendars/", "")
+          when "updated"
+          @updated_at = Time.xmlschema ele.text
+          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
+        puts "Getting ACL Feed" if @service.debug
+        
+        #rescue error on shared calenar ACL list access
+        begin 
+          ret = @service.send_request(GData4Ruby::Request.new(:get, @acl_uri))
+        rescue Exception => e
+          puts "ACL Feed Get Failed: #{e.inspect}" if @service.debug
+          @public = false
+          return true
+        end
+        r = REXML::Document.new(ret.body)
+        r.root.elements.each("entry") do |ele|
+          e = GData4Ruby::ACL::AccessRule.new(service, self)
+          ele = GData4Ruby::Utils.add_namespaces(ele)
+          e.load(ele.to_s)
+          puts 'acl rule = '+e.inspect if service.debug
+          @public = (e.role.include? 'read' and e.user == 'default')
+          puts 'public = '+@public.to_s if service.debug
+          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='http://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='http://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.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