osm 0.0.26 → 0.1.0

data/lib/osm/flexi_record.rb

@@ -0,0 +1,131 @@
+module Osm
+
+  class FlexiRecord
+
+    # Get structure for a flexi record
+    # @param [Osm::Api] api The api to use to make the request
+    # @param [Osm::Section, Fixnum] section the section (or its ID) to get the structure for
+    # @param [Fixnum] the id of the Flexi Record
+    # @!macro options_get
+    # @return [Array<Osm::FlexiRecordField>] representing the fields of the flexi record
+    def self.get_fields(api, section, id, options={})
+      section_id = section.to_i
+      cache_key = ['flexi_record_fields', id]
+
+      if !options[:no_cache] && Osm::Model.cache_exist?(api, cache_key) && Osm::Model.get_user_permissions(api, section_id)[:flexi].include?(:read)
+        return Osm::Model.cache_read(api, cache_key)
+      end
+
+      data = api.perform_query("extras.php?action=getExtra&sectionid=#{section_id}&extraid=#{id}")
+
+      structure = []
+      data['structure'].each do |item|
+        item['rows'].each do |row|
+          structure.push Osm::FlexiRecord::Field.new(
+            :id => row['field'],
+            :name => row['name'],
+            :editable => row['editable'] || false,
+          )
+        end
+      end
+      Osm::Model.cache_write(api, cache_key, structure)
+
+      return structure
+    end
+
+    # Get data for flexi record
+    # @param [Osm::Api] api The api to use to make the request
+    # @param [Osm::Section, Fixnum] section the section (or its ID) to get the register for
+    # @param [Fixnum] the id of the Flexi Record
+    # @param [Osm::Term, Fixnum, nil] section the term (or its ID) to get the register for, passing nil causes the current term to be used
+    # @!macro options_get
+    # @return [Array<FlexiRecordData>]
+    def self.get_data(api, section, id, term=nil, options={})
+      section = Osm::Section.get(api, section) if section.is_a?(Fixnum)
+      term_id = term.nil? ? Osm::Term.get_current_term_for_section(api, section).id : term.to_i
+      cache_key = ['flexi_record_data', id, term_id]
+
+      if !options[:no_cache] && Osm::Model.cache_exist?(api, cache_key) && Osm::Model.get_user_permissions(api, section.id)[:flexi].include?(:read)
+        return Osm::Model.cache_read(api, cache_key)
+      end
+
+      data = api.perform_query("extras.php?action=getExtraRecords&sectionid=#{section.id}&extraid=#{id}&termid=#{term_id}&section=#{section.type}")
+
+      to_return = []
+      data['items'].each do |item|
+        fields = item.select { |key, value|
+          ['firstname', 'lastname', 'dob', 'total', 'completed', 'age'].include?(key) || key.to_s.match(/\Af_\d+\Z/)
+        }
+        fields.merge!(
+          'dob' => item['dob'].empty? ? nil : item['dob'],
+          'total' => item['total'].empty? ? nil : item['total'],
+          'completed' => item['completed'].empty? ? nil : item['completed'],
+          'age' => item['age'].empty? ? nil : item['age'],
+        )
+
+        to_return.push Osm::FlexiRecord::Data.new(
+          :member_id => Osm::to_i_or_nil(item['scoutid']),
+          :grouping_id => Osm::to_i_or_nil(item['patrolid'].eql?('') ? nil : item['patrolid']),
+          :fields => fields
+        )
+      end
+
+      Osm::Model.cache_write(api, cache_key, to_return)
+      return to_return
+    end
+
+
+
+
+    class Field < Osm::Model
+      # @!attribute [rw] id
+      #   @return [String] OSM identifier for the field. Special ones are 'dob', 'total', 'completed', 'age', 'firstname' and 'lastname', user ones are of the format 'f\_NUMBER'
+      # @!attribute [rw] name
+      #   @return [String] Human readable name for the field
+      # @!attribute [rw] editable
+      #   @return [Boolean] Wether the field can be edited
+
+      attribute :id, :type => String
+      attribute :name, :type => String
+      attribute :editable, :type => Boolean, :default => false
+
+      attr_accessible :id, :name, :editable
+
+      validates_presence_of :id
+      validates_presence_of :name
+      validates_inclusion_of :editable, :in => [true, false]
+
+      # @!method initialize
+      #   Initialize a new FlexiRecordField
+      #   @param [Hash] attributes the hash of attributes (see attributes for descriptions, use Symbol of attribute name as the key)
+
+    end # Class FlexiRecord::Data
+
+
+    class Data < Osm::Model
+      # @!attribute [rw] member_id
+      #   @return [Fixnum] OSM id for the member
+      # @!attribute [rw] grouping__id
+      #   @return [Fixnum] OSM id for the grouping the member is in
+      # @!attribute [rw] fields
+      #   @return [Hash] Keys are the field's id, values are the field values
+
+      attribute :member_id, :type => Integer
+      attribute :grouping_id, :type => Integer
+      attribute :fields, :default => {}
+
+      attr_accessible :member_id, :grouping_id, :fields
+
+      validates_numericality_of :member_id, :only_integer=>true, :greater_than=>0
+      validates_numericality_of :grouping_id, :only_integer=>true, :greater_than_or_equal_to=>-2
+      validates :fields, :hash => {:key_type => String}
+
+      # @!method initialize
+      #   Initialize a new FlexiRecordData
+      #   @param [Hash] attributes the hash of attributes (see attributes for descriptions, use Symbol of attribute name as the key)
+  
+    end # Class FlexiRecord::Data
+
+  end # Class FlexiRecord
+  
+end # Module

