osm 0.0.26 → 0.1.0

data/lib/osm/register.rb

@@ -0,0 +1,177 @@
+module Osm
+
+  class Register
+
+    # Get register structure
+    # @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 [Osm::Term, Fixnum, nil] section the term (or its ID) to get the structure for, passing nil causes the current term to be used
+    # @!macro options_get
+    # @return [Array<Osm::Register::Field>] representing the fields of the register
+    def self.get_structure(api, section, term=nil, options={})
+      section_id = section.to_i
+      term_id = term.nil? ? Osm::Term.get_current_term_for_section(api, section).id : term.to_i
+      cache_key = ['register_structure', section_id, term_id]
+
+      if !options[:no_cache] && Osm::Model.cache_exist?(api, cache_key) && Osm::Model.get_user_permissions(api, section_id)[:register].include?(:read)
+        return Osm::Model.cache_read(api, cache_key)
+      end
+
+      data = api.perform_query("users.php?action=registerStructure&sectionid=#{section_id}&termid=#{term_id}")
+
+      structure = []
+      data.each do |item|
+        item['rows'].each do |row|
+          structure.push Field.new(
+            :id => row['field'],
+            :name => row['name'],
+            :tooltip => row['tooltip'],
+          )
+        end
+      end
+      Osm::Model.cache_write(api, cache_key, structure)
+
+      return structure
+    end
+
+    # Get register attendance
+    # @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 [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<Register::Attendance>] representing the attendance of each member
+    def self.get_attendance(api, section, term=nil, options={})
+      section_id = section.to_i
+      term_id = term.nil? ? Osm::Term.get_current_term_for_section(api, section).id : term.to_i
+      cache_key = ['register_attendance', section_id, term_id]
+
+      if !options[:no_cache] && Osm::Model.cache_exist?(api, cache_key) && Osm::Model.get_user_permissions(api, section_id)[:register].include?(:read)
+        return Osm::Model.cache_read(api, cache_key)
+      end
+
+      data = api.perform_query("users.php?action=register&sectionid=#{section_id}&termid=#{term_id}")
+
+      data = data['items']
+      to_return = []
+      data.each do |item|
+        to_return.push Osm::Register::Attendance.new(
+          :member_id => Osm::to_i_or_nil(item['scoutid']),
+          :grouping_id => Osm::to_i_or_nil(item ['patrolid']),
+          :section_id => Osm::to_i_or_nil(item['sectionid']),
+          :first_name => item['firstname'],
+          :last_name => item['lastname'],
+          :total => item['total'].to_i,
+          :attendance => item.select { |key, value| key.to_s.match(Osm::OSM_DATE_REGEX) }.
+                              inject({}){ |new_hash,(date, attendance)| new_hash[Date.strptime(date, Osm::OSM_DATE_FORMAT)] = attendance; new_hash },
+        )
+      end
+      Osm::Model.cache_write(api, cache_key, to_return)
+      return to_return
+    end
+
+    # Update attendance for an evening in OSM
+    # @param [Hash] data
+    # @option data [Osm::Api] :api The api to use to make the request
+    # @option data [Osm::Section] :section the section to update the register for
+    # @option data [Osm::Term, Fixnum, nil] :term the term (or its ID) to get the register for, passing nil causes the current term to be used
+    # @option data [Osm::Evening, DateTime, Date] :evening the evening to update the register on
+    # @option data [String] :attendance what to mark the attendance as, one of "Yes", "No" or "Absent"
+    # @option data [Fixnum, Array<Fixnum>, Osm::Member, Array<Osm::Member>] :members the members (or their ids) to update
+    # @option data [Array<Hash>] :completed_badge_requirements (optional) the badge requirements to mark as completed, selected from the Hash returned by the get_badge_requirements_for_evening method
+    # @return [Boolean] wether the update succedded
+    def self.update_attendance(data={})
+      raise ArgumentIsInvalid, ':attendance is invalid' unless ['Yes', 'No', 'Absent'].include?(data[:attendance])
+      raise ArgumentIsInvalid, ':section is missing' if data[:section].nil?
+      raise ArgumentIsInvalid, ':evening is missing' if data[:evening].nil?
+      raise ArgumentIsInvalid, ':members is missing' if data[:members].nil?
+
+      api = data[:api]
+      term_id = data[:term].nil? ? Osm::Term.get_current_term_for_section(api, section).id : data[:term].to_i
+
+      data[:members] = [*data[:members]].map{ |member| (member.is_a?(Fixnum) ? member : member.id).to_s } # Make sure it's an Array of Strings
+
+      response = api.perform_query("users.php?action=registerUpdate&sectionid=#{data[:section].id}&termid=#{term_id}", {
+        'scouts' => data[:members].inspect,
+        'selectedDate' => data[:evening].strftime(Osm::OSM_DATE_FORMAT),
+        'present' => data[:attendance],
+        'section' => data[:section].type,
+        'sectionid' => data[:section].id,
+        'completedBadges' => (data[:completed_badge_requirements] || []).to_json
+      })
+
+      # The cached attendance will be out of date - remove them
+      Osm::Model.cache_delete(api, ['register_attendance', data[:section].id, term_id])
+
+      return response.is_a?(Array)
+    end
+
+
+    class Field < Osm::Model
+      # @!attribute [rw] id
+      #   @return [String] OSM identifier for the field
+      # @!attribute [rw] name
+      #   @return [String] Human readable name for the field
+      # @!attribute [rw] tooltip
+      #   @return [String] Tooltip for the field
+
+      attribute :id, :type => String
+      attribute :name, :type => String
+      attribute :tooltip, :type => String, :default => ''
+
+      attr_accessible :id, :name, :tooltip
+
+      validates_presence_of :id
+      validates_presence_of :name
+      validates_presence_of :tooltip, :allow_blank => true
+
+      # @!method initialize
+      #   Initialize a new RegisterField
+      #   @param [Hash] attributes the hash of attributes (see attributes for descriptions, use Symbol of attribute name as the key)
+
+    end # Class Register::Field
+
+
+    class Attendance < Osm::Model
+      # @!attribute [rw] member_id
+      #   @return [Fixnum] The OSM ID for the member
+      # @!attribute [rw] grouping_id
+      #   @return [Fixnum] The OSM ID for the member's grouping
+      # @!attribute [rw] section_id
+      #   @return [Fixnum] The OSM ID for the member's section
+      # @!attribute [rw] first_name
+      #   @return [String] The member's first name
+      # @!attribute [rw] last_name
+      #   @return [String] The member's last name
+      # @!attribute [rw] total
+      #   @return [FixNum] Total
+      # @!attribute [rw] attendance
+      #   @return [Hash] The data for each field - keys are the date, values one of 'Yes' (present), 'No' (known absence) or nil (absent)
+
+      attribute :member_id, :type => Integer
+      attribute :grouping_id, :type => Integer
+      attribute :section_id, :type => Integer
+      attribute :first_name, :type => String
+      attribute :last_name, :type => String
+      attribute :total, :type => Integer
+      attribute :attendance, :default => {}
+
+      attr_accessible :member_id, :first_name, :last_name, :section_id, :grouping_id, :total, :attendance
+
+      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_numericality_of :section_id, :only_integer=>true, :greater_than=>0
+      validates_numericality_of :total, :only_integer=>true, :greater_than_or_equal_to=>0
+      validates_presence_of :first_name
+      validates_presence_of :last_name
+
+      validates :attendance, :hash => {:key_type => Date, :value_in => ['Yes', 'No', nil]}
+
+      # @!method initialize
+      #   Initialize a new registerData
+      #   @param [Hash] attributes the hash of attributes (see attributes for descriptions, use Symbol of attribute name as the key)
+
+    end # Class Register::Data
+
+  end # Class Register
+  
+end # Module

