class Google::Event

Represents a Google Event.

Attributes

Attributes

attendees[RW]
calendar[RW]
color_id[RW]
creator_name[RW]
description[RW]
extended_properties[W]
guests_can_invite_others[RW]
guests_can_see_other_guests[RW]
id[R]
location[RW]
new_event_with_id_specified[RW]
quickadd[RW]
raw[R]
recurrence[W]
reminders[W]
send_notifications[RW]
status[R]
title[RW]
transparency[R]
visibility[R]

Public Class Methods

build_from_google_feed(response, calendar) click to toggle source

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

# File lib/google/event.rb, line 256
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(params = {}) click to toggle source

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 = {'freq' => '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 = {'useDefault' => false, 'overrides' => ['minutes' => 10, 'method' => “popup”]} event.attendees = [

  {'email' => 'some.a.one@gmail.com', 'displayName' => 'Some A One', 'responseStatus' => 'tentative'},
  {'email' => 'some.b.one@gmail.com', 'displayName' => 'Some B One', 'responseStatus' => 'tentative'}
]

event.extendedProperties = {'shared' => {'custom_str' => 'some custom string'}} event.guests_can_invite_others = false event.guests_can_see_other_guests = false event.send_notifications = true

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

Protected Class Methods

parse_id(id) click to toggle source

Validates id format

# File lib/google/event.rb, line 556
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) click to toggle source

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

# File lib/google/event.rb, line 526
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) click to toggle source

Parse recurrence rule Returns hash with recurrence info

# File lib/google/event.rb, line 503
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) click to toggle source

A utility method used centralize time parsing.

# File lib/google/event.rb, line 548
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) click to toggle source

Validates visibility value

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

Public Instance Methods

all_day=(time) click to toggle source

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.

# File lib/google/event.rb, line 131
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?() click to toggle source

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.

# File lib/google/event.rb, line 122
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() click to toggle source

Hash representation of attendees

# File lib/google/event.rb, line 313
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() click to toggle source

JSON representation of attendees

# File lib/google/event.rb, line 326
def attendees_json
  attendees_attributes.to_json
end
color_attributes() click to toggle source

Hash representation of colors

# File lib/google/event.rb, line 298
def color_attributes
  return {} unless color_id
  { "colorId" => "#{color_id}" }
end
color_json() click to toggle source

JSON representation of colors

# File lib/google/event.rb, line 306
def color_json
  color_attributes.to_json
end
delete() click to toggle source

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.
# File lib/google/event.rb, line 430
def delete
  @calendar.delete_event(self)
  @id = nil
end
duration() click to toggle source

Duration of the event in seconds

# File lib/google/event.rb, line 142
def duration
  Time.parse(end_time) - Time.parse(start_time)
end
end_time() click to toggle source

Get the end_time of the event.

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

# File lib/google/event.rb, line 107
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) click to toggle source

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

# File lib/google/event.rb, line 115
def end_time=(time)
  @end_time = Event.parse_time(time)
end
extended_properties() click to toggle source

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 = {'shared' => {'prop1' => 'value 1'}}

end

# File lib/google/event.rb, line 210
def extended_properties
  @extended_properties ||= {}
end
extended_properties_attributes() click to toggle source

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

# File lib/google/event.rb, line 396
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() click to toggle source

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

# File lib/google/event.rb, line 406
def extended_properties_json
  extended_properties_attributes.to_json
end
id=(id) click to toggle source

Sets the id of the Event.

# File lib/google/event.rb, line 81
def id=(id)
  @id = Event.parse_id(id) unless id.nil?
end
local_timezone_attributes() click to toggle source

Hash representation of local timezone

# File lib/google/event.rb, line 359
def local_timezone_attributes
  tz = Time.now.getlocal.zone
  tz_name = TimezoneParser::getTimezones(tz).last
  { "timeZone" => tz_name }
end
local_timezone_json() click to toggle source

JSON representation of local timezone

# File lib/google/event.rb, line 368
def local_timezone_json
  local_timezone_attributes.to_json
end
new_event?() click to toggle source

Returns true if this a new event.

# File lib/google/event.rb, line 445
def new_event?
  new_event_with_id_specified? || id == nil || id == ''
