Class: Google::Event

Inherits:
Object
  • Object
show all
Defined in:
lib/google/event.rb

Overview

Represents a Google Event.

Attributes

  • id - The google assigned id of the event (nil until saved). Read Write.
  • status - The status of the event (confirmed, tentative or cancelled). Read only.
  • title - The title of the event. Read Write.
  • description - The content of the event. Read Write.
  • location - The location of the event. Read Write.
  • start_time - The start time of the event (Time object, defaults to now). Read Write.
  • end_time - The end time of the event (Time object, defaults to one hour from now). Read Write.
  • recurrence - A hash containing recurrence info for repeating events. Read write.
  • calendar - What calendar the event belongs to. Read Write.
  • all_day - Does the event run all day. Read Write.
  • quickadd - A string that Google parses when setting up a new event. If set and then saved it will take priority over any attributes you have set. Read Write.
  • reminders - A hash containing reminders. Read Write.
  • attendees - An array of hashes containing information about attendees. Read Write
  • transparency - Does the event 'block out space' on the calendar. Valid values are true, false or 'transparent', 'opaque'. Read Write.
  • duration - The duration of the event in seconds. Read only.
  • html_link - An absolute link to this event in the Google Calendar Web UI. Read only.
  • raw - The full google json representation of the event. Read only.
  • visibility - The visibility of the event ('default', 'public', 'private', 'confidential'). Read Write.
  • extended_properties - Custom properties which may be shared or private. Read Write
  • guests_can_invite_others - Whether attendees other than the organizer can invite others to the event (true, false). Read Write.
  • guests_can_see_other_guests - Whether attendees other than the organizer can see who the event's attendees are (true, false). Read Write.
  • send_notifications - Whether to send notifications about the event update (true, false). Write only.

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(params = {}) ⇒ Event

Create a new event, and optionally set it's attributes.

Example

event = Google::Event.new event.calendar = AnInstanceOfGoogleCalendaer event.id = "0123456789abcdefghijklmopqrstuv" event.start_time = Time.now event.end_time = Time.now + (60 * 60) event.recurrence = => 'monthly' event.title = "Go Swimming" event.description = "The polar bear plunge" event.location = "In the arctic ocean" event.transparency = "opaque" event.visibility = "public" event.reminders = => false, 'overrides' => ['minutes' => 10, 'method' => "popup"] event.attendees = [ => 'some.a.one@gmail.com', 'displayName' => 'Some A One', 'responseStatus' => 'tentative', => 'some.b.one@gmail.com', 'displayName' => 'Some B One', 'responseStatus' => 'tentative' ] event.extendedProperties = => {'custom_str' => 'some custom string'} event.guests_can_invite_others = false event.guests_can_see_other_guests = false event.send_notifications = true



67
68
69
70
71
72
73
74
75
76
77
 
# File 'lib/google/event.rb', line 67

def initialize(params = {})
  [:id, :status, :raw, :html_link, :title, :location, :calendar, :quickadd, :attendees, :description, :reminders, :recurrence, :start_time, :end_time, :color_id, :extended_properties, :guests_can_invite_others, :guests_can_see_other_guests, :send_notifications].each do |attribute|
    instance_variable_set("@#{attribute}", params[attribute])
  end

  self.visibility   = params[:visibility]
  self.transparency = params[:transparency]
  self.all_day      = params[:all_day] if params[:all_day]
  self.creator_name = params[:creator]['displayName'] if params[:creator]
  self.new_event_with_id_specified = !!params[:new_event_with_id_specified]
end

Instance Attribute Details

#attendees ⇒ Object

Returns the value of attribute attendees.



39
40
41
 
# File 'lib/google/event.rb', line 39

def attendees
  @attendees
end

#calendar ⇒ Object

Returns the value of attribute calendar.



39
40
41
 
# File 'lib/google/event.rb', line 39

def calendar
  @calendar
end

#color_id ⇒ Object

Returns the value of attribute color_id.



39
40
41
 
# File 'lib/google/event.rb', line 39

def color_id
  @color_id
end

#creator_name ⇒ Object

Returns the value of attribute creator_name.



39
40
41
 
# File 'lib/google/event.rb', line 39

def creator_name
  @creator_name
end

#description ⇒ Object

Returns the value of attribute description.



39
40
41
 
# File 'lib/google/event.rb', line 39

def description
  @description
end

#extended_properties ⇒ Object

Stores custom data within extended properties which can be shared or private.

