Class: Google::Calendar

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

Overview

Calendar is the main object you use to interact with events. use it to find, create, update and delete them.

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(params = {}, connection = nil) ⇒ Calendar

Setup and connect to the specified Google Calendar.

the +params+ paramater accepts

  • :client_id => the client ID that you received from Google after registering your application with them (console.developers.google.com/). REQUIRED

  • :client_secret => the client secret you received from Google after registering your application with them. REQUIRED

  • :redirect_url => the url where your users will be redirected to after they have successfully permitted access to their calendars. REQUIRED

  • :calendar => the id of the calendar you would like to work with (see Readme.rdoc for instructions on how to find yours). REQUIRED

  • :refresh_token => if a user has already given you access to their calendars, you can specify their refresh token here and you will be ‘logged on’ automatically (i.e. they don’t need to authorize access again). OPTIONAL

See Readme.rdoc or readme_code.rb for an explication on the OAuth2 authorization process.

Example

Google::Calendar.new(:client_id => YOUR_CLIENT_ID,

 :client_secret => YOUR_SECRET,
 :calendar => YOUR_CALENDAR_ID,
 :redirect_url => "http://myapplicationurl.com/"
)



29
30
31
32
 
# File 'lib/google/calendar.rb', line 29

def initialize(params={}, connection=nil)
  @connection = connection || Connection.factory(params)
  @id = params[:calendar]
end

Instance Attribute Details

#connection ⇒ Object (readonly)

Returns the value of attribute connection.



9
10
11
 
# File 'lib/google/calendar.rb', line 9

def connection
  @connection
end

#description ⇒ Object (readonly)

Returns the value of attribute description.



9
10
11
 
# File 'lib/google/calendar.rb', line 9

def description
  @description
end

#id ⇒ Object (readonly)

Returns the value of attribute id.



9
10
11
 
# File 'lib/google/calendar.rb', line 9

def id
  @id
end

#location ⇒ Object (readonly)

Returns the value of attribute location.



9
10
11
 
# File 'lib/google/calendar.rb', line 9

def location
  @location
end

#summary ⇒ Object (readonly)

Returns the value of attribute summary.



9
10
11
 
# File 'lib/google/calendar.rb', line 9

def summary
  @summary
end

#time_zone ⇒ Object (readonly)

Returns the value of attribute time_zone.



9
10
11
 
# File 'lib/google/calendar.rb', line 9

def time_zone
  @time_zone
end

Class Method Details

.create(params = {}, connection = nil) ⇒ Object

Setup, connect and create a Google Calendar.

the +params+ paramater accepts

  • :client_id => the client ID that you received from Google after registering your application with them (console.developers.google.com/). REQUIRED

  • :client_secret => the client secret you received from Google after registering your application with them. REQUIRED

  • :redirect_url => the url where your users will be redirected to after they have successfully permitted access to their calendars. REQUIRED

  • :summary => title of the calendar being created. OPTIONAL

  • :location => geographic location of the calendar as free-form text. OPTIONAL

  • :time_zone => the time zone of the calendar. (Formatted as an IANA Time Zone Database name, e.g. “Europe/Zurich”.) OPTIONAL

  • :description => description of the calendar. OPTIONAL

  • :refresh_token => if a user has already given you access to their calendars, you can specify their refresh token here and you will be ‘logged on’ automatically (i.e. they don’t need to authorize access again). OPTIONAL

See Readme.rdoc or readme_code.rb for an explication on the OAuth2 authorization process.

Example

Google::Calendar.create(

 :client_id => YOUR_CLIENT_ID,
 :client_secret => YOUR_SECRET,
 :summary => 'Test Calendar',
 :location => 'Somewhere',
 :description => 'Test Calendar Description',
 :time_zone => 'Europe/Zurich',
 :redirect_url => "http://myapplicationurl.com/"
)



59
60
61
62
63
64
65
66
67
 
# File 'lib/google/calendar.rb', line 59

def self.create(params={}, connection=nil)
  cal = new(params, connection)
  cal.instance_variable_set(:@summary, params[:summary])
  cal.instance_variable_set(:@location, params[:location])
  cal.instance_variable_set(:@description, params[:description])
  cal.instance_variable_set(:@time_zone, params[:time_zone])

  cal.save
end

.get(params = {}, connection = nil) ⇒ Object

Connect and retrieve a Google Calendar.