end
opaque?() click to toggle source

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

# File lib/google/event.rb, line 238
def opaque?
  @transparency == "opaque"
end
recurrence() click to toggle source

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 = {freq: "weekly", byday: "mo,tu,we,th,fr"}

end

# File lib/google/event.rb, line 189
def recurrence
  @recurrence ||= {}
end
recurrence_attributes() click to toggle source

Hash representation of recurrence rules for repeating events

# File lib/google/event.rb, line 375
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() click to toggle source

JSON representation of recurrence rules for repeating events

# File lib/google/event.rb, line 388
def recurrence_json
  recurrence_attributes.to_json
end
reminders() click to toggle source

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' => [{method: 'email', minutes: 4}, {method: 'popup', minutes: 60}, {method: 'sms', minutes: 30}]}

end

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

# File lib/google/event.rb, line 160
def reminders
  @reminders ||= {}
end
reminders_attributes() click to toggle source

Hash representation of a reminder

# File lib/google/event.rb, line 333
def reminders_attributes
  if reminders && reminders.is_a?(Hash) && reminders['overrides']

    { "useDefault" => false, "overrides" => reminders['overrides'] }
  else
    { "useDefault" => true}
  end
end
reminders_json() click to toggle source

JSON representation of a reminder

# File lib/google/event.rb, line 345
def reminders_json
  reminders_attributes.to_json
end
save() click to toggle source

Saves an event.

Note: make sure to set the calendar before calling this method.
# File lib/google/event.rb, line 421
def save
  update_after_save(@calendar.save_event(self))
end
send_notifications?() click to toggle source

Returns true if notifications were requested to be sent

# File lib/google/event.rb, line 452
def send_notifications?
  !!send_notifications
end
start_time() click to toggle source

Get the start_time of the event.

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

# File lib/google/event.rb, line 97
def start_time
  @start_time ||= Time.now.utc
  (@start_time.is_a? String) ? @start_time : @start_time.xmlschema
end
start_time=(time) click to toggle source

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

# File lib/google/event.rb, line 88
def start_time=(time)
  @start_time = Event.parse_time(time)
end
timezone_needed?() click to toggle source

Timezone info is needed only at recurring events

# File lib/google/event.rb, line 352
def timezone_needed?
  is_recurring_event?
end
to_json() click to toggle source

Google JSON representation of an event object.

# File lib/google/event.rb, line 264
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() click to toggle source

String representation of an event object.

# File lib/google/event.rb, line 413
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
transparency=(val) click to toggle source

Utility method that simplifies setting the transparency of an event. You can pass true or false. Defaults to transparent.

# File lib/google/event.rb, line 218
def transparency=(val)
  if val == false || val.to_s.downcase == 'opaque'
    @transparency = 'opaque'
  else
    @transparency = 'transparent'
  end
end
transparent?() click to toggle source

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

# File lib/google/event.rb, line 230
def transparent?
  @transparency == "transparent"
end
use_quickadd?() click to toggle source

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

# File lib/google/event.rb, line 438
def use_quickadd?
  quickadd && id == nil
end
visibility=(val) click to toggle source

Sets the visibility of the Event.

# File lib/google/event.rb, line 245
def visibility=(val)
  if val
    @visibility = Event.parse_visibility(val)
  else
    @visibility = "default"
  end
end

Protected Instance Methods

is_recurring_event?() click to toggle source

A utility method used to centralize checking for recurring events

# File lib/google/event.rb, line 541
def is_recurring_event? #:nodoc
  @recurrence && (@recurrence[:freq] || @recurrence['FREQ'] || @recurrence['freq'])
end

Private Instance Methods

new_event_with_id_specified?() click to toggle source
# File lib/google/event.rb, line 459
def new_event_with_id_specified?
  !!new_event_with_id_specified
end
time_or_all_day(time) click to toggle source
# File lib/google/event.rb, line 463
def time_or_all_day(time)
  time = Time.parse(time) if time.is_a? String

  if all_day?
    { "date" => time.strftime("%Y-%m-%d") }
  else
    { "dateTime" => time.xmlschema }
  end
end