Allowed contents: :private => a hash containing custom key/values (strings) private to the event OPTIONAL :shared => a hash containing custom key/values (strings) shared with others OPTIONAL

Note: Both private and shared can be specified at once

Example

event = cal.create_event do |e| e.title = 'Work-day Event' e.start_time = Time.now e.end_time = Time.now + (60 * 60) # seconds * min e.extended_properties = => {'prop1' => 'value 1'} end



211
212
213
 
# File 'lib/google/event.rb', line 211

def extended_properties
  @extended_properties ||= {}
end

#guests_can_invite_others ⇒ Object

Returns the value of attribute guests_can_invite_others.



39
40
41
 
# File 'lib/google/event.rb', line 39

def guests_can_invite_others
  @guests_can_invite_others
end

#guests_can_see_other_guests ⇒ Object

Returns the value of attribute guests_can_see_other_guests.



39
40
41
 
# File 'lib/google/event.rb', line 39

def guests_can_see_other_guests
  @guests_can_see_other_guests
end

#html_link ⇒ Object (readonly)

Returns the value of attribute html_link.



37
38
39
 
# File 'lib/google/event.rb', line 37

def html_link
  @html_link
end

#id ⇒ Object

Returns the value of attribute id.



37
38
39
 
# File 'lib/google/event.rb', line 37

def id
  @id
end

#location ⇒ Object

Returns the value of attribute location.



39
40
41
 
# File 'lib/google/event.rb', line 39

def location
  @location
end

#new_event_with_id_specified ⇒ Object

Returns the value of attribute new_event_with_id_specified.



39
40
41
 
# File 'lib/google/event.rb', line 39

def new_event_with_id_specified
  @new_event_with_id_specified
end

#quickadd ⇒ Object

Returns the value of attribute quickadd.



39
40
41
 
# File 'lib/google/event.rb', line 39

def quickadd
  @quickadd
end

#raw ⇒ Object (readonly)

Returns the value of attribute raw.



37
38
39
 
# File 'lib/google/event.rb', line 37

def raw
  @raw
end

#recurrence ⇒ Object

Stores recurrence rules for repeating events.

Allowed contents: :freq => frequence information ("daily", "weekly", "monthly", "yearly") REQUIRED :count => how many times the repeating event should occur OPTIONAL :until => Time class, until when the event should occur OPTIONAL :interval => how often should the event occur (every "2" weeks, ...) OPTIONAL :byday => if frequence is "weekly", contains ordered (starting with OPTIONAL Sunday)comma separated abbreviations of days the event should occur on ("su,mo,th") if frequence is "monthly", can specify which day of month the event should occur on ("2mo" - second Monday, "-1th" - last Thursday, allowed indices are 1,2,3,4,-1)

Note: The hash should not contain :count and :until keys simultaneously.

Example

event = cal.create_event do |e| e.title = 'Work-day Event' e.start_time = Time.now e.end_time = Time.now + (60 * 60) # seconds * min e.recurrence = "weekly", byday: "mo,tu,we,th,fr" end



190
191
192
 
# File 'lib/google/event.rb', line 190

def recurrence
  @recurrence ||= {}
end

#reminders ⇒ Object

Stores reminders for this event. Multiple reminders are allowed.

Examples

event = cal.create_event do |e| e.title = 'Some Event' e.start_time = Time.now + (60 * 10) e.end_time = Time.now + (60 * 60) # seconds * min e.reminders = { 'useDefault' => false, 'overrides' => ['email', minutes: 4, 'popup', minutes: 60, 'sms', minutes: 30]} end

event = Event.new :start_time => "2012-03-31", :end_time => "2012-04-03", :reminders => { 'useDefault' => false, 'overrides' => [=> 10, 'method' => "popup"]}



161
162
163
 
# File 'lib/google/event.rb', line 161

def reminders
  @reminders ||= {}
end

#send_notifications ⇒ Object

Returns the value of attribute send_notifications.



39
40
41
 
# File 'lib/google/event.rb', line 39

def send_notifications
  @send_notifications
end

#status ⇒ Object (readonly)

Returns the value of attribute status.



37
38
39
 
# File 'lib/google/event.rb', line 37

def status
  @status
end

#title ⇒ Object

Returns the value of attribute title.



39
40
41
 
# File 'lib/google/event.rb', line 39

def title
  @title
end

#transparency ⇒ Object

Returns the value of attribute transparency.



37
38
39
 
