Class: Osm::Api

Inherits:
Object
  • Object
show all
Defined in:
lib/osm/api.rb

Constant Summary collapse

@@default_cache_ttl = 
30 * 60
@@user_access =

The default caching time for responses from OSM (in seconds) Some things will only be cached for half this time Whereas others will be cached for twice this time Most items however will be cached for this time

Hash.new
@@cache_prepend_to_key = 
'OSMAPI'
@@cache = 
nil

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(userid = nil, secret = nil, site = @@api_site) ⇒ Object

Initialize a new API connection If passing user details then both must be passed

Parameters:

  • userid (String) (defaults to: nil) —

    osm userid of the user to act as

  • secret (String) (defaults to: nil) —

    osm secret of the user to act as

  • site (Symbol) (defaults to: @@api_site) —

    wether to use OSM (:scout) or OGM (:guide), defaults to the value set for the class

Raises:

  • (ArgumentError) 


30
31
32
33
34
35
36
37
38
39
 
# File 'lib/osm/api.rb', line 30

def initialize(userid=nil, secret=nil, site=@@api_site)
  raise ArgumentError, 'You must pass a secret if you are passing a userid' if secret.nil? && !userid.nil?
  raise ArgumentError, 'You must pass a userid if you are passing a secret' if userid.nil? && !secret.nil?
  raise ArgumentError, 'site is invalid, if passed it should be either :scout or :guide' unless [:scout, :guide].include?(site)

  @base_url = 'https://www.onlinescoutmanager.co.uk' if site == :scout
  @base_url = 'http://www.onlineguidemanager.co.uk' if site == :guide
  set_user(userid, secret)
  nil
end

Class Method Details

.api_id ⇒ String

Get the API ID used in this class

Returns:

  • (String) —

    the API ID



75
76
77
 
# File 'lib/osm/api.rb', line 75

def self.api_id
  return @@api_id
end

.api_name ⇒ String

Get the API name displayed in the External Access tab of OSM

Returns:

  • (String) —

    the API name



81
82
83
 
# File 'lib/osm/api.rb', line 81

def self.api_name
  return @@api_name
end

.configure(options) ⇒ Object

Configure the API options used by all instances of the class

Parameters:

  • options (Hash)

Options Hash (options):

  • :api_id (String) —

    the apiid given to you for using the OSM id

  • :api_token (String) —

    the token which goes with the above api

  • :api_name (String) —

    the name displayed in the External Access tab of OSM

  • :api_sate (Symbol) —

    wether to use OSM (if :scout) or OGM (if :guide)

  • :cache (Class) — default: optional —

    An instance of a cache class, must provide the methods (exist?, delete, write, read), for details see Rails.cache. Whilst this is optional you should remember that caching is required to use the OSM API.

  • :default_cache_ttl (Fixnum) — default: optional, default = 30.minutes —

    The default TTL value for the cache, note that some items are cached for twice this time and others are cached for half this time (in seconds)

  • :cache_prepend_to_key (String) — default: optional, default = 'OSMAPI' —

    Text to prepend to the key used to store data in the cache

Returns:

  • nil

Raises:

  • (ArgumentError) 


51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
 
# File 'lib/osm/api.rb', line 51

def self.configure(options)
  raise ArgumentError, ':api_id does not exist in options hash' if options[:api_id].nil?
  raise ArgumentError, ':api_token does not exist in options hash' if options[:api_token].nil?
  raise ArgumentError, ':api_name does not exist in options hash' if options[:api_name].nil?
  raise ArgumentError, ':api_site does not exist in options hash or is invalid, this should be set to either :scout or :guide' unless [:scout, :guide].include?(options[:api_site])
  raise ArgumentError, ':default_cache_ttl must be greater than 0' unless (options[:default_cache_ttl].nil? || options[:default_cache_ttl].to_i > 0)
  unless options[:cache].nil?
    [:exist?, :delete, :write, :read].each do |method|
      raise ArgumentError, ":cache must have a #{method} method" unless options[:cache].methods.include?(method)
    end
  end

  @@api_id = options[:api_id].to_s
  @@api_token = options[:api_token].to_s
  @@api_name = options[:api_name].to_s
  @@api_site = options[:api_site]
  @@default_cache_ttl = options[:default_cache_ttl].to_i unless options[:default_cache_ttl].nil?
  @@cache_prepend_to_key = options[:cache_prepend_to_key].to_s unless options[:cache_prepend_to_key].nil?
  @@cache = options[:cache]
  nil
