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

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

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.



87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
 
# File 'lib/gcal4ruby/calendar.rb', line 87

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

Instance Attribute Details

#color ⇒ Object

The calendar color. Must be one of these values.



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

def color
  @color
end

#editable ⇒ Object (readonly)

A flag indicating whether the calendar is editable by this account



80
81
82
 
# File 'lib/gcal4ruby/calendar.rb', line 80

def editable
  @editable
end

#hidden ⇒ Object

Boolean value indicating the calendar visibility



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

def hidden
  @hidden
end

#selected ⇒ Object

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



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

def selected
  @selected
end

#summary ⇒ Object

A short description of the calendar



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

def summary
  @summary
end

#timezone ⇒ Object

The calendar timezone



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

def timezone
  @timezone
end

#title ⇒ Object

The calendar title



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

def title
  @title
end

#updated_at ⇒ Object (readonly)

Timestamp when last updated



83
84
85
 
# File 'lib/gcal4ruby/calendar.rb', line 83

def updated_at
  @updated_at
end

#where ⇒ Object

The calendar geo location, if any



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

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) 


172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
 
# File 'lib/gcal4ruby/calendar.rb', line 172

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

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



347
348
349
350
351
352
353
354
355
356
357
358
359
 
# File 'lib/gcal4ruby/calendar.rb', line 347

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

Instance Method Details

#create ⇒ Object

Creates a new instance of the object



160
161
162
 
# File 'lib/gcal4ruby/calendar.rb', line 160

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

#events ⇒ Object

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



121
122
123
124
125
126
127
128
129
130
131
132
 
# File 'lib/gcal4ruby/calendar.rb', line 121

def events
  events = []
  ret = @service.send_request(GData4Ruby::Request.new(:get, @content_uri))
  REXML::Document.new(ret).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) 


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

def exists?
  return @exists
end

#load(string) ⇒ Object

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



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
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
 
# File 'lib/gcal4ruby/calendar.rb', line 236

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/", "")
      @id = @id.gsub("http://www.google.com/calendar/feeds/default/owncalendars/full/", "")
      @id = @id.gsub("http://www.google.com/calendar/feeds/default/allcalendars/full/", "")
      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)
    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

#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.



155
156
157
 
# File 'lib/gcal4ruby/calendar.rb', line 155

def public=(p)
  @public = p
end

#public? ⇒ Boolean

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

Returns:

  • (Boolean) 


116
117
118
 
# File 'lib/gcal4ruby/calendar.rb', line 116

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.



205
206
207
208
209
210
211
212
213
 
# File 'lib/gcal4ruby/calendar.rb', line 205

def reload
  return false if not @exists
  t = Calendar.find(service, {:id => @id})
  if t
    load(t.to_xml)
  else
    return false
  end
end

#save ⇒ Object

Saves the calendar.



136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
 
# File 'lib/gcal4ruby/calendar.rb', line 136

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

#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



313
314
315
316
317
318
319
320
321
322
323
324
325
326
 
# File 'lib/gcal4ruby/calendar.rb', line 313

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

#to_xml ⇒ Object

Returns the xml representation of the Calenar.



216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
 
# File 'lib/gcal4ruby/calendar.rb', line 216

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