Class: GCal4Ruby::Calendar

Inherits:
GData4Ruby::GDataObject
  • Object
show all
Defined in:
lib/gcal4ruby/calendar.rb

Overview

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, => cal_id)

  3. Get all calendar events cal = Calendar.find(service, => cal_id) events = cal.events

  4. Find an existing calendar by title cal = Calendar.find(service, => “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.

Constant Summary collapse

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>"

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(service, attributes = {}) ⇒ Calendar

Accepts a Service object and an optional attributes hash for initialization. Returns the new Calendar if successful, otherwise raises the InvalidService error.



81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
 
# File 'lib/gcal4ruby/calendar.rb', line 81

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 ||= ""
  @permissions = ''
  attributes.each do |key, value|
    self.send("#{key}=", value)
  end
  return true
end

Instance Attribute Details

#color ⇒ Object

The calendar color. Must be one of these values.



68
69
70
 
# File 'lib/gcal4ruby/calendar.rb', line 68

def color
  @color
end

#editable ⇒ Object (readonly)

A flag indicating whether the calendar is editable by this account



77
78
79
 
# File 'lib/gcal4ruby/calendar.rb', line 77

def editable
  @editable
end

#hidden ⇒ Object

Boolean value indicating the calendar visibility



62
63
64
 
# File 'lib/gcal4ruby/calendar.rb', line 62

def hidden
  @hidden
end

#selected ⇒ Object

A boolean value indicating whether the calendar appears by default when viewed online



74
75
76
 
# File 'lib/gcal4ruby/calendar.rb', line 74

def selected
  @selected
end

#summary ⇒ Object

A short description of the calendar



59
60
61
 
# File 'lib/gcal4ruby/calendar.rb', line 59

def summary
  @summary
end

#timezone ⇒ Object

The calendar timezone



65
66
67
 
# File 'lib/gcal4ruby/calendar.rb', line 65

def timezone
  @timezone
end

#where ⇒ Object

The calendar geo location, if any



71
72
73
 
# File 'lib/gcal4ruby/calendar.rb', line 71

def where
  @where
end

Class Method Details

.find(service, query, args = {}) ⇒ Object

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 code.google.com/apis/gdata/docs/2.0/reference.html#Queries for a full list of possible values. Example:

=> ‘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.

Raises:

  • (ArgumentError) 


152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
 
# File 'lib/gcal4ruby/calendar.rb', line 152

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, CALENDAR_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[:query]
      else
        results << cal if cal.title.downcase.include? query.downcase
      end
    end
    service.check_public = old_public
    return results
  end
  return false
end

.to_iframe(id, params = {}) ⇒ Object

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.



324
325
326
327
328
329
330
331
332
333
334
335
 
# File 'lib/gcal4ruby/calendar.rb', line 324

def self.to_iframe(id, params = {})
  params[:height] ||= "600"
  params[:width] ||= "600"
  params[:bgcolor] ||= "#FFFFFF"
  params[:color] ||= "#2952A3"
  params[:border] ||= "0"
  output = "?#{params.to_a.collect{|a| a.join("=")}.join("&")}&"

  output += "src=#{id}&color=#{params[:color]}"
      
  "<iframe src='http://www.google.com/calendar/embed?#{CGI.escape(output)}' style='#{params[:border]} px solid;' width='#{params[:width]}' height='#{params[:height]}' frameborder='#{params[:border]}' scrolling='no'></iframe>"  
end

Instance Method Details

#create ⇒ Object

Creates a new instance of the object



140
141
142
 
# File 'lib/gcal4ruby/calendar.rb', line 140

def create
  return service.send_request(GData4Ruby::Request.new(:post, CALENDAR_FEED, to_xml()))
end

#events ⇒ Object

Returns an array of Event objects corresponding to each event in the calendar.



115
116
117
118
119
120
121
122
123
124
125
126
 
# File 'lib/gcal4ruby/calendar.rb', line 115

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

#exists? ⇒ Boolean

Returns true if the calendar exists on the Google Calendar system (i.e. was loaded or has been saved). Otherwise returns false.

Returns:

  • (Boolean) 


105
106
107
 
# File 'lib/gcal4ruby/calendar.rb', line 105

def exists?
  return @exists
end

#load(string) ⇒ Object

Loads the Calendar with returned data from Google Calendar feed. Returns true if successful.



218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
 
# File 'lib/gcal4ruby/calendar.rb', line 218

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 '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.read_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)
      @public == (e.role.include? 'read' and e.user == 'default')
      break if @public
    end
  else
    @public = false
  end
  return true
end

#public=(p) ⇒ Object

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.



131
132
133
134
135
136
137
 
# File 'lib/gcal4ruby/calendar.rb', line 131

def public=(p)
  if p
    @permissions = 'http://schemas.google.com/gCal/2005#read' 
  else
    @permissions = 'none'
  end
end

#public? ⇒ Boolean

Returns true if the calendar is publically accessable, otherwise returns false.

Returns:

  • (Boolean) 


110
111
112
 
# File 'lib/gcal4ruby/calendar.rb', line 110

def public?
  return @public
end

#reload ⇒ Object

Reloads the calendar objects information from the stored server version. Returns true if successful, otherwise returns false. Any information not saved will be overwritten.



185
186
187
188
189
190
191
192
193
 
# File 'lib/gcal4ruby/calendar.rb', line 185

def reload
  return false if not @exists
  t = self.find(service, @id)
  if t
    load(t.to_xml)
  else
    return false
  end
end

#to_iframe(params = {}) ⇒ Object

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



289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
 
# File 'lib/gcal4ruby/calendar.rb', line 289

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"
  puts "params = #{params.inspect}" if service.debug
  output = "?#{params.to_a.collect{|a| a.join("=")}.join("&")}&"
  puts "param_string = #{output}" if service.debug

  output += "src=#{@id}&color=#{params[:color]}"
      
  "<iframe src='http://www.google.com/calendar/embed?#{CGI.escape(output)}' style='#{params[:border]} px solid;' width='#{params[:width]}' height='#{params[:height]}' frameborder='#{params[:border]}' scrolling='no'></iframe>"  
end

#to_xml ⇒ Object

Returns the xml representation of the Calenar.



196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
 
# File 'lib/gcal4ruby/calendar.rb', line 196

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
    when 'role'
      ele.attributes['value'] = @permissions
    end
  end
  xml.to_s
end