end

Instance Method Details

#authorize(email, password) ⇒ Hash

Get the userid and secret to be able to act as a certain user on the OSM system Also set’s the ‘current user’

Parameters:

  • email (String) —

    the login email address of the user on OSM

  • password (String) —

    the login password of the user on OSM

Returns:

  • (Hash) —

    a hash containing the following keys:

    • ‘userid’ - the userid to use in future requests

    • ‘secret’ - the secret to use in future requests



92
93
94
95
96
97
98
99
100
 
# File 'lib/osm/api.rb', line 92

def authorize(email, password)
  api_data = {
    'email' => email,
    'password' => password,
  }
  data = perform_query('users.php?action=authorise', api_data)
  set_user(data['userid'], data['secret'])
  return data
end

#create_evening(section, meeting_date, api_data = {}) ⇒ Boolean

Create an evening in OSM

Parameters:

  • section_id (Fixnum) —

    the id of the section to add the term to

  • meeting_date (Date) —

    the date of the meeting

  • api_data (Hash) (defaults to: {})

Options Hash (api_data):

  • 'userid' (String) — default: optional —

    the OSM userid to make the request as

  • 'secret' (String) — default: optional —

    the OSM secret belonging to the above user

Returns:

  • (Boolean) —

    if the operation suceeded or not



508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
 
# File 'lib/osm/api.rb', line 508

def create_evening(section, meeting_date, api_data={})
  section_id = id_for_section(section)
  evening_api_data = {
    'meetingdate' => meeting_date.strftime('%Y-%m-%d'),
    'sectionid' => section_id,
    'activityid' => -1
  }

  data = perform_query("programme.php?action=addActivityToProgramme", api_data.merge(evening_api_data))

  # The cached programmes for the section will be out of date - remove them
  get_terms(api_data).each do |term|
    cache_delete("programme-#{term.section_id}-#{term.id}") if term.section_id == section_id
  end

  return data.is_a?(Hash) && (data['result'] == 0)
end

#get_activity(activity_id, version = nil, options = {}, api_data = {}) ⇒ Osm::Activity

Get activity details

Parameters:

  • activity_id (Fixnum) —

    the activity ID

  • version (Fixnum) (defaults to: nil) —

    the version of the activity to retreive, if nil the latest version will be assumed

  • options (Hash) (defaults to: {})
  • api_data (Hash) (defaults to: {})

Options Hash (options):

  • :no_cache (Boolean) — default: optional —

    if true then the data will be retreived from OSM not the cache

Options Hash (api_data):

  • 'userid' (String) — default: optional —

    the OSM userid to make the request as

  • 'secret' (String) — default: optional —

    the OSM secret belonging to the above user

Returns:



304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
 
# File 'lib/osm/api.rb', line 304

def get_activity(activity_id, version=nil, options={}, api_data={})
  if !options[:no_cache] && cache_exist?("activity-#{activity_id}-#{version}") && self.user_can_access?(:activity, activity_id, api_data)
    return cache_read("activity-#{activity_id}-#{version}")
  end

  data = nil
  if version.nil?
    data = perform_query("programme.php?action=getActivity&id=#{activity_id}", api_data)
  else
    data = perform_query("programme.php?action=getActivity&id=#{activity_id}&version=#{version}", api_data)
  end

  activity = Osm::Activity.new(data)
  cache_write("activity-#{activity_id}-#{nil}", activity, :expires_in => @@default_cache_ttl*2) if version.nil?
  cache_write("activity-#{activity_id}-#{activity.version}", activity, :expires_in => @@default_cache_ttl/2)
  self.user_can_access :activity, activity.id, api_data

  return activity
end

#get_api_access(section, options = {}, api_data = {}) ⇒ Array<Osm::ApiAccess>

Get API access details for a given section

Parameters:

  • section (Osm:Section, Fixnum) —

    the section (or its ID) to get the details for

  • options (Hash) (defaults to: {})
  • api_data (Hash) (defaults to: {})

Options Hash (options):

  • :no_cache (Boolean) — default: optional —

    if true then the data will be retreived from OSM not the cache

Options Hash (api_data):

  • 'userid' (String) — default: optional —

    the OSM userid to make the request as

  • 'secret' (String) — default: optional —

    the OSM secret belonging to the above user

Returns:



355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
 