data/lib/osm/section.rb

@@ -1,15 +1,16 @@
 module Osm
 
-  class Section
+  class Section < Osm::Model
     class FlexiRecord; end # Ensure the constant exists for the validators
 
-    include ::ActiveAttr::MassAssignmentSecurity
-    include ::ActiveAttr::Model
-
     # @!attribute [rw] id
     #   @return [Fixnum] the id for the section
     # @!attribute [rw] name
     #   @return [String] the section name
+    # @!attribute [rw] group_id
+    #   @return [Fixnum] the id for the group
+    # @!attribute [rw] group_name
+    #   @return [String] the group name
     # @!attribute [rw] subscription_level
     #   @return [Symbol] what subscription the section has to OSM (:bronze, :silver or :gold)
     # @!attribute [rw] subscription_expires
@@ -28,11 +29,11 @@ module Osm
     #   @return [Hash] which columns are shown in the OSM mobile app
     # @!attribute [rw] flexi_records
     #   @return [Array<FlexiRecord>] list of the extra records the section has
-    # @!attribute [rw] role
-    #   @return [Osm::Role] the role linking the user to this section
 
     attribute :id, :type => Integer
     attribute :name, :type => String
+    attribute :group_id, :type => Integer
+    attribute :group_name, :type => String
     attribute :subscription_level, :default => :unknown
     attribute :subscription_expires, :type => Date
     attribute :type, :default => :unknown
