osm 0.1.11 → 0.1.12

data/CHANGELOG.md

@@ -1,4 +1,31 @@
-## Version 0.0.11
+## Version 0.1.12
+
+  * Attribute Section.myscout\_email\_address\_send defaults to an empty String
+  * Attribute Section.myscout\_email\_address\_copy defaults to an empty String
+  * Attribute Section.myscout\_email\_address\_send renamed to myscout\_email\_address\_from
+  * Osm::Event::Column
+    * Rename parent\_label attribute to label
+    * Add update method to update OSM
+    * Add delete method to update OSM
+  * Osm::Evening
+    * Add delete method to update OSM
+    * Changes to create method:
+      * Now takes arguments of (api, parameters)
+      * Now returns an Osm::Evening on success, nil on failure
+      * Will now pass start time, finish time and title to OSM
+  * Add activity to programme
+      * Evening.add\_activity(api, activity, notes="")
+      * Activity.add\_to\_programme(api, section, date, notes="")
+  * Osm::Member
+    * Add create method to update OSM
+    * Add update method to update OSM
+  * Osm::FlexiRecord
+    * Add add\_field method to add a field to the record in OSM
+    * Add update\_field method to rename a field in OSM
+    * Add delete\_field method to delete a field from OSM
+    * Add update\_data method to update the data in OSM
+
+## Version 0.1.11
 
   * Fix "can't convert Hash into String" occuring when some section's config is a Hash not a JSON encoded Hash
   * Remove num\_scouts attribute from Section (OSM always sets this to 999)
@@ -14,8 +41,8 @@
     * myscout\_emails (Hash of Symbol to Boolean) - which email addresses are linked to MyScout for each Member
     * myscout\_email\_address\_send (String, blank OK) - which email address to send My.SCOUT emails as
     * myscout\_email\_address\_copy (String, blank OK) - which email address to send copys of My.SCOUT emails to
-    * myscout\_badges\_partial (Boolean) - Wether parents can see partially completed badges
-    * myscout\_programme\_summary (Boolean) - Wether parents can see the summary of programme items
+    * myscout\_badges\_partial (Boolean) - Whether parents can see partially completed badges
+    * myscout\_programme\_summary (Boolean) - Whether parents can see the summary of programme items
     * myscout\_event\_reminder\_count (Integer) - How many event reminders to send to parents who haven't responded
     * myscout\_event\_reminder\_frequency (Integer) - How many days to leave between event reminder emails
     * myscout\_payment\_reminder\_count (Integer) - How many payment reminders to send to parents who haven't paid yet
@@ -24,8 +51,8 @@
     * notepad - the notepad shown in OSM
     * public\_notepad - the notepad shown on My.SCOUT
     * confirm\_by\_date - the last day that parents can change their child's attendance details
-    * allow\_changes - wether parents can change their child's attendance details
-    * reminders - wether reminder emails are sent
+    * allow\_changes - whether parents can change their child's attendance details
+    * reminders - whether reminder emails are sent
   * Osm::Event
     * Mark fields attribute as depricated
     * Add columns attribute returning an array of column details

data/README.md