# File 'lib/osm/api.rb', line 355

def get_api_access(section, options={}, api_data={})
  section_id = id_for_section(section)

  if !options[:no_cache] && cache_exist?("api_access-#{api_data['userid'] || @userid}-#{section_id}")
    return cache_read("api_access-#{api_data['userid'] || @userid}-#{section_id}")
  end

  data = perform_query("users.php?action=getAPIAccess&sectionid=#{section_id}", api_data)

  result = Array.new
  data['apis'].each do |item|
    this_item = Osm::ApiAccess.new(item)
    result.push this_item
    self.user_can_access(:programme, section_id, api_data) if this_item.can_read?(:programme)
    self.user_can_access(:member, section_id, api_data) if this_item.can_read?(:member)
    self.user_can_access(:badge, section_id, api_data) if this_item.can_read?(:badge)
    cache_write("api_access-#{api_data['userid'] || @userid}-#{section_id}-#{this_item.id}", this_item, :expires_in => @@default_cache_ttl*2)
  end

  return result
end

#get_due_badges(section, term = nil, options = {}, api_data = {}) ⇒ Osm::DueBadges

Get due badges

Parameters:

  • section (Osm:Section, Fixnum) —

    the section (or its ID) to get the due badges for

  • options (Hash) (defaults to: {})
  • api_data (Hash) (defaults to: {})

Options Hash (options):

  • :no_cache (Boolean) — default: optional —

    if true then the data will be retreived from OSM not the cache

Options Hash (api_data):

  • 'userid' (String) — default: optional —

    the OSM userid to make the request as

  • 'secret' (String) — default: optional —

    the OSM secret belonging to the above user

Returns:



429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
 
# File 'lib/osm/api.rb', line 429

def get_due_badges(section, term=nil, options={}, api_data={})
  section_id = id_for_section(section)
  term_id = id_for_term(term, section, api_data)

  if !options[:no_cache] && cache_exist?("due_badges-#{section_id}-#{term_id}") && self.user_can_access?(:badge, section_id, api_data)
    return cache_read("due_badges-#{section_id}-#{term_id}")
  end

  section_type = get_section(section_id, api_data).type.to_s
  data = perform_query("challenges.php?action=outstandingBadges&section=#{section_type}&sectionid=#{section_id}&termid=#{term_id}", api_data)

  data = Osm::DueBadges.new(data)
  self.user_can_access :badge, section_id, api_data
  cache_write("due_badges-#{section_id}-#{term_id}", data, :expires_in => @@default_cache_ttl*2)

  return data
end

#get_events(section, options = {}, api_data = {}) ⇒ Array<Osm::Event>

Get events

Parameters:

  • section (Osm:Section, Fixnum) —

    the section (or its ID) to get the events for

  • options (Hash) (defaults to: {})
  • api_data (Hash) (defaults to: {})

Options Hash (options):

  • :no_cache (Boolean) — default: optional —

    if true then the data will be retreived from OSM not the cache

Options Hash (api_data):

  • 'userid' (String) — default: optional —

    the OSM userid to make the request as

  • 'secret' (String) — default: optional —

    the OSM secret belonging to the above user

Returns:



403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
 
# File 'lib/osm/api.rb', line 403

def get_events(section, options={}, api_data={})
  section_id = id_for_section(section)

  if !options[:no_cache] && cache_exist?("events-#{section_id}") && self.user_can_access?(:programme, section_id, api_data)
    return cache_read("events-#{section_id}")
  end

  data = perform_query("events.php?action=getEvents&sectionid=#{section_id}", api_data)

  result = Array.new
  unless data['items'].nil?
    data['items'].each do |item|
      result.push Osm::Event.new(item)
    end
  end
  self.user_can_access :programme, section_id, api_data
  cache_write("events-#{section_id}", result, :expires_in => @@default_cache_ttl)

  return result
end

#get_groupings(section, options = {}, api_data = {}) ⇒ Array<Osm::Grouping>

Get the groupings (e.g. patrols, sixes, lodges) for a given section

Parameters:

  • section (Osm::Section, Fixnum) —

    the section to get the groupings for

  • options (Hash) (defaults to: {})
  • api_data (Hash) (defaults to: {})

Options Hash (options):

  • :no_cache (Boolean) — default: optional —

    if true then the data will be retreived from OSM not the cache