data/lib/osm/grouping.rb

@@ -1,11 +1,11 @@
 module Osm
 
-  class Grouping
-    include ::ActiveAttr::MassAssignmentSecurity
-    include ::ActiveAttr::Model
+  class Grouping < Osm::Model
 
     # @!attribute [rw] id
     #   @return [Fixnum] the id for grouping
+    # @!attribute [rw] section_id
+    #   @return [Fixnum] the id for the section this grouping belongs to
     # @!attribute [rw] name
     #   @return [String] the name of the grouping
     # @!attribute [rw] active
@@ -14,34 +14,56 @@ module Osm
     #   @return [Fixnum] the points awarded to the grouping
 
     attribute :id, :type => Integer
+    attribute :section_id, :type => Integer
     attribute :name, :type => String
     attribute :active, :type => Boolean
     attribute :points, :type => Integer
 
-    attr_accessible :id, :name, :active, :points
+    attr_accessible :id, :section_id, :name, :active, :points
 
     validates_numericality_of :id, :only_integer=>true, :greater_than_or_equal_to=>-2
+    validates_numericality_of :section_id, :only_integer=>true, :greater_than=>0
     validates_presence_of :name
     validates_numericality_of :points, :only_integer=>true
     validates_presence_of :active
 
 
-    # @!method initialize
-    #   Initialize a new Term
-    #   @param [Hash] attributes the hash of attributes (see attributes for descriptions, use Symbol of attribute name as the key)
+    # Get the groupings that a section has
+    # @param [Osm::Api] api The api to use to make the request
+    # @param [Fixnum] section the section (or its ID) of the section to get groupings for
+    # @!macro options_get
+    # @return [Array<Osm::Grouping>, nil] An array of groupings or nil if the user can not access that section
+    def self.get_for_section(api, section, options={})
+      section_id = section.to_i
+      cache_key = ['groupings', section_id]
 
+      if !options[:no_cache] && cache_exist?(api, cache_key)
+        return cache_read(api, cache_key)
+      end
 