@@ -42,12 +43,15 @@ module Osm
     attribute :intouch_fields, :default => {}
     attribute :mobile_fields, :default => {}
     attribute :flexi_records, :default => []
-    attribute :role
 
-    attr_accessible :id, :name, :subscription_level, :subscription_expires, :type, :num_scouts, :column_names, :fields, :intouch_fields, :mobile_fields, :flexi_records, :role
+    attr_accessible :id, :name, :group_id, :group_name, :subscription_level, :subscription_expires, :type,
+                    :num_scouts, :column_names, :fields, :intouch_fields, :mobile_fields, :flexi_records
 
     validates_numericality_of :id, :only_integer=>true, :greater_than=>0, :allow_nil => true
+    validates_numericality_of :group_id, :only_integer=>true, :greater_than=>0, :allow_nil => true
     validates_numericality_of :num_scouts, :only_integer=>true, :greater_than_or_equal_to=>0
+    validates_presence_of :name
+    validates_presence_of :group_name
     validates_presence_of :subscription_level
     validates_presence_of :subscription_expires
     validates_presence_of :type
@@ -56,14 +60,13 @@ module Osm
     validates_presence_of :intouch_fields, :unless => Proc.new { |a| a.intouch_fields == {} }
     validates_presence_of :mobile_fields, :unless => Proc.new { |a| a.mobile_fields == {} }
     validates_presence_of :flexi_records, :unless => Proc.new { |a| a.flexi_records == [] }
-    validates_presence_of :role
 
     validates_inclusion_of :subscription_level, :in => [:bronze, :silver, :gold, :unknown], :message => 'is not a valid level'
 
     validates :column_names, :hash => {:key_type => Symbol, :value_type => String}
-    validates :fields, :hash => {:key_type => Symbol, :value_type => String}
-    validates :intouch_fields, :hash => {:key_type => Symbol, :value_type => String}
-    validates :mobile_fields, :hash => {:key_type => Symbol, :value_type => String}
+    validates :fields, :hash => {:key_type => Symbol, :value_in => [true, false]}
+    validates :intouch_fields, :hash => {:key_type => Symbol, :value_in => [true, false]}
+    validates :mobile_fields, :hash => {:key_type => Symbol, :value_in => [true, false]}
 
 
     # @!method initialize
@@ -71,40 +74,137 @@ module Osm
     #   @param [Hash] attributes the hash of attributes (see attributes for descriptions, use Symbol of attribute name as the key)
 
 
