class 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 thatGoogle
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 theGoogle
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.
Attributes
Public Class Methods
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
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
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
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 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
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
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
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
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
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
JSON representation of attendees
# File lib/google/event.rb, line 326 def attendees_json attendees_attributes.to_json end
Hash representation of colors
# File lib/google/event.rb, line 298 def color_attributes return {} unless color_id { "colorId" => "#{color_id}" } end
JSON representation of colors
# File lib/google/event.rb, line 306 def color_json color_attributes.to_json end
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 of the event in seconds
# File lib/google/event.rb, line 142 def duration Time.parse(end_time) - Time.parse(start_time) end
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
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
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
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
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
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
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
JSON representation of local timezone
# File lib/google/event.rb, line 368 def local_timezone_json local_timezone_attributes.to_json end
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
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
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
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
JSON representation of recurrence rules for repeating events
# File lib/google/event.rb, line 388 def recurrence_json recurrence_attributes.to_json end
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
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
JSON representation of a reminder
# File lib/google/event.rb, line 345 def reminders_json reminders_attributes.to_json end
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
Returns true if notifications were requested to be sent
# File lib/google/event.rb, line 452 def send_notifications? !!send_notifications end
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
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 info is needed only at recurring events
# File lib/google/event.rb, line 352 def timezone_needed? is_recurring_event? end
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
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
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
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
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
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
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
# File lib/google/event.rb, line 459 def new_event_with_id_specified? !!new_event_with_id_specified end
# 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