# File 'lib/google/event.rb', line 37

def transparency
  @transparency
end

#visibility ⇒ Object

Returns the value of attribute visibility.



37
38
39
 
# File 'lib/google/event.rb', line 37

def visibility
  @visibility
end

Class Method Details

.build_from_google_feed(response, calendar) ⇒ Object

Convenience method used to build an array of events from a Google feed.



257
258
259
260
 
# File 'lib/google/event.rb', line 257

def self.build_from_google_feed(response, calendar)
  events = response['items'] ? response['items'] : [response]
  events.collect {|e| new_from_feed(e, calendar)}.flatten
end

.new_from_feed(e, calendar) ⇒ Object

Create a new event from a google 'entry'



479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
 
# File 'lib/google/event.rb', line 479

def self.new_from_feed(e, calendar) #:nodoc:
  params = {}
  %w(id status description location creator transparency updated reminders attendees visibility).each do |p|
    params[p.to_sym] = e[p]
  end

  params[:raw] = e
  params[:calendar] = calendar
  params[:title] = e['summary']
  params[:color_id] = e['colorId']
  params[:extended_properties] = e['extendedProperties']
  params[:guests_can_invite_others] = e['guestsCanInviteOthers']
  params[:guests_can_see_other_guests] = e['guestsCanSeeOtherGuests']
  params[:html_link] = e['htmlLink']
  params[:start_time] = Event.parse_json_time(e['start'])
  params[:end_time] = Event.parse_json_time(e['end'])
  params[:recurrence] = Event.parse_recurrence_rule(e['recurrence'])

  Event.new(params)
end

.parse_id(id) ⇒ Object

Validates id format



557
558
559
560
561
562
563
 
# File 'lib/google/event.rb', line 557

def self.parse_id(id)
  if id.to_s =~ /\A[a-v0-9]{5,1024}\Z/
    id
  else
    raise ArgumentError, "Event ID is invalid. Please check Google documentation: https://developers.google.com/google-apps/calendar/v3/reference/events/insert"
  end
end

.parse_json_time(time_hash) ⇒ Object

A utility method used to centralize parsing of time in json format



527
528
529
530
531
532
533
534
535
536
537
 
# File 'lib/google/event.rb', line 527

def self.parse_json_time(time_hash) #:nodoc
  return nil unless time_hash

  if time_hash['date']
    Time.parse(time_hash['date']).utc
  elsif time_hash['dateTime']
    Time.parse(time_hash['dateTime']).utc
  else
    Time.now.utc
  end
end

.parse_recurrence_rule(recurrence_entry) ⇒ Object

Parse recurrence rule Returns hash with recurrence info



504
505
506
507
508
509
510
511
512
 
# File 'lib/google/event.rb', line 504

