class Google::Calendar

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

Attributes

connection[R]
description[R]
id[R]
location[R]
summary[R]
time_zone[R]

Public Class Methods

create(params={}, connection=nil) click to toggle source

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. Use 'urn:ietf:wg:oauth:2.0:oob' if you are using an 'application'“ 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 => "urn:ietf:wg:oauth:2.0:oob" # this is what Google uses for 'applications'
)
# 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) click to toggle source

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. Use 'urn:ietf:wg:oauth:2.0:oob' if you are using an 'application'“ 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 => "urn:ietf:wg:oauth:2.0:oob" # this is what Google uses for 'applications'
)
# File lib/google/calendar.rb, line 88
def self.get(params={}, connection=nil)
  cal = new(params, connection)
  cal.retrieve_calendar
end
new(params={}, connection=nil) click to toggle source

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. Use 'urn:ietf:wg:oauth:2.0:oob' if you are using an 'application'“ 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 => "urn:ietf:wg:oauth:2.0:oob" # this is what Google uses for 'applications'
)
# File lib/google/calendar.rb, line 29
def initialize(params={}, connection=nil)
  @connection = connection || Connection.factory(params)
  @id = params[:calendar]
end

Public Instance Methods

access_token() click to toggle source

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

# File lib/google/calendar.rb, line 162
def access_token
  @connection.access_token
end
auth_code() click to toggle source

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

# File lib/google/calendar.rb, line 155
def auth_code
  @connection.auth_code
end
authorize_url() click to toggle source

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

# File lib/google/calendar.rb, line 148
def authorize_url
  @connection.authorize_url
end
create_event(&blk) click to toggle source

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
# File lib/google/calendar.rb, line 364
def create_event(&blk)
  setup_event(Event.new, &blk)
end
delete_event(event) click to toggle source

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

# 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() click to toggle source

Destroy a Google Calendar.

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

Example

google_calendar_object.destroy

# File lib/google/calendar.rb, line 141
def destroy
  send_calendar_request("/#{@id}", :delete)
end
events() click to toggle source

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.
# File lib/google/calendar.rb, line 221
def events
  event_lookup()
end
find_event_by_id(id) click to toggle source

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.
# File lib/google/calendar.rb, line 342
def find_event_by_id(id)
  return nil unless id
  event_lookup("/#{id}")
end
find_events(query) click to toggle source

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.
# File lib/google/calendar.rb, line 241
def find_events(query)
  event_lookup("?q=#{query}")
end
find_events_by_extended_properties(extended_properties, options = {}) click to toggle source

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' => {'p1' => '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.
# 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 = {}) click to toggle source

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' => {'p1' => '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.
# 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 = {}) click to toggle source

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.
# 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={}) click to toggle source

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.
# 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) click to toggle source

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.

# 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) click to toggle source

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

# File lib/google/calendar.rb, line 176
def login_with_auth_code(auth_code)
  @connection.login_with_auth_code(auth_code)
end
login_with_refresh_token(refresh_token) click to toggle source

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

# File lib/google/calendar.rb, line 183
def login_with_refresh_token(refresh_token)
  @connection.login_with_refresh_token(refresh_token)
end
refresh_token() click to toggle source

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

# File lib/google/calendar.rb, line 169
def refresh_token
  @connection.refresh_token
end
retrieve_calendar() click to toggle source

Get an existing calender.

Returns:
 the calendar that was requested.
# 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() click to toggle source

Save a new calender.

Returns:
 the calendar that was saved.
# 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) click to toggle source

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

# 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={}) click to toggle source

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',
)
# 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

Protected Instance Methods

parse_extended_properties(extended_properties) click to toggle source

Utility method used to centralize the parsing of extended query parameters.

# File lib/google/calendar.rb, line 447
def parse_extended_properties(extended_properties) # :nodoc
  query_parts = []
  ['shared', 'private'].each do |prop_type|
    next unless extended_properties[prop_type]
    query_parts << extended_properties[prop_type].map {|key, value| (prop_type == "shared" ? "sharedExtendedProperty=" : "privateExtendedProperty=") + "#{key}%3D#{value}" }.join("&")
  end
  query_parts.join('&')
end
parse_options(options) click to toggle source

Utility method used to centralize the parsing of common query parameters.

# File lib/google/calendar.rb, line 433
def parse_options(options) # :nodoc
  options[:max_results] ||=  25
  options[:order_by] ||= 'startTime' # other option is 'updated'
  options[:expand_recurring_events] ||= true
  query_string = "&orderBy=#{options[:order_by]}"
  query_string << "&maxResults=#{options[:max_results]}"
  query_string << "&singleEvents=#{options[:expand_recurring_events]}"
  query_string << "&q=#{options[:query]}" unless options[:query].nil?
  query_string
end
send_calendar_request(path_and_query_string, method, content = '') click to toggle source

Wraps the `send` method. Send a calendar related request to Google.

# File lib/google/calendar.rb, line 494
def send_calendar_request(path_and_query_string, method, content = '')
  @connection.send("/calendars#{path_and_query_string}", method, content)
end
send_events_request(path_and_query_string, method, content = '') click to toggle source

Wraps the `send` method. Send an event related request to Google.

# File lib/google/calendar.rb, line 501
def send_events_request(path_and_query_string, method, content = '')
  @connection.send("/calendars/#{CGI::escape @id}/events#{path_and_query_string}", method, content)
end