the +params+ paramater accepts

  • :client_id => the client ID that you received from Google after registering your application with them (console.developers.google.com/). REQUIRED

  • :client_secret => the client secret you received from Google after registering your application with them. REQUIRED

  • :redirect_url => the url where your users will be redirected to after they have successfully permitted access to their calendars. REQUIRED

  • :calendar => the id of the calendar you would like to work with (see Readme.rdoc for instructions on how to find yours). REQUIRED

  • :refresh_token => if a user has already given you access to their calendars, you can specify their refresh token here and you will be ‘logged on’ automatically (i.e. they don’t need to authorize access again). OPTIONAL

See Readme.rdoc or readme_code.rb for an explication on the OAuth2 authorization process.

Example

Google::Calendar.get(

 :client_id => YOUR_CLIENT_ID,
 :client_secret => YOUR_SECRET,
 :calendar => YOUR_CALENDAR_ID,
 :redirect_url => "http://myapplicationurl.com/"
)



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

def self.get(params={}, connection=nil)
  cal = new(params, connection)
  cal.retrieve_calendar
end

Instance Method Details

#access_token ⇒ Object

The current access token. Used during a session, typically expires in a hour.



162
163
164
 
# File 'lib/google/calendar.rb', line 162

def access_token
  @connection.access_token
end

#auth_code ⇒ Object

The single use auth code that google uses during the auth process.



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

def auth_code
  @connection.auth_code
end

#authorize_url ⇒ Object

The URL you need to send a user in order to let them grant you access to their calendars.



148
149
150
 
# File 'lib/google/calendar.rb', line 148

def authorize_url
  @connection.authorize_url
end

#create_event(&blk) ⇒ Object

Creates a new event and immediately saves it. Returns the event

Examples

# Use a block
cal.create_event do |e|
  e.title = "A New Event"
  e.where = "Room 101"
end

# Don't use a block (need to call save manually)
event  = cal.create_event
event.title = "A New Event"
event.where = "Room 101"
event.save



364
365
366
 
# File 'lib/google/calendar.rb', line 364

def create_event(&blk)
  setup_event(Event.new, &blk)
end

#delete_event(event) ⇒ Object

Deletes the specified event. This is a callback used by the Event class.



411
412
413
414
 
# File 'lib/google/calendar.rb', line 411

def delete_event(event)
  notifications = "sendNotifications=#{event.send_notifications?}"
  send_events_request("/#{event.id}?#{notifications}", :delete)
end

#destroy ⇒ Object

Destroy a Google Calendar.

See Readme.rdoc or readme_code.rb for an explication on the OAuth2 authorization process.

Example

google_calendar_object.destroy



141
142
143
 
# File 'lib/google/calendar.rb', line 141

def destroy
  send_calendar_request("/#{@id}", :delete)
end

#events ⇒ Object

Find all of the events associated with this calendar.

Returns:
 an empty array if nothing found.
 an array with one element if only one found.
 an array of events if many found.



221
222
223
 
# File 'lib/google/calendar.rb', line 221

def events
  event_lookup()
end

#find_event_by_id(id) ⇒ Object

Attempts to find the event specified by the id

Returns:
 an empty array if nothing found.
 an array with one element if only one found.
 an array of events if many found.



342
343
344
345
 
# File 'lib/google/calendar.rb', line 342

def find_event_by_id(id)
  return nil unless id
  event_lookup("/#{id}")
end

#find_events(query) ⇒ Object

This is equivalent to running a search in the Google calendar web application. Google does not provide a way to specify what attributes you would like to search (i.e. title), by default it searches everything. If you would like to find specific attribute value (i.e. title=Picnic), run a query and parse the results.

Note that it is not possible to query the extended properties using queries. If you need to do so, use the alternate methods find_events_by_extended_property and find_events_by_extended_property_in_range

Returns:
 an empty array if nothing found.
 an array with one element if only one found.
 an array of events if many found.



241
242
243
 
# File 'lib/google/calendar.rb', line 241

def find_events(query)
  event_lookup("?q=#{query}")
end

#find_events_by_extended_properties(extended_properties, options = {}) ⇒ Object

Find all events that match at least one of the specified extended properties.

the extended_properties parameter is set up the same way that it is configured when creating an event for example, providing the following hash { ‘shared’ => => ‘v1’, ‘p2’ => v2 } will return the list of events that contain either v1 for shared extended property p1 or v2 for p2.