def self.parse_recurrence_rule(recurrence_entry)
  return {} unless recurrence_entry && recurrence_entry != []

  rrule = /(?<=RRULE:)(.*)(?="\])/.match(recurrence_entry.to_s).to_s
  rhash = Hash[*rrule.downcase.split(/[=;]/)]

  rhash[:until] = Time.parse(rhash[:until]) if rhash[:until]
  rhash
end

.parse_time(time) ⇒ Object

A utility method used centralize time parsing.

Raises:

  • (ArgumentError) 


549
550
551
552
 
# File 'lib/google/event.rb', line 549

def self.parse_time(time) #:nodoc
  raise ArgumentError, "Start Time must be either Time or String" unless (time.is_a?(String) || time.is_a?(Time))
  (time.is_a? String) ? Time.parse(time) : time.dup.utc
end

.parse_visibility(visibility) ⇒ Object

Validates visibility value

Raises:

  • (ArgumentError) 


568
569
570
571
 
# File 'lib/google/event.rb', line 568

def self.parse_visibility(visibility)
  raise ArgumentError, "Event visibility must be 'default', 'public', 'private' or 'confidential'." unless ['default', 'public', 'private', 'confidential'].include?(visibility)
  return visibility
end

Instance Method Details

#all_day=(time) ⇒ Object

Makes an event all day, by setting it's start time to the passed in time and it's end time 24 hours later. Note: this will clobber both the start and end times currently set.



132
133
134
135
136
137
138
 
# File 'lib/google/event.rb', line 132

def all_day=(time)
  if time.class == String
    time = Time.parse(time)
  end
  @start_time = time.strftime("%Y-%m-%d")
  @end_time = (time + 24*60*60).strftime("%Y-%m-%d")
end

#all_day? ⇒ Boolean

Returns whether the Event is an all-day event, based on whether the event starts at the beginning and ends at the end of the day.

Returns:

  • (Boolean) 


123
124
125
126
 
# File 'lib/google/event.rb', line 123

def all_day?
  time = (@start_time.is_a? String) ? Time.parse(@start_time) : @start_time.dup.utc
  duration % (24 * 60 * 60) == 0 && time == Time.local(time.year,time.month,time.day)
end

#attendees_attributes ⇒ Object

Hash representation of attendees



314
315
316
317
318
319
320
321
322
 
# File 'lib/google/event.rb', line 314

def attendees_attributes
  return {} unless @attendees

  attendees = @attendees.map do |attendee|
    attendee.select { |k,_v| ['displayName', 'email', 'responseStatus'].include?(k) }
  end

  { "attendees" => attendees }
end

#attendees_json ⇒ Object

JSON representation of attendees



327
328
329
 
# File 'lib/google/event.rb', line 327

def attendees_json
  attendees_attributes.to_json
end

#color_attributes ⇒ Object

Hash representation of colors



299
300
301
302
 
# File 'lib/google/event.rb', line 299

def color_attributes
  return {} unless color_id
  { "colorId" => "#{color_id}" }
end

#color_json ⇒ Object

JSON representation of colors



307
308
309
 
# File 'lib/google/event.rb', line 307

def color_json
  color_attributes.to_json
end

#delete ⇒ Object

Deletes an event. Note: If using this on an event you created without using a calendar object, make sure to set the calendar before calling this method.



431
432
433
434
 
# File 'lib/google/event.rb', line 431

def delete
  @calendar.delete_event(self)
  @id = nil
end

#duration ⇒ Object

Duration of the event in seconds



143
144
145
 
# File 'lib/google/event.rb', line 143

def duration
  Time.parse(end_time) - Time.parse(start_time)
end

#end_time ⇒ Object

Get the end_time of the event.

If no time is set (i.e. new event) it defaults to one hour in the future.



108
109
110
111
 
# File 'lib/google/event.rb', line 108

def end_time
  @end_time ||= Time.now.utc + (60 * 60) # seconds * min
  (@end_time.is_a? String) ? @end_time : @end_time.xmlschema
end

#end_time=(time) ⇒ Object

Sets the end time of the Event. Must be a Time object or a parse-able string representation of a time.



116
117
118
 
# File 'lib/google/event.rb', line 116

def end_time=(time)
  @end_time = Event.parse_time(time)
end

#extended_properties_attributes ⇒ Object

Hash representation of extended properties shared : whether this should handle shared or public properties



397
398
399
400
401
 
# File 'lib/google/event.rb', line 397

def extended_properties_attributes
  return {} unless @extended_properties && (@extended_properties['shared'] || @extended_properties['private'])

  { "extendedProperties" => @extended_properties.select {|k,_v| ['shared', 'private'].include?(k) } }
end

#extended_properties_json ⇒ Object

JSON representation of extended properties shared : whether this should handle shared or public properties



407
408
409
 
# File 'lib/google/event.rb', line 407

def extended_properties_json
  extended_properties_attributes.to_json
end

#local_timezone_attributes ⇒ Object

Hash representation of local timezone



360
361
362
363
364
 
# File 'lib/google/event.rb', line 360

def local_timezone_attributes
  tz = Time.now.getlocal.zone
  tz_name = TimezoneParser::getTimezones(tz).last
  { "timeZone" => tz_name }
end

#local_timezone_json ⇒ Object

JSON representation of local timezone



369
370
371
 
# File 'lib/google/event.rb', line 369

def local_timezone_json
  local_timezone_attributes.to_json
end

#new_event? ⇒ Boolean

Returns true if this a new event.

Returns:

  • (Boolean) 


446
447
448
 
# File 'lib/google/event.rb', line 446

def new_event?
  new_event_with_id_specified? || id == nil || id == ''
end

#opaque? ⇒ Boolean

Returns true if the event is opaque otherwise returns false. Opaque events block time on a calendar.

Returns:

  • (Boolean) 


239
240
241
 
# File 'lib/google/event.rb', line 239

def opaque?
  @transparency == "opaque"
end

#recurrence_attributes ⇒ Object

Hash representation of recurrence rules for repeating events



376
377
378
379
380
381
382
383
384
 
# File 'lib/google/event.rb', line 376

def recurrence_attributes
  return {} unless is_recurring_event?

  @recurrence[:until] = @recurrence[:until].strftime('%Y%m%dT%H%M%SZ') if @recurrence[:until]
  rrule = "RRULE:" + @recurrence.collect { |k,v| "#{k}=#{v}" }.join(';').upcase
  @recurrence[:until] = Time.parse(@recurrence[:until]) if @recurrence[:until]

  { "recurrence" => [rrule] }
end

#recurrence_json ⇒ Object

JSON representation of recurrence rules for repeating events



389
390
391
 
# File 'lib/google/event.rb', line 389

def recurrence_json
  recurrence_attributes.to_json
end

#reminders_attributes ⇒ Object

Hash representation of a reminder



334
335
336
337
338
339
340
341
 
# File 'lib/google/event.rb', line 334

def reminders_attributes
  if reminders && reminders.is_a?(Hash) && reminders['overrides']

    { "useDefault" => false, "overrides" => reminders['overrides'] }
  else
    { "useDefault" => true}
  end
end

#reminders_json ⇒ Object

JSON representation of a reminder



346
347
348
 
# File 'lib/google/event.rb', line 346

def reminders_json
  reminders_attributes.to_json
end

#save ⇒ Object

Saves an event. Note: make sure to set the calendar before calling this method.



422
423
424
 
# File 'lib/google/event.rb', line 422

def save
  update_after_save(@calendar.save_event(self))
end

#send_notifications? ⇒ Boolean

Returns true if notifications were requested to be sent

Returns:

  • (Boolean) 


453
454
455
 
# File 'lib/google/event.rb', line 453

def send_notifications?
  !!send_notifications
end

#start_time ⇒ Object

Get the start_time of the event.

If no time is set (i.e. new event) it defaults to the current time.



98
99
100
101
 
# File 'lib/google/event.rb', line 98

def start_time
  @start_time ||= Time.now.utc
  (@start_time.is_a? String) ? @start_time : @start_time.xmlschema
end

#start_time=(time) ⇒ Object

Sets the start time of the Event. Must be a Time object or a parse-able string representation of a time.



89
90
91
 
# File 'lib/google/event.rb', line 89

def start_time=(time)
  @start_time = Event.parse_time(time)
end

#timezone_needed? ⇒ Boolean

Timezone info is needed only at recurring events

Returns:

  • (Boolean) 


353
354
355
 
# File 'lib/google/event.rb', line 353

def timezone_needed?
  is_recurring_event?
end

#to_json ⇒ Object

Google JSON representation of an event object.



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
294
 
# File 'lib/google/event.rb', line 265

def to_json
  attributes = {
    "summary" => title,
    "visibility" => visibility,
    "transparency" => transparency,
    "description" => description,
    "location" => location,
    "start" => time_or_all_day(start_time),
    "end" => time_or_all_day(end_time),
    "reminders" => reminders_attributes,
    "guestsCanInviteOthers" => guests_can_invite_others,
    "guestsCanSeeOtherGuests" => guests_can_see_other_guests
  }

  if id
    attributes["id"] = id
  end

  if timezone_needed?
    attributes['start'].merge!(local_timezone_attributes)
    attributes['end'].merge!(local_timezone_attributes)
  end

  attributes.merge!(recurrence_attributes)
  attributes.merge!(color_attributes)
  attributes.merge!(attendees_attributes)
  attributes.merge!(extended_properties_attributes)

  JSON.generate attributes
end

#to_s ⇒ Object

String representation of an event object.



414
415
416
 
# File 'lib/google/event.rb', line 414

def to_s
  "Event Id '#{self.id}'\n\tStatus: #{status}\n\tTitle: #{title}\n\tStarts: #{start_time}\n\tEnds: #{end_time}\n\tLocation: #{location}\n\tDescription: #{description}\n\tColor: #{color_id}\n\n"
end

#transparent? ⇒ Boolean

Returns true if the event is transparent otherwise returns false. Transparent events do not block time on a calendar.

Returns:

  • (Boolean) 


231
232
233
 
# File 'lib/google/event.rb', line 231

def transparent?
  @transparency == "transparent"
end

#use_quickadd? ⇒ Boolean

Returns true if the event will use quickadd when it is saved.

Returns:

  • (Boolean) 


439
440
441
 
# File 'lib/google/event.rb', line 439

def use_quickadd?
  quickadd && id == nil
end