Options Hash (api_data):

  • 'userid' (String) — default: optional —

    the OSM userid to make the request as

  • 'secret' (String) — default: optional —

    the OSM secret belonging to the above user

Returns:



197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
 
# File 'lib/osm/api.rb', line 197

def get_groupings(section, options={}, api_data={})
  section_id = id_for_section(section)

  if !options[:no_cache] && cache_exist?("groupings-#{section_id}") && self.user_can_access?(:section, section_id, api_data)
    return cache_read("groupings-#{section_id}")
  end

  data = perform_query("users.php?action=getPatrols&sectionid=#{section_id}", api_data)

  result = Array.new
  data['patrols'].each do |item|
    grouping = Osm::Grouping.new(item)
    result.push grouping
    cache_write("grouping-#{grouping.id}", grouping, :expires_in => @@default_cache_ttl*2)
    self.user_can_access :grouping, grouping.id, api_data
  end
  cache_write("groupings-#{section_id}", result, :expires_in => @@default_cache_ttl*2)

  return result
end

#get_members(section, term = nil, options = {}, api_data = {}) ⇒ Array<Osm::Member>

Get members

Parameters:

  • section (Osm:Section, Fixnum) —

    the section (or its ID) to get the members for

  • term (Osm:Term, Fixnum) (defaults to: nil) —

    the term (or its ID) to get the members for, passing nil causes the current term to be used

  • options (Hash) (defaults to: {})
  • api_data (Hash) (defaults to: {})

Options Hash (options):

  • :no_cache (Boolean) — default: optional —

    if true then the data will be retreived from OSM not the cache

Options Hash (api_data):

  • 'userid' (String) — default: optional —

    the OSM userid to make the request as

  • 'secret' (String) — default: optional —

    the OSM secret belonging to the above user

Returns:



330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
 
# File 'lib/osm/api.rb', line 330

def get_members(section, term=nil, options={}, api_data={})
  section_id = id_for_section(section)
  term_id = id_for_term(term, section, api_data)

  if !options[:no_cache] && cache_exist?("members-#{section_id}-#{term_id}") && self.user_can_access?(:member, section_id, api_data)
    return cache_read("members-#{section_id}-#{term_id}")
  end

  data = perform_query("users.php?action=getUserDetails&sectionid=#{section_id}&termid=#{term_id}", api_data)

  result = Array.new
  data['items'].each do |item|
    result.push Osm::Member.new(item)
  end
  self.user_can_access :member, section_id, api_data
  cache_write("members-#{section_id}-#{term_id}", result, :expires_in => @@default_cache_ttl)

  return result
end

#get_notepad(section, options = {}, api_data = {}) ⇒ Object

Get the notepad for a specified section

Parameters:

  • section (Osm:Section, Fixnum) —

    the section (or its ID) to get the notepad for

  • options (Hash) (defaults to: {})
  • api_data (Hash) (defaults to: {})

Options Hash (options):

  • :no_cache (Boolean) — default: optional —

    if true then the data will be retreived from OSM not the cache

Options Hash (api_data):

  • 'userid' (String) — default: optional —

    the OSM userid to make the request as

  • 'secret' (String) — default: optional —

    the OSM secret belonging to the above user

Returns:

  • nil if an error occured or the user does not have access to that section

  • (String) —

    the content of the notepad otherwise



154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
 
# File 'lib/osm/api.rb', line 154

def get_notepad(section, options={}, api_data={})
  section_id = id_for_section(section)

  if !options[:no_cache] && cache_exist?("notepad-#{section_id}") && self.user_can_access?(:section, section_id, api_data)
    return cache_read("notepad-#{section_id}")
  end

  notepads = get_notepads(options, api_data)
  return nil unless notepads.is_a? Hash

  notepads.each_key do |key|
    return notepads[key] if key == section_id
  end

  return nil
end

#get_notepads(options = {}, api_data = {}) ⇒ Hash

Get the user’s notepads

Parameters:

  • options (Hash) (defaults to: {})
  • api_data (Hash) (defaults to: {})

Options Hash (options):

  • :no_cache (Boolean) — default: optional —

    if true then the data will be retreived from OSM not the cache

Options Hash (api_data):

  • 'userid' (String) — default: optional —

    the OSM userid to make the request as

  • 'secret' (String) — default: optional —

    the OSM secret belonging to the above user

Returns:

  • (Hash) —

    a hash (keys are section IDs, values are a string)



130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
 
