class Google::Calendar
Calendar
is the main object you use to interact with events. use it to find, create, update and delete them.
Attributes
Public Class Methods
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¶ ↑
: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
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¶ ↑
: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
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
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
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
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
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
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
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
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 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 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 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 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
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
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
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
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
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 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
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
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
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
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
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
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