-    # Initialize a new Sections from api data
-    # @param [Fixnum] id the section ID used by the API to refer to this section
-    # @param [String] name the name given to the sction in OSM
-    # @param [Hash] data the hash of data for the object returned by the API
-    # @param [Osm::Role] role the Osm::Role linked with this section
-    def self.from_api(id, name, data, role)
-      subscription_levels = [:bronze, :silver, :gold]
-      subscription_level = data['subscription_level'].to_i - 1
-
-      attributes = {
-        :id => Osm::to_i_or_nil(id),
-        :name => name,
-        :subscription_level => (subscription_levels[subscription_level] unless subscription_level < 0) || :unknown,
-        :subscription_expires => data['subscription_expires'] ? Date.parse(data['subscription_expires'], 'yyyy-mm-dd') : nil,
-        :type => !data['sectionType'].nil? ? data['sectionType'].to_sym : :unknown,
-        :num_scouts => data['numscouts'],
-        :column_names => data['columnNames'].is_a?(Hash) ? Osm::symbolize_hash(data['columnNames']) : {},
-        :fields => data['fields'].is_a?(Hash) ? Osm::symbolize_hash(data['fields']) : {},
-        :intouch_fields => data['intouch'].is_a?(Hash) ? Osm::symbolize_hash(data['intouch']) : {},
-        :mobile_fields => data['mobFields'].is_a?(Hash) ? Osm::symbolize_hash(data['mobFields']) : {},
-        :role => role,
-        :flexi_records => [],
+    # Get the user's sections
+    # @param [Osm::Api] The api to use to make the request
+    # @!macro options_get
+    # @return [Array<Osm::Section>]
+    def self.get_all(api, options={})
+      cache_key = ['sections', api.user_id]
+      subscription_levels = {
+        1 => :bronze,
+        2 => :silver,
+        3 => :gold,
       }
 
-      # Populate arrays
-      fr = []
-      fr = data['extraRecords'] if data['extraRecords'].is_a?(Array)
-      fr = data['extraRecords'].values if data['extraRecords'].is_a?(Hash)
-      fr.each do |record_data|
-        attributes[:flexi_records].push FlexiRecord.from_api(record_data)
+      if !options[:no_cache] && cache_exist?(api, cache_key)
+        return cache_read(api, cache_key)
+      end
+
+      data = api.perform_query('api.php?action=getUserRoles')
+
+      result = Array.new
+      permissions = Hash.new
+      data.each do |role_data|
+        section_data = ActiveSupport::JSON.decode(role_data['sectionConfig'])
+
+        # Make sense of flexi records
+        fr_data = []
+        flexi_records = []
+        fr_data = section_data['extraRecords'] if section_data['extraRecords'].is_a?(Array)
+        fr_data = section_data['extraRecords'].values if section_data['extraRecords'].is_a?(Hash)
+        fr_data.each do |record_data|
+          # Expect item to be: {:name=>String, :extraid=>Fixnum}
+          # Sometimes get item as: [String, {"name"=>String, "extraid"=>Fixnum}]
+          record_data = record_data[1] if record_data.is_a?(Array)
+          flexi_records.push FlexiRecord.new(
+            :id => Osm::to_i_or_nil(record_data['extraid']),
+            :name => record_data['name'],
+          )
+        end
+
+        section = new(
+          :id => Osm::to_i_or_nil(role_data['sectionid']),
+          :name => role_data['sectionname'],
+          :subscription_level => (subscription_levels[section_data['subscription_level']] || :unknown),
+          :subscription_expires => Osm::parse_date(section_data['subscription_expires']),
+          :type => !section_data['sectionType'].nil? ? section_data['sectionType'].to_sym : :unknown,
+          :num_scouts => section_data['numscouts'],
+          :column_names => section_data['columnNames'].is_a?(Hash) ? Osm::symbolize_hash(section_data['columnNames']) : {},
+          :fields => section_data['fields'].is_a?(Hash) ? Osm::symbolize_hash(section_data['fields']) : {},
+          :intouch_fields => section_data['intouch'].is_a?(Hash) ? Osm::symbolize_hash(section_data['intouch']) : {},
+          :mobile_fields => section_data['mobFields'].is_a?(Hash) ? Osm::symbolize_hash(section_data['mobFields']) : {},
+          :flexi_records => flexi_records.sort,
+          :group_id => role_data['groupid'],
+          :group_name => role_data['groupname'],
+        )
+
+        result.push section
+        cache_write(api, ['section', section.id], section)
+        permissions.merge!(section.id => make_permissions_hash(role_data['permissions']))
+      end
+
+      set_user_permissions(api, get_user_permissions(api).merge(permissions))
+      cache_write(api, cache_key, result)
+      return result
+    end
+
+
+    # Get a section
+    # @param [Osm::Api] The api to use to make the request
+    # @param [Fixnum] section_id the section id of the required section
+    # @!macro options_get
+    # @return nil if an error occured or the user does not have access to that section
+    # @return [Osm::Section]
+    def self.get(api, section_id, options={})
+      cache_key = ['section', section_id]
+
+      if !options[:no_cache] && cache_exist?(api, cache_key) && get_user_permissions(api).keys.include?(section_id)
+        return cache_read(api, cache_key)
       end
-      attributes[:flexi_records].sort
 
-      new(attributes)
+      sections = get_all(api, options)
+      return nil unless sections.is_a? Array
+
+      sections.each do |section|
+        return section if section.id == section_id
+      end
+      return nil
+    end
+
+
+    # Get API user's permissions
+    # @param [Osm::Api] The api to use to make the request
+    # @!macro options_get
+    # @return nil if an error occured or the user does not have access to that section
+    # @return [Hash] {section_id => permissions_hash}
+    def self.fetch_user_permissions(api, options={})
+      cache_key = ['permissions', api.user_id]
+
+      if !options[:no_cache] && cache_exist?(api, cache_key)
+        return cache_read(api, cache_key)
+      end
+
+      data = api.perform_query('api.php?action=getUserRoles')
+
+      all_permissions = Hash.new
+      data.each do |item|
+        all_permissions.merge!(Osm::to_i_or_nil(item['sectionid']) => make_permissions_hash(item['permissions']))
+      end
+      cache_write(api, cache_key, all_permissions)
+      return all_permissions
+    end
+
+    # Get the section's notepads
+    # @param [Osm::Api] The api to use to make the request
+    # @!macro options_get
+    # @return [String] the section's notepad
+    def get_notepad(api, options={})
+      cache_key = ['notepad', id]
+
+      if !options[:no_cache] && self.class.cache_exist?(api, cache_key) && get_user_permissions(api).keys.include?(section_id)
+        return self.class.cache_read(api, cache_key)
+      end
+
+      notepads = api.perform_query('api.php?action=getNotepads')
+      return '' unless notepads.is_a?(Hash)
+
+      notepad = ''
+      notepads.each do |key, value|
+        self.class.cache_write(api, ['notepad', key.to_i], value)
+        notepad = value if key.to_i == id
+      end
+
+      return notepad
     end
 
     # Check if this section is one of the youth sections
@@ -140,7 +240,14 @@ module Osm
 
     def <=>(another)
       begin
-        return self.role <=> another.role
+        compare_group_name = group_name <=> another.group_name
+        return compare_group_name unless compare_group_name == 0
+  
+        return 0 if section.type == another.type
+        [:beavers, :cubs, :scouts, :explorers, :waiting, :adults].each do |type|
+          return -1 if section.type == type
+          return 1 if another.type == type
+        end
       rescue NoMethodError
         return 1
       end
@@ -153,23 +260,22 @@ module Osm
         return false
       end
     end
-    
-    def inspect
-      attribute_descriptions = attributes.merge('role' => (role.nil? ? nil : role.inspect_without_section(self)))
-      return_inspect(attribute_descriptions)
-    end
-
-    def inspect_without_role(exclude_role)
-      attribute_descriptions = (role == exclude_role) ? attributes.merge('role' => 'SET') : attributes
-      return_inspect(attribute_descriptions)
-    end
 
 
     private
-    def return_inspect(attribute_descriptions)
-      attribute_descriptions.sort.map { |key, value| "#{key}: #{key.eql?('role') ? value : value.inspect}" }.join(", ")
-      separator = " " unless attribute_descriptions.empty?
-      "#<#{self.class.name}#{separator}#{attribute_descriptions}>"
+    def self.make_permissions_hash(permissions)
+      return {} unless permissions.is_a?(Hash)
+
+      permissions_map = {
+        10  => [:read],
+        20  => [:read, :write],
+        100 => [:read, :write, :administer],
+      }
+
+      return permissions.inject({}) do |new_hash, (key, value)|
+        new_hash[key.to_sym] = (permissions_map[value] || [])
+        new_hash
+      end
     end
 
 
@@ -195,20 +301,6 @@ module Osm
       #   Initialize a new FlexiRecord
       #   @param [Hash] attributes the hash of attributes (see attributes for descriptions, use Symbol of attribute name as the key)
 
-
-      # Initialize a new FlexiRecord from api data
-      # @param [Hash] data the hash of data provided by the API
-      def self.from_api(data)
-        # Expect item to be: {:name=>String, :extraid=>Fixnum}
-        # Sometimes get item as: [String, {"name"=>String, "extraid"=>Fixnum}]
-        data = data[1] if data.is_a?(Array)
-
-        new({
-          :id => Osm::to_i_or_nil(data['extraid']),
-          :name => data['name'],
-        })
-      end
-
       def <=>(another)
         begin
           return self.name <=> another.name