@@ -68,7 +68,7 @@ api_for_this_user = Osm::Api.new(userid, secret)
 Documentation can be found on [rubydoc.info](http://rubydoc.info/github/robertgauld/osm/master/frames)
 
 We follow the [Semantic Versioning](http://semver.org/) concept,
-however it should be noted that when the OSM API adds a feature it can be difficult to decide wether to bump the patch or minor version number up. A smaller change (such as adding score into the grouping object) will bump the patch whereas a larger change wil bump the minor version.
+however it should be noted that when the OSM API adds a feature it can be difficult to decide Whether to bump the patch or minor version number up. A smaller change (such as adding score into the grouping object) will bump the patch whereas a larger change wil bump the minor version.
 
 
 ## Parts of the OSM API Supported:
@@ -82,7 +82,7 @@ however it should be noted that when the OSM API adds a feature it can be diffic
   * Evening
   * Event
   * Events
-  * Event Fields
+  * Event Columns
   * Event Attendance
   * Flexi Record Data
   * Flexi Record Structure
@@ -103,41 +103,40 @@ however it should be noted that when the OSM API adds a feature it can be diffic
   * Evening
   * Event
   * Event Attendance
-  * Register attendance
+  * Event Column
+  * Flexi Record Column
+  * Flexi Record Data
+  * Member
+  * Register Attendance
 
 ### Create
   * Evening
   * Event
+  * Member
+  * Flexi Record Column
 
 ### Delete
+  * Evening
   * Event
+  * Event Column
+  * Flexi Record Column
 
 ### Actions
   * Authorise an app to use the API on a user's behalf
+  * Add activity to programme
 
 
-## Parts of the OSM API currently NOT supported:
+## Parts of the OSM API currently NOT supported (may not be an exhaustive list):
 
-  * Event Fields:
-    * Delete [issue 45]
-    * Rename [issue 46]
   * Badges:
     * Which requirements each member has met:
       * Retreive [issue 21]
       * Update [issue 22]
     * Retrieve details for each badge (stock, short column names etc.) [issue 20]
-  * Flexi Records:
-    * Update data [issue 23]
-    * Add Column [issue 24]
-  * Member:
-    * Update [issue 33]
-    * Add [issue 34]
-  * Add activity to programme [issue 35]
-  * Delete Evening [issue 36]
   * Update Activity
-  * Gift aid (everything)
+  * Gift aid (Everything)
   * Finances (Everything)
   * SMS:
     * Retreival of delivery reports
     * Sending a message
-  * MyScout
+  * MyScout (Everything) (Maybe)

data/lib/osm.rb

@@ -35,7 +35,7 @@ module Osm
     # Configure the options used by classes in the module
     # @param [Hash] options
     # @option options [Hash] :api Default options for accessing the API
-    # @option options[:api] [Symbol] :default_site wether to use OSM (if :osm) or OGM (if :ogm) by default
+    # @option options[:api] [Symbol] :default_site whether to use OSM (if :osm) or OGM (if :ogm) by default
     # @option options[:api] [Hash] :osm (optional but :osm_api or :ogm_api must be present) the api data for OSM
     # @option options[:api][:osm] [String] :id the apiid given to you for using the OSM id
     # @option options[:api][:osm] [String] :token the token which goes with the above api

data/lib/osm/activity.rb

@@ -177,6 +177,24 @@ module Osm
     #   @param [Hash] attributes the hash of attributes (see attributes for descriptions, use Symbol of attribute name as the key)
 
 
+    # Add this activity to the programme in OSM
+    # @param [Osm::Api] api The api to use to make the request
+    # @param [Osm::Section, Fixnum] activity The Section (or it's ID) to add the Activity to
+    # @param [Date, DateTime] date The date of the Evening to add the Activity to (OSM will create the Evening if it doesn't already exist)
+    # @param [String] notes The notes which should appear for this Activity on this Evening
+    # @return [Boolean] Whether the activity ws successfully added
+    def add_to_programme(api, section, date, notes="")
+      data = api.perform_query("programme.php?action=addActivityToProgramme", {
+        'meetingdate' => date.strftime(Osm::OSM_DATE_FORMAT),
+        'activityid' => id,
+        'sectionid' => section.to_i,
+        'notes' => notes,
+      })
+
+      return (data == {'result'=>0})
+    end
+
+
     private
     class File
       include ::ActiveAttr::MassAssignmentSecurity

data/lib/osm/api.rb

@@ -17,7 +17,7 @@ module Osm
 
     # Configure the API options used by all instances of the class
     # @param [Hash] options
-    # @option options [Symbol] :default_site wether to use OSM (if :osm) or OGM (if :ogm)
+    # @option options [Symbol] :default_site whether to use OSM (if :osm) or OGM (if :ogm)
     # @option options [Hash] :osm (optional but :osm_api or :ogm_api must be present) the api data for OSM
     # @option options[:osm] [String] :id the apiid given to you for using the OSM id
     # @option options[:osm] [String] :token the token which goes with the above api
@@ -53,7 +53,7 @@ module Osm
     # Initialize a new API connection
     # @param [String] user_id osm userid of the user to act as (get this by using the authorize method)
     # @param [String] secret osm secret of the user to act as (get this by using the authorize method)
-    # @param [Symbol] site wether to use OSM (:osm) or OGM (:ogm), defaults to the value set for the class
+    # @param [Symbol] site whether to use OSM (:osm) or OGM (:ogm), defaults to the value set for the class
     # @return nil
     def initialize(user_id, secret, site=@@site)
       raise ArgumentError, 'You must pass a secret (get this by using the authorize method)' if secret.nil?
@@ -171,6 +171,7 @@ module Osm
         puts result.response.body
       end
 
+      return nil if result.response.body.empty?
       raise Osm::Error, result.response.body unless looks_like_json?(result.response.body)
       decoded = ActiveSupport::JSON.decode(result.response.body)
       osm_error = get_osm_error(decoded)

data/lib/osm/evening.rb

@@ -63,6 +63,7 @@ module Osm
     # @param [Osm::term, Fixnum, nil] term the term (or its ID) to get the programme for, passing nil causes the current term to be used
     # @!macro options_get
     # @return [Array<Osm::Evening>]
+    # TODO Change to get_all in next version bump
     def self.get_programme(api, section, term, options={})
       section_id = section.to_i
       term_id = term.nil? ? Osm::Term.get_current_term_for_section(api, section).id : term.to_i
@@ -115,25 +116,26 @@ module Osm
 
     # Create an evening in OSM
     # @param [Osm::Api] api The api to use to make the request
-    # @param [Osm::Section, Fixnum] section or section_id to add the evening to
-    # @param [Date] meeting_date the date of the meeting
-    # @return [Boolean] if the operation suceeded or not
-    def self.create(api, section, meeting_date)
-      section_id = section.to_i
-      api_data = {
-        'meetingdate' => meeting_date.strftime(Osm::OSM_DATE_FORMAT),
-        'sectionid' => section_id,
-        'activityid' => -1
-      }
-
-      data = api.perform_query("programme.php?action=addActivityToProgramme", api_data)
+    # @return [Osm::Evening, nil] the created evening, nil if failed
+    def self.create(api, parameters)
+      evening = new(parameters)
+
+      data = api.perform_query("programme.php?action=addActivityToProgramme", {
+        'meetingdate' => evening.meeting_date.strftime(Osm::OSM_DATE_FORMAT),
+        'sectionid' => evening.section_id,
+        'activityid' => -1,
+        'start' => evening.meeting_date.strftime(Osm::OSM_DATE_FORMAT),
+        'starttime' => evening.start_time,
+        'endtime' => evening.finish_time,
+        'title' => evening.title,
+      })
 
       # The cached programmes for the section will be out of date - remove them
-      Osm::Term.get_for_section(api, section).each do |term|
-        cache_delete(api, ['programme', section_id, term.id])
+      Osm::Term.get_for_section(api, evening.section_id).each do |term|
+        cache_delete(api, ['programme', evening.section_id, term.id])
       end
 
-      return data.is_a?(Hash) && (data['result'] == 0)
+      return data.is_a?(Hash) ? evening : nil
     end
 
 
@@ -177,6 +179,40 @@ module Osm
       return response.is_a?(Hash) && (response['result'] == 0)
     end
 
+    # Add an activity to this evening in OSM
+    # @param [Osm::Api] api The api to use to make the request
+    # @param [Osm::Activity] activity The Activity to add to the Evening
+    # @param [String] notes The notes which should appear for this Activity on this Evening
+    # @return [Boolean] Whether the activity ws successfully added
+    def add_activity(api, activity, notes='')
+      if activity.add_to_programme(api, section_id, meeting_date, notes)
+        activities.push Osm::Evening::Activity.new(:activity_id => activity.id, :notes => notes, :title => activity.title)
+
+        # The cached programmes for the section will be out of date - remove them
+        Osm::Term.get_for_section(api, section_id).each do |term|
+          cache_delete(api, ['programme', section_id, term.id]) if term.contains_date?(meeting_date)
+        end
+
+        return true
+      end
+
+      return false
+    end
+
+    # Delete evening from OSM
+    # @param [Osm::Api] api The api to use to make the request
+    # @return [Boolean] true
+    def delete(api)
+      data = api.perform_query("programme.php?action=deleteEvening&eveningid=#{id}&sectionid=#{section_id}")
+
+      # The cached programmes for the section will be out of date - remove them
+      Osm::Term.get_for_section(api, section_id).each do |term|
+        cache_delete(api, ['programme', section_id, term.id]) if term.contains_date?(meeting_date)
+      end
+
+      return true
+    end
+
 
     # Get the badge requirements met on a specific evening
     # @param [Osm::Api] api The api to use to make the request

data/lib/osm/event.rb

@@ -33,9 +33,9 @@ module Osm
     # @!attribute [rw] confirm_by_date
     #   @return [Date] the date parents can no longer add/change their child's details
     # @!attribute [rw] allow_changes
-    #   @return [Boolean] wether parent's can change their child's details
+    #   @return [Boolean] whether parent's can change their child's details
     # @!attribute [rw] reminders
-    #   @return [Boolean] wether email reminders are sent for the event
+    #   @return [Boolean] whether email reminders are sent for the event
 
     attribute :id, :type => Integer
     attribute :section_id, :type => Integer
@@ -160,7 +160,7 @@ module Osm
 
     # Update event in OSM
     # @param [Osm::Api] api The api to use to make the request
-    # @return [Boolean] wether the update succedded
+    # @return [Boolean] whether the update succedded
     def update(api)
       raise Forbidden, 'you do not have permission to write to events for this section' unless get_user_permission(api, section_id, :events).include?(:write)
 
@@ -196,7 +196,7 @@ module Osm
 
     # Delete event from OSM
     # @param [Osm::Api] api The api to use to make the request
-    # @return [Boolean] wether the delete succedded
+    # @return [Boolean] whether the delete succedded
     def delete(api)
       raise Forbidden, 'you do not have permission to write to events for this section' unless get_user_permission(api, section_id, :events).include?(:write)
 
@@ -254,7 +254,7 @@ module Osm
     # @param [Osm::Api] api The api to use to make the request
     # @param [String] label the label for the field in OSM
     # @param [String] name the label for the field in My.SCOUT (if this is blank then parents can't edit it)
-    # @return [Boolean] wether the update succedded
+    # @return [Boolean] whether the update succedded
     def add_column(api, name, label='')
       raise ArgumentIsInvalid, 'name is invalid' if name.blank?
       raise Forbidden, 'you do not have permission to write to events for this section' unless get_user_permission(api, section_id, :events).include?(:write)
@@ -278,7 +278,7 @@ module Osm
     # @deprecated use add_column instead
     # @param [Osm::Api] api The api to use to make the request
     # @param [String] field_label the label for the field to add
-    # @return [Boolean] wether the update succedded
+    # @return [Boolean] whether the update succedded
     # TODO - Remove this method when upping the version
     def add_field(api, label)
       warn "[DEPRECATION OF METHOD] this method is being depreiated, use add_column instead"
@@ -311,11 +311,6 @@ module Osm
 
     private
     def self.new_event_from_data(event_data)
-      columns = []
-      ActiveSupport::JSON.decode(event_data['config']).each do |field|
-        columns.push Column.new(:id => field['id'], :name => field['name'], :parent_label => field['pL'])
-      end
-
       event = Osm::Event.new(
         :id => Osm::to_i_or_nil(event_data['eventid']),
         :section_id => Osm::to_i_or_nil(event_data['sectionid']),
@@ -326,13 +321,19 @@ module Osm
         :location => event_data['location'],
         :notes => event_data['notes'],
         :archived => event_data['archived'].eql?('1'),
-        :columns => columns,
         :notepad => event_data['notepad'],
         :public_notepad => event_data['publicnotes'],
         :confirm_by_date => Osm::parse_date(event_data['confdate']),
         :allow_changes => event_data['allowchanges'].eql?('1'),
         :reminders => !event_data['disablereminders'].eql?('1'),
       )
+
+      columns = []
+      ActiveSupport::JSON.decode(event_data['config']).each do |field|
+        columns.push Column.new(:id => field['id'], :name => field['name'], :label => field['pL'], :event => event)
+      end
+      event.columns = columns
+      return event
     end
 
 
@@ -344,14 +345,17 @@ module Osm
       #   @return [String] OSM id for the column
       # @!attribute [rw] name
       #   @return [String] name for the column (displayed in OSM)
-      # @!attribute [rw] parent_label
+      # @!attribute [rw] label
       #   @return [String] label to display in My.SCOUT ("" prevents display in My.SCOUT)
+      # @!attriute [rw] event
+      #   @return [Osm::Event] the event that this column belongs to
 
       attribute :id, :type => String
       attribute :name, :type => String
-      attribute :parent_label, :type => String, :default => ''
+      attribute :label, :type => String, :default => ''
+      attribute :event
 
-      attr_accessible :id, :name, :parent_label
+      attr_accessible :id, :name, :label, :event
 
       validates_presence_of :id
       validates_presence_of :name
@@ -361,6 +365,57 @@ module Osm
       #   Initialize a new Column
       #   @param [Hash] attributes the hash of attributes (see attributes for descriptions, use Symbol of attribute name as the key)
 
+
+      # Update event column in OSM
+      # @param [Osm::Api] api The api to use to make the request
+      # @return [Boolean] if the operation suceeded or not
+      def update(api)
+        raise Forbidden, 'you do not have permission to write to events for this section' unless Osm::Model.get_user_permission(api, event.section_id, :events).include?(:write)
+
+        data = api.perform_query("events.php?action=renameColumn&sectionid=#{event.section_id}&eventid=#{event.id}", {
+          'columnId' => id,
+          'columnName' => name,
+          'pL' => label
+        })
+
+        # The cached events for the section will be out of date - remove them
+        Osm::Model.cache_delete(api, ['events', event.section_id])
+        Osm::Model.cache_delete(api, ['event', event.id])
+
+        (ActiveSupport::JSON.decode(data['config']) || []).each do |i|
+          if i['id'] == id
+            return i['name'].eql?(name) && (i['pL'].nil? || i['pL'].eql?(label))
+          end
+        end
+        return false
+      end
+
+      # Delete event column from OSM
+      # @param [Osm::Api] api The api to use to make the request
+      # @return [Boolean] whether the delete succedded
+      def delete(api)
+        raise Forbidden, 'you do not have permission to write to events for this section' unless Osm::Model.get_user_permission(api, event.section_id, :events).include?(:write)
+
+        data = api.perform_query("events.php?action=deleteColumn&sectionid=#{event.section_id}&eventid=#{event.id}", {
+          'columnId' => id
+        })
+
+        # The cached events for the section will be out of date - remove them
+        Osm::Model.cache_delete(api, ['events', event.section_id])
+        Osm::Model.cache_delete(api, ['event', event.id])
+
+        (ActiveSupport::JSON.decode(data['config']) || []).each do |i|
+          return false if i['id'] == id
+        end
+
+        new_columns = []
+        event.columns.each do |column|
+          new_columns.push(column) unless column == self
+        end
+        event.columns = new_columns
+        return true
+      end
+
     end # class Column
 
 
@@ -376,6 +431,8 @@ module Osm
       #   @return [Hash] Keys are the field's id, values are the field values
       # @!attribute [rw] row
       #   @return [Fixnum] part of the OSM API
+      # @!attriute [rw] event
+      #   @return [Osm::Event] the event that this attendance applies to
   
       attribute :row, :type => Integer
       attribute :member_id, :type => Integer

data/lib/osm/flexi_record.rb

@@ -1,3 +1,5 @@
+# TODO make 'proper' class
+
 module Osm
 
   class FlexiRecord
@@ -5,7 +7,7 @@ module Osm
     # 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
+    # @param [Fixnum] id 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={})
@@ -33,6 +35,87 @@ module Osm
       return structure
     end
 
+    # Add a field in OSM
+    # @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] id the id of the Flexi Record
+    # @param [String] name The name for the created column
+    # @return [Boolean] whether the field was created in OSM
+    def self.add_field(api, section, id, name)
+      raise ArgumentError, 'name is invalid' if name.blank?
+      section_id = section.to_i
+
+      data = api.perform_query("extras.php?action=addColumn&sectionid=#{section_id}&extraid=#{id}", {
+        'columnName' => name,
+      })
+
+      if (data.is_a?(Hash) && data.has_key?('config'))
+        ActiveSupport::JSON.decode(data['config']).each do |field|
+          if field['name'] == name
+            # The cached fields for the flexi record will be out of date - remove them
+             Osm::Model.cache_delete(api, ['flexi_record_fields', id])
+            return true
+          end
+        end
+      end
+      return false
+    end
+
+    # Update a field in OSM
+    # @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] id the id of the Flexi Record
+    # @param [String] field the id of the Flexi Record Field
+    # @param [String] name The new name for the created column
+    # @return [Boolean] whether the field was updated in OSM
+    def self.update_field(api, section, id, field, name)
+      raise ArgumentError, 'name is invalid' if name.blank?
+      section_id = section.to_i
+
+      data = api.perform_query("extras.php?action=renameColumn&sectionid=#{section_id}&extraid=#{id}", {
+        'columnId' => field,
+        'columnName' => name,
+      })
+
+      if (data.is_a?(Hash) && data.has_key?('config'))
+        ActiveSupport::JSON.decode(data['config']).each do |f|
+          if (f['id'] == field) && (f['name'] == name)
+            # The cached fields for the flexi record will be out of date - remove them
+            Osm::Model.cache_delete(api, ['flexi_record_fields', id])
+            return true
+          end
+        end
+      end
+      return false
+    end
+
+    # Update a field in OSM
+    # @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] id the id of the Flexi Record
+    # @param [String] field the id of the Flexi Record Field
+    # @return [Boolean] whether the field was updated in OSM
+    def self.delete_field(api, section, id, field)
+      section_id = section.to_i
+
+      data = api.perform_query("extras.php?action=deleteColumn&sectionid=#{section_id}&extraid=#{id}", {
+        'columnId' => field,
+      })
+
+      if (data.is_a?(Hash) && data.has_key?('config'))
+        ActiveSupport::JSON.decode(data['config']).each do |f|
+          if f['id'] == field
+            # It wasn't deleted
+            return false
+          end
+        end
+      end
+
+      # The cached fields for the flexi record will be out of date - remove them
+      Osm::Model.cache_delete(api, ['flexi_record_fields', id])
+      return true
+    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
@@ -76,6 +159,36 @@ module Osm
       return to_return
     end
 
+    # Update a field in OSM
+    # @param [Osm::Api] api The api to use to make the request
+    # @param [Osm::Section, Fixnum] section the section (or its ID) to update the data for
+    # @param [Fixnum] flexi_record_id the id of the Flexi Record
+    # @param [Osm::Member, Fixnum] member the member (or their ID) to update
+    # @param [String] column the id of the Flexi Record Field
+    # @param [String] value The updated value
+    # @return [Boolean] whether the field was updated in OSM
+    def self.update_data(api, section, flexi_record_id, member, column, value)
+      raise ArgumentError, 'name is invalid' if name.blank?
+      section_id = section.to_i
+      member_id = member.to_i
+      term_id = Osm::Term.get_current_term_for_section(api, section).id
+
+      data = api.perform_query("extras.php?action=updateScout", {
+        'termid' => term_id,
+        'scoutid' => member_id,
+        'column' => column,
+        'value' => value,
+        'sectionid' => section_id,
+        'extraid' => flexi_record_id,
+      })
+
+      if (data.is_a?(Hash) && data['items'].is_a?(Array))
+        data['items'].each do |item|
+          return true if (item[column] == value) && (item['scoutid'] == member_id.to_s)
+        end
+      end
+      return false
+    end