the options parameter accepts :max_results => the maximum number of results to return defaults to 25 the largest number Google accepts is 2500 :order_by => how you would like the results ordered, can be either ‘startTime’ or ‘updated’. Defaults to ‘startTime’. Note: it must be ‘updated’ if expand_recurring_events is set to false. :expand_recurring_events => When set to true each instance of a recurring event is returned. Defaults to true.

Returns:
 an empty array if nothing found.
 an array with one element if only one found.
 an array of events if many found.



303
304
305
306
 
# File 'lib/google/calendar.rb', line 303

def find_events_by_extended_properties(extended_properties, options = {})
  query = "?" + parse_extended_properties(extended_properties) + parse_options(options)
  event_lookup(query)
end

#find_events_by_extended_properties_in_range(extended_properties, start_min, start_max, options = {}) ⇒ Object

Find all events that match at least one of the specified extended properties within a given time frame. The lower bound is inclusive, whereas the upper bound is exclusive. Events that overlap the range are included.

the extended_properties parameter is set up the same way that it is configured when creating an event for example, providing the following hash { ‘shared’ => => ‘v1’, ‘p2’ => v2 } will return the list of events that contain either v1 for shared extended property p1 or v2 for p2.

the options parameter accepts :max_results => the maximum number of results to return defaults to 25 the largest number Google accepts is 2500 :order_by => how you would like the results ordered, can be either ‘startTime’ or ‘updated’. Defaults to ‘startTime’. Note: it must be ‘updated’ if expand_recurring_events is set to false. :expand_recurring_events => When set to true each instance of a recurring event is returned. Defaults to true.

Returns:
 an empty array if nothing found.
 an array with one element if only one found.
 an array of events if many found.



327
328
329
330
331
332
333
 
# File 'lib/google/calendar.rb', line 327

def find_events_by_extended_properties_in_range(extended_properties, start_min, start_max, options = {})
  formatted_start_min = encode_time(start_min)
  formatted_start_max = encode_time(start_max)
  base_query = parse_extended_properties(extended_properties) + parse_options(options)
  query = "?" + base_query + (base_query.empty? ? '' : '&') + "timeMin=#{formatted_start_min}&timeMax=#{formatted_start_max}"
  event_lookup(query)
end

#find_events_in_range(start_min, start_max, options = {}) ⇒ Object

Find all of the events associated with this calendar that start in the given time frame. The lower bound is inclusive, whereas the upper bound is exclusive. Events that overlap the range are included.

the options parameter accepts :max_results => the maximum number of results to return defaults to 25 the largest number Google accepts is 2500 :order_by => how you would like the results ordered, can be either ‘startTime’ or ‘updated’. Defaults to ‘startTime’. Note: it must be ‘updated’ if expand_recurring_events is set to false. :expand_recurring_events => When set to true each instance of a recurring event is returned. Defaults to true.

Returns:
 an empty array if nothing found.
 an array with one element if only one found.
 an array of events if many found.



260
261
262
263
264
265
 
# File 'lib/google/calendar.rb', line 260

def find_events_in_range(start_min, start_max, options = {})
  formatted_start_min = encode_time(start_min)
  formatted_start_max = encode_time(start_max)
  query = "?timeMin=#{formatted_start_min}&timeMax=#{formatted_start_max}#{parse_options(options)}"
  event_lookup(query)
end

#find_future_events(options = {}) ⇒ Object

Find all events that are occurring at the time the method is run or later.

the options parameter accepts :max_results => the maximum number of results to return defaults to 25 the largest number Google accepts is 2500 :order_by => how you would like the results ordered, can be either ‘startTime’ or ‘updated’. Defaults to ‘startTime’. Note: it must be ‘updated’ if expand_recurring_events is set to false. :expand_recurring_events => When set to true each instance of a recurring event is returned. Defaults to true.

Returns:
 an empty array if nothing found.
 an array with one element if only one found.
 an array of events if many found.



280
281
282
283
284
 
# File 'lib/google/calendar.rb', line 280

def find_future_events(options={})
  formatted_start_min = encode_time(Time.now)
  query = "?timeMin=#{formatted_start_min}#{parse_options(options)}"
  event_lookup(query)
end

#find_or_create_event_by_id(id, &blk) ⇒ Object