# File 'lib/osm/api.rb', line 130

def get_notepads(options={}, api_data={})
  if !options[:no_cache] && cache_exist?("notepads-#{api_data[:userid] || @userid}")
    return cache_read("notepads-#{api_data[:userid] || @userid}")
  end

  notepads = perform_query('api.php?action=getNotepads', api_data)
  return {} unless notepads.is_a?(Hash)

  data = {}
  notepads.each do |key, value|
    data[key.to_i] = value
    cache_write("notepad-#{key}", value, :expires_in => @@default_cache_ttl*2)
  end

  cache_write("notepads-#{api_data[:userid] || @userid}", data, :expires_in => @@default_cache_ttl*2)
  return data
end

#get_our_api_access(section, options = {}, api_data = {}) ⇒ Osm::ApiAccess

Get our API access details for a given section

Parameters:

  • section (Osm:Section, Fixnum) —

    the section (or its ID) to get the details for

  • options (Hash) (defaults to: {})
  • api_data (Hash) (defaults to: {})

Options Hash (options):

  • :no_cache (Boolean) — default: optional —

    if true then the data will be retreived from OSM not the cache

Options Hash (api_data):

  • 'userid' (String) — default: optional —

    the OSM userid to make the request as

  • 'secret' (String) — default: optional —

    the OSM secret belonging to the above user

Returns:



382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
 
# File 'lib/osm/api.rb', line 382

def get_our_api_access(section, options={}, api_data={})
  section_id = id_for_section(section)

  if !options[:no_cache] && cache_exist?("api_access-#{api_data['userid'] || @userid}-#{section_id}-#{Osm::Api.api_id}")
    return cache_read("api_access-#{api_data['userid'] || @userid}-#{section_id}-#{Osm::Api.api_id}")
  end

  data = get_api_access(section_id, options)
  found = nil
  data.each do |item|
    found = item if item.our_api?
  end

  return found
end

#get_programme(section, term, options = {}, api_data = {}) ⇒ Array<Osm::Evening>

Get the programme for a given term

Parameters:

  • section (Osm:Section, Fixnum) —

    the section (or its ID) to get the programme for

  • term (Osm:term, Fixnum) —

    the term (or its ID) to get the programme for, passing nil causes the current term to be used

  • options (Hash) (defaults to: {})
  • api_data (Hash) (defaults to: {})

Options Hash (options):

  • :no_cache (Boolean) — default: optional —

    if true then the data will be retreived from OSM not the cache

Options Hash (api_data):

  • 'userid' (String) — default: optional —

    the OSM userid to make the request as

  • 'secret' (String) — default: optional —

    the OSM secret belonging to the above user

Returns:



270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
 
# File 'lib/osm/api.rb', line 270

def get_programme(section, term, options={}, api_data={})
  section_id = id_for_section(section)
  term_id = id_for_term(term, section, api_data)

  if !options[:no_cache] && cache_exist?("programme-#{section_id}-#{term_id}") && self.user_can_access?(:programme, section_id, api_data)
    return cache_read("programme-#{section_id}-#{term_id}")
  end

  data = perform_query("programme.php?action=getProgramme&sectionid=#{section_id}&termid=#{term_id}", api_data)

  result = Array.new
  data = {'items'=>[],'activities'=>{}} if data.is_a? Array
  self.user_can_access(:programme, section_id, api_data) unless data.is_a? Array
  items = data['items'] || []
  activities = data['activities'] || {}

  items.each do |item|
    evening = Osm::Evening.new(item, activities[item['eveningid']])
    result.push evening
    evening.activities.each do |activity|
      self.user_can_access :activity, activity.activity_id, api_data
    end
  end

  cache_write("programme-#{section_id}-#{term_id}", result, :expires_in => @@default_cache_ttl)
  return result
end

#get_register(section, term = nil, options = {}, api_data = {}) ⇒ Array<Hash>

Get register

Parameters:

  • section (Osm:Section, Fixnum) —

    the section (or its ID) to get the register for

  • section (Osm:Term, Fixnum) —

    the term (or its ID) to get the register for, passing nil causes the current term to be used

  • options (Hash) (defaults to: {})
  • api_data (Hash) (defaults to: {})

Options Hash (options):

  • :no_cache (Boolean) — default: optional —

    if true then the data will be retreived from OSM not the cache