-    # Initialize a new Grouping from api data
-    # @param [Hash] data the hash of data provided by the API
-    def self.from_api(data)
-      new({
-        :id => Osm::to_i_or_nil(data['patrolid']),
-        :name => data['name'],
-        :active => (data['active'] == 1),
-        :points => Osm::to_i_or_nil(data['points']),
+      data = api.perform_query("users.php?action=getPatrols&sectionid=#{section_id}")
+
+      result = Array.new
+      data['patrols'].each do |item|
+        result.push Osm::Grouping.new({
+        :id => Osm::to_i_or_nil(item['patrolid']),
+        :section_id => section_id,
+        :name => item['name'],
+        :active => (item['active'] == 1),
+        :points => Osm::to_i_or_nil(item['points']),
       })
+      end
+      cache_write(api, cache_key, result)
+
+      return result
     end
 
+
+    # @!method initialize
+    #   Initialize a new Term
+    #   @param [Hash] attributes the hash of attributes (see attributes for descriptions, use Symbol of attribute name as the key)
+
+
   end # Class Grouping
 
 end # Module

data/lib/osm/member.rb

@@ -1,8 +1,6 @@
 module Osm
 
-  class Member
-    include ::ActiveAttr::MassAssignmentSecurity
-    include ::ActiveAttr::Model
+  class Member < Osm::Model
 
     # @!attribute [rw] id
     #   @return [Fixnum] the id for the member
@@ -54,6 +52,24 @@ module Osm
     #   @return [String] the member's ethnicity
     # @!attribute [rw] subs
     #   @return [String] details about the member's subs
+    # @!attribute [rw] custom1
+    #   @return [String] the custom1 data for the member
+    # @!attribute [rw] custom2
+    #   @return [String] the custom2 data for the member
+    # @!attribute [rw] custom3
+    #   @return [String] the custom3 data for the member
+    # @!attribute [rw] custom4
+    #   @return [String] the custom4 data for the member
+    # @!attribute [rw] custom5
+    #   @return [String] the custom5 data for the member
+    # @!attribute [rw] custom6
+    #   @return [String] the custom6 data for the member
+    # @!attribute [rw] custom7
+    #   @return [String] the custom7 data for the member
+    # @!attribute [rw] custom8
+    #   @return [String] the custom8 data for the member
+    # @!attribute [rw] custom9
+    #   @return [String] the custom9 data for the member
     # @!attribute [rw] grouping_id
     #   @return [Fixnum] the grouping within the section that the member belongs to
     # @!attribute [rw] grouping_leader
@@ -90,13 +106,26 @@ module Osm
     attribute :school, :type => String, :default => ''
     attribute :ethnicity, :type => String, :default => ''
     attribute :subs, :type => String, :default => ''
+    attribute :custom1, :type => String, :default => ''
+    attribute :custom2, :type => String, :default => ''
+    attribute :custom3, :type => String, :default => ''
+    attribute :custom4, :type => String, :default => ''
+    attribute :custom5, :type => String, :default => ''
+    attribute :custom6, :type => String, :default => ''
+    attribute :custom7, :type => String, :default => ''
+    attribute :custom8, :type => String, :default => ''
+    attribute :custom9, :type => String, :default => ''
     attribute :grouping_id, :type => Integer
     attribute :grouping_leader, :type => Integer
     attribute :joined, :type => Date
     attribute :age, :type => String
     attribute :joined_years, :type => Integer
 
-    attr_accessible :id, :section_id, :type, :first_name, :last_name, :email1, :email2, :email3, :email4, :phone1, :phone2, :phone3, :phone4, :address, :address2, :date_of_birth, :started, :joining_in_years, :parents, :notes, :medical, :religion, :school, :ethnicity, :subs, :grouping_id, :grouping_leader, :joined, :age, :joined_years
+    attr_accessible :id, :section_id, :type, :first_name, :last_name, :email1, :email2, :email3, :email4,
+                    :phone1, :phone2, :phone3, :phone4, :address, :address2, :date_of_birth, :started,
+                    :joining_in_years, :parents, :notes, :medical, :religion, :school, :ethnicity, :subs,
+                    :custom1, :custom2, :custom3, :custom4, :custom5, :custom6, :custom7, :custom8, :custom9,
+                    :grouping_id, :grouping_leader, :joined, :age, :joined_years
 
     validates_numericality_of :id, :only_integer=>true, :greater_than=>0
     validates_numericality_of :section_id, :only_integer=>true, :greater_than=>0
@@ -112,48 +141,78 @@ module Osm
     validates_format_of :age, :with => /\A[0-9]{2}\/(0[0-9]|1[012])\Z/, :message => 'age is not in the correct format (yy/mm)', :allow_blank => true
 
 
+    # Get members for a section
+    # @param [Osm::Api] api The api to use to make the request
+    # @param [Osm::Section, Fixnum] section the section (or its ID) to get the members for
+    # @param [Osm::Term, Fixnum, nil] term the term (or its ID) to get the members for, passing nil causes the current term to be used
+    # @!macro options_get
+    # @return [Array<Osm::Member>]
+    def self.get_for_section(api, section, term=nil, options={})
+      term_id = term.nil? ? Osm::Term.get_current_term_for_section(api, section).id : term.to_i
+      section_id = section.to_i
+      cache_key = ['members', section_id, term_id]
+
+      if !options[:no_cache] && cache_exist?(api, cache_key) && get_user_permissions(api, section_id)[:member].include?(:read)
+        return cache_read(api, cache_key)
+      end
+
+      data = api.perform_query("users.php?action=getUserDetails&sectionid=#{section_id}&termid=#{term_id}")
+
+      result = Array.new
+      data['items'].each do |item|
+        result.push Osm::Member.new(
+          :section_id => section_id,
+          :id => Osm::to_i_or_nil(item['scoutid']),
+          :type => item['type'],
+          :first_name => item['firstname'],
+          :last_name => item['lastname'],
+          :email1 => item['email1'],
+          :email2 => item['email2'],
+          :email3 => item['email3'],
+          :email4 => item['email4'],
+          :phone1 => item['phone1'],
+          :phone2 => item['phone2'],
+          :phone3 => item['phone3'],
+          :phone4 => item['phone4'],
+          :address => item['address'],
+          :address2 => item['address2'],
+          :date_of_birth => Osm::parse_date(item['dob'], :ignore_epoch => true),
+          :started => Osm::parse_date(item['started']),
+          :joining_in_years => item['joining_in_yrs'].to_i,
+          :parents => item['parents'],
+          :notes => item['notes'],
+          :medical => item['medical'],
+          :religion => item['religion'],
+          :school => item['school'],
+          :ethnicity => item['ethnicity'],
+          :subs => item['subs'],
+          :custom1 => item['custom1'],
+          :custom2 => item['custom2'],
+          :custom3 => item['custom3'],
+          :custom4 => item['custom4'],
+          :custom5 => item['custom5'],
+          :custom6 => item['custom6'],
+          :custom7 => item['custom7'],
+          :custom8 => item['custom8'],
+          :custom9 => item['custom9'],
+          :grouping_id => Osm::to_i_or_nil(item['patrolid']),
+          :grouping_leader => Osm::to_i_or_nil(item['patrolleader']),
+          :joined => Osm::parse_date(item['joined']),
+          :age => item['age'],
+          :joined_years => item['yrs'].to_i,
+        )
+      end
+
+      cache_write(api, cache_key, result)
+      return result
+    end
+
+
     # @!method initialize
     #   Initialize a new Term
     #   @param [Hash] attributes the hash of attributes (see attributes for descriptions, use Symbol of attribute name as the key)
 
 
-    # Initialize a new Member from api data
-    # @param [Hash] data the hash of data provided by the API
-    def self.from_api(data, section_id)
-      new({
-        :section_id => section_id,
-        :id => Osm::to_i_or_nil(data['scoutid']),
-        :type => data['type'],
-        :first_name => data['firstname'],
-        :last_name => data['lastname'],
-        :email1 => data['email1'],
-        :email2 => data['email2'],
-        :email3 => data['email3'],
-        :email4 => data['email4'],
-        :phone1 => data['phone1'],
-        :phone2 => data['phone2'],
-        :phone3 => data['phone3'],
-        :phone4 => data['phone4'],
-        :address => data['address'],
-        :address2 => data['address2'],
-        :date_of_birth => Osm::parse_date(data['dob'], :ignore_epoch => true),
-        :started => Osm::parse_date(data['started']),
-        :joining_in_years => data['joining_in_yrs'].to_i,
-        :parents => data['parents'],
-        :notes => data['notes'],
-        :medical => data['medical'],
-        :religion => data['religion'],
-        :school => data['school'],
-        :ethnicity => data['ethnicity'],
-        :subs => data['subs'],
-        :grouping_id => Osm::to_i_or_nil(data['patrolid']),
-        :grouping_leader => Osm::to_i_or_nil(data['patrolleader']),
-        :joined => Osm::parse_date(data['joined']),
-        :age => data['age'],
-        :joined_years => data['yrs'].to_i,
-      })
-    end
-
     # Get the years element of this scout's age
     # @return [Fixnum] the number of years this scout has been alive
     def age_years

data/lib/osm/model.rb

@@ -0,0 +1,95 @@
+# @!macro [new] options_get
+#   @param [Hash] options
+#   @option options [Boolean] :no_cache (optional) if true then the data will be retreived from OSM not the cache
+
+
+module Osm
+
+  # This class is expected to be inherited from.
+  # It provides the caching and permission handling for model objects.
+  class Model
+    include ::ActiveAttr::MassAssignmentSecurity
+    include ::ActiveAttr::Model
+
+    @@cache = nil               # Class to use for caching
+    @@cache_prepend = 'OSMAPI'  # Prepended to the key
+    @@cache_ttl = 600           # 10 minutes
+
+
+    # Configure the options used by all models
+    # @param [Hash] options
+    # @option options [Class, nil] :cache An instance of a cache class, must provide the methods (exist?, delete, write, read), for details see Rails.cache. Set to nil to disable caching.
+    # @option options [Fixnum] :ttl (optional, default = 1800 (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)
+    # @option options [String] :prepend_to_key (optional, default = 'OSMAPI') Text to prepend to the key used to store data in the cache
+    # @return nil
+    def self.configure(options)
+      raise ArgumentError, ":ttl must be a FixNum greater than 0" if options[:ttl] && !(options[:ttl].is_a?(Fixnum) && options[:ttl] > 0)
+      raise ArgumentError, ":prepend_to_key must be a String" if options[:prepend_to_key] && !options[:prepend_to_key].is_a?(String)
+      if options[:cache]
+        [:exist?, :delete, :write, :read].each do |method|
+          raise ArgumentError, ":cache must have a #{method} method" unless options[:cache].methods.include?(method)
+        end
+      end
+
+      @@cache = options[:cache]
+      @@cache_prepend = options[:prepend_to_key] || 'OSMAPI'
+      @@cache_ttl = options[:ttl] || 1800
+      nil
+    end
+
+
+    def to_i
+      id
+    end
+
+    private
+    # Wrap cache calls
+    def self.cache_read(api, key)
+      return nil if @@cache.nil?
+      @@cache.read(cache_key(api, key))
+    end
+    def self.cache_write(api, key, data, options={})
+      return false if @@cache.nil?
+      options.merge!(:expires_in => @@cache_ttl)
+      @@cache.write(cache_key(api, key), data, options)
+    end
+    def self.cache_exist?(api, key)
+      return false if @@cache.nil?
+      @@cache.exist?(cache_key(api, key))
+    end
+    def self.cache_delete(api, key)
+      return true if @@cache.nil?
+      @@cache.delete(cache_key(api, key))
+    end
+    def self.cache_key(api, key)
+      key = key.join('-') if key.is_a?(Array)
+      "#{@@cache_prepend.empty? ? '' : "#{@@cache_prepend}-"}#{api.site}-#{key}"
+    end
+
+
+    # Get access permission for an API user
+    # @param [Osm::Api] The api to use to make the request
+    # @param [Fixnum, nil] section_id to get permissions for, if nil a Hash of all section's permissions is returned
+    # @return [Hash] the permissions Hash
+    def self.get_user_permissions(api, section_id=nil)
+      key = ['permissions', api.user_id]
+      permissions = cache_exist?(api, key) ? cache_read(api, key) : Osm::Section.fetch_user_permissions(api)
+      return section_id.nil? ? permissions : (permissions[section_id] || {})
+    end
+
+    # Set access permission for an API user
+    # @param [Osm::Api] The api to use to make the request
+    # @param [Fixnum, nil] section_id to set permissions for, if nil the Hash of all section's permissions is set
+    # @param [Hash] permissions the permissions Hash
+    def self.set_user_permissions(api, section_id=nil, permissions)
+      key = ['permissions', api.user_id]
+      if section_id
+        permissions = get_user_permissions(api).merge(section_id => permissions)
+      end
+      cache_write(api, key, permissions)
+    end
+
+
+  end # Class Model
+
+end # Module