Looks for the specified event id. If it is found it, updates it’s vales and returns it. If the event is no longer on the server it creates a new one with the specified values. Works like the create_event method.



374
375
376
377
378
379
380
381
382
383
384
385
386
 
# File 'lib/google/calendar.rb', line 374

def find_or_create_event_by_id(id, &blk)      
  event = id ? find_event_by_id(id)[0] : nil

  if event
    setup_event(event, &blk)
  elsif id
    event = Event.new(id: id, new_event_with_id_specified: true)
    setup_event(event, &blk)
  else
    event = Event.new
    setup_event(event, &blk)
  end
end

#login_with_auth_code(auth_code) ⇒ Object

Convenience method used to streamline the process of logging in with a auth code.



176
177
178
 
# File 'lib/google/calendar.rb', line 176

def (auth_code)
  @connection.(auth_code)
end

#login_with_refresh_token(refresh_token) ⇒ Object

Convenience method used to streamline the process of logging in with a refresh token.



183
184
185
 
# File 'lib/google/calendar.rb', line 183

def (refresh_token)
  @connection.(refresh_token)
end

#refresh_token ⇒ Object

The refresh token is used to obtain a new access token. It remains valid until a user revokes access.



169
170
171
 
# File 'lib/google/calendar.rb', line 169

def refresh_token
  @connection.refresh_token
end

#retrieve_calendar ⇒ Object

Get an existing calender.

Returns:
 the calendar that was requested.



202
203
204
205
206
207
208
209
210
211
212
 
# File 'lib/google/calendar.rb', line 202

def retrieve_calendar
  response = send_calendar_request("/#{@id}", :get)
  @raw = JSON.parse(response.body)
  instance_variable_set(:@summary, @raw['summary'])
  instance_variable_set(:@location, @raw['location'])
  instance_variable_set(:@description, @raw['description'])
  instance_variable_set(:@time_zone, @raw['timeZone'])
  @html_link = @raw['htmlLink']

  self
end

#save ⇒ Object

Save a new calender.

Returns:
 the calendar that was saved.



192
193
194
195
 
# File 'lib/google/calendar.rb', line 192

def save
  response = send_calendar_request("/", :post, {:summary => @summary}.to_json)     
  update_after_save(response)
end

#save_event(event) ⇒ Object

Saves the specified event. This is a callback used by the Event class.



392
393
394
395
396
397
398
399
400
401
402
403
404
405
 
# File 'lib/google/calendar.rb', line 392

def save_event(event)
  method = event.new_event? ? :post : :put
  body = event.use_quickadd? ? nil : event.to_json
  notifications = "sendNotifications=#{event.send_notifications?}"
  query_string =  if event.use_quickadd?
                    "/quickAdd?#{notifications}&text=#{event.title}"
                  elsif event.new_event?
                    "?#{notifications}"
                  else # update existing event.
                    "/#{event.id}?#{notifications}"
                  end

  send_events_request(query_string, method, body)
end

#update(params = {}) ⇒ Object

Connect and update a Google Calendar.

the +params+ paramater accepts

  • :summary => title of the calendar being created. OPTIONAL

  • :location => geographic location of the calendar as free-form text. OPTIONAL

  • :time_zone => the time zone of the calendar. (Formatted as an IANA Time Zone Database name, e.g. “Europe/Zurich”.) OPTIONAL

  • :description => description of the calendar. OPTIONAL

  • :refresh_token => if a user has already given you access to their calendars, you can specify their refresh token here and you will be ‘logged on’ automatically (i.e. they don’t need to authorize access again). OPTIONAL

See Readme.rdoc or readme_code.rb for an explication on the OAuth2 authorization process.

Example

google_calendar_object.update(

 :summary => 'Test Calendar',
 :location => 'Somewhere',
 :description => 'Test Calendar Description',
 :time_zone => 'Europe/Zurich',
)



112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
 
# File 'lib/google/calendar.rb', line 112

def update(params={})
  instance_variable_set(:@summary, params[:summary])
  instance_variable_set(:@location, params[:location])
  instance_variable_set(:@description, params[:description])
  instance_variable_set(:@time_zone, params[:time_zone])

  response =
    send_calendar_request(
                          "/#{@id}", 
                          :put, 
                          {
                           summary: @summary,
                           location: @location,
                           description: @description,
                           timeZone: @time_zone,
                          }.to_json
                         )
  @raw = JSON.parse(response.body)
  self
end