Options Hash (api_data):

  • 'userid' (String) — default: optional —

    the OSM userid to make the request as

  • 'secret' (String) — default: optional —

    the OSM secret belonging to the above user

Returns:

  • (Array<Hash>) —

    representing the attendance of each member



481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
 
# File 'lib/osm/api.rb', line 481

def get_register(section, term=nil, options={}, api_data={})
  section_id = id_for_section(section)
  term_id = id_for_term(term, section, api_data)

  if !options[:no_cache] && cache_exist?("register-#{section_id}-#{term_id}") && self.user_can_access?(:register, section_id, api_data)
    return cache_read("register-#{section_id}-#{term_id}")
  end

  data = perform_query("users.php?action=register&sectionid=#{section_id}&termid=#{term_id}", api_data)

  data = data['items']
  data.each do |item|
    item = Osm::symbolize_hash(item)
    item[:scoutid] = item[:scoutid].to_i
    item[:sectionid] = item[:sectionid].to_i
    item[:patrolid] = item[:patrolid].to_i
  end
  self.user_can_access :register, section_id, api_data
  cache_write("register-#{section_id}-#{term_id}", data, :expires_in => @@default_cache_ttl/2)
  return data
end

#get_register_structure(section, term = nil, options = {}, api_data = {}) ⇒ Array<Hash>

Get register structure

Parameters:

  • section (Osm:Section, Fixnum) —

    the section (or its ID) to get the structure for

  • section (Osm:Term, Fixnum) —

    the term (or its ID) to get the structure for, passing nil causes the current term to be used

  • options (Hash) (defaults to: {})
  • api_data (Hash) (defaults to: {})

Options Hash (options):

  • :no_cache (Boolean) — default: optional —

    if true then the data will be retreived from OSM not the cache

Options Hash (api_data):

  • 'userid' (String) — default: optional —

    the OSM userid to make the request as

  • 'secret' (String) — default: optional —

    the OSM secret belonging to the above user

Returns:

  • (Array<Hash>) —

    representing the rows of the register



453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
 
# File 'lib/osm/api.rb', line 453

def get_register_structure(section, term=nil, options={}, api_data={})
  section_id = id_for_section(section)
  term_id = id_for_term(term, section, api_data)

  if !options[:no_cache] && cache_exist?("register_structure-#{section_id}-#{term_id}") && self.user_can_access?(:register, section_id, api_data)
    return cache_read("register_structure-#{section_id}-#{term_id}")
  end

  data = perform_query("users.php?action=registerStructure&sectionid=#{section_id}&termid=#{term_id}", api_data)

  data.each_with_index do |item, item_index|
    data[item_index] = item = Osm::symbolize_hash(item)
    item[:rows].each_with_index do |row, row_index|
      item[:rows][row_index] = row = Osm::symbolize_hash(row)
    end
  end
  self.user_can_access :register, section_id, api_data
  cache_write("register_structure-#{section_id}-#{term_id}", data, :expires_in => @@default_cache_ttl/2)

  return data
end

#get_roles(options = {}, api_data = {}) ⇒ Array<Osm::Role>

Get the user’s roles

Parameters:

  • options (Hash) (defaults to: {})
  • api_data (Hash) (defaults to: {})

Options Hash (options):

  • :no_cache (Boolean) — default: optional —

    if true then the data will be retreived from OSM not the cache

Options Hash (api_data):

  • 'userid' (String) — default: optional —

    the OSM userid to make the request as

  • 'secret' (String) — default: optional —

    the OSM secret belonging to the above user

Returns:



106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
 
# File 'lib/osm/api.rb', line 106

def get_roles(options={}, api_data={})

  if !options[:no_cache] && cache_exist?("roles-#{api_data[:userid] || @userid}")
    return cache_read("roles-#{api_data[:userid] || @userid}")
  end

  data = perform_query('api.php?action=getUserRoles', api_data)

  result = Array.new
  data.each do |item|
    role = Osm::Role.new(item)
    result.push role
    cache_write("section-#{role.section.id}", role.section, :expires_in => @@default_cache_ttl*2)
    self.user_can_access :section, role.section.id, api_data
  end
  cache_write("roles-#{api_data[:userid] || @userid}", result, :expires_in => @@default_cache_ttl*2)

  return result
end

#get_section(section_id, options = {}, api_data = {}) ⇒ Object

Get the section (and its configuration)

Parameters:

  • section_id (Fixnum) —

    the section id of the required section

  • options (Hash) (defaults to: {})
  • api_data (Hash) (defaults to: {})

Options Hash (options):

  • :no_cache (Boolean) — default: optional —

    if true then the data will be retreived from OSM not the cache

Options Hash (api_data):

  • 'userid' (String) — default: optional —

    the OSM userid to make the request as

  • 'secret' (String) — default: optional —

    the OSM secret belonging to the above user

Returns:

  • nil if an error occured or the user does not have access to that section

  • (Osm::Section) 


177
178
179
180
181
182
183
184
185
186
187
188
189
190
 
# File 'lib/osm/api.rb', line 177

def get_section(section_id, options={}, api_data={})
  if !options[:no_cache] && cache_exist?("section-#{section_id}") && self.user_can_access?(:section, section_id, api_data)
    return cache_read("section-#{section_id}")
  end

  roles = get_roles(options, api_data)
  return nil unless roles.is_a? Array

  roles.each do |role|
    return role.section if role.section.id == section_id
  end

  return nil
end

#get_term(term_id, options = {}, api_data = {}) ⇒ Object

Get a term

Parameters:

  • term_id (Fixnum) —

    the id of the required term

  • options (Hash) (defaults to: {})
  • api_data (Hash) (defaults to: {})

Options Hash (options):

  • :no_cache (Boolean) — default: optional —

    if true then the data will be retreived from OSM not the cache

Options Hash (api_data):

  • 'userid' (String) — default: optional —

    the OSM userid to make the request as

  • 'secret' (String) — default: optional —

    the OSM secret belonging to the above user

Returns:

  • nil if an error occured or the user does not have access to that term

  • (Osm::Term) 


249
250
251
252
253
254
255
256
257
258
259
260
261
262
 
# File 'lib/osm/api.rb', line 249

def get_term(term_id, options={}, api_data={})
  if !options[:no_cache] && cache_exist?("term-#{term_id}") && self.user_can_access?(:term, term_id, api_data)
    return cache_read("term-#{term_id}")
  end

  terms = get_terms(options)
  return nil unless terms.is_a? Array

  terms.each do |term|
    return term if term.id == term_id
  end

  return nil
end

#get_terms(options = {}, api_data = {}) ⇒ Array<Osm::Term>

Get the terms that the OSM user can access

Parameters:

  • options (Hash) (defaults to: {})
  • api_data (Hash) (defaults to: {})

Options Hash (options):

  • :no_cache (Boolean) — default: optional —

    if true then the data will be retreived from OSM not the cache

Options Hash (api_data):

  • 'userid' (String) — default: optional —

    the OSM userid to make the request as

  • 'secret' (String) — default: optional —

    the OSM secret belonging to the above user

Returns:



222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
 
# File 'lib/osm/api.rb', line 222

def get_terms(options={}, api_data={})
  if !options[:no_cache] && cache_exist?("terms-#{api_data[:userid] || @userid}")
    return cache_read("terms-#{api_data[:userid] || @userid}")
  end

  data = perform_query('api.php?action=getTerms', api_data)

  result = Array.new
  data.each_key do |key|
    data[key].each do |item|
      term = Osm::Term.new(item)
      result.push term
      cache_write("term-#{term.id}", term, :expires_in => @@default_cache_ttl*2)
      self.user_can_access :term, term.id, api_data
    end
  end

  cache_write("terms-#{api_data[:userid] || @userid}", result, :expires_in => @@default_cache_ttl*2)
  return result
end

#update_evening(evening, api_data = {}) ⇒ Boolean

Update an evening in OSM

Parameters:

  • evening (Osm::Evening) —

    the evening to update

  • api_data (Hash) (defaults to: {})

Options Hash (api_data):

  • 'userid' (String) — default: optional —

    the OSM userid to make the request as

  • 'secret' (String) — default: optional —

    the OSM secret belonging to the above user

Returns:

  • (Boolean) —

    if the operation suceeded or not



530
531
532
533
534
535
536
537
538
539
 
# File 'lib/osm/api.rb', line 530

def update_evening(evening, api_data={})
  response = perform_query("programme.php?action=editEvening", api_data.merge(evening.data_for_saving))

  # The cached programmes for the section will be out of date - remove them
  get_terms(api_data).each do |term|
    cache_delete("programme-#{term.section_id}-#{term.id}") if term.section_id == evening.section_id
  end

  return response.is_a?(Hash) && (response['result'] == 0)
end