ecoportal-api-v2 0.8.10 → 0.8.14

data/lib/ecoportal/api/v2/page/force.rb

@@ -0,0 +1,34 @@
+module Ecoportal
+  module API
+    class V2
+      class Page
+        class Force < Common::Content::DoubleModel
+          INITIAL_WEIGHT = 9999
+
+          class << self
+            def new_doc
+              {
+                "id"      => new_uuid,
+                "weight"  => INITIAL_WEIGHT
+              }
+            end
+          end
+
+          class_resolver :bindings_class, "Ecoportal::API::V2::Page::Force::Bindings"
+
+          passkey     :id
+          passforced  :patch_ver, default: 1
+          passthrough :name, :weight, :script
+          embeds_many :bindings,  enum_class: :bindings_class
+
+          def ooze
+            self._parent.ooze
+          end
+        end
+      end
+    end
+  end
+end
+
+require 'ecoportal/api/v2/page/force/binding'
+require 'ecoportal/api/v2/page/force/bindings'

data/lib/ecoportal/api/v2/page/forces.rb

@@ -0,0 +1,103 @@
+module Ecoportal
+  module API
+    class V2
+      class Page
+        class Forces < Common::Content::CollectionModel
+          class_resolver :force_class, "Ecoportal::API::V2::Page::Force"
+
+          self.klass    = :force_class
+          order_matters = true
+
+          def ooze
+            self._parent.ooze
+          end
+
+          # @return [Ecoportal::API::V2::Page::Force]
+          def get_by_id(id)
+            self.find do |force|
+              force.id == id
+            end
+          end
+
+          # @return [Array<Ecoportal::API::V2::Page::Force>]
+          def get_by_name(name)
+            self.select do |force|
+              same_string?(force.name, name)
+            end
+          end
+
+          # Creates a new `force`
+          # @note
+          #   - It won't fix weights unless all the forces of the ooze are present
+          #   - This means that it doesn't fix forces weights on stages,
+          #     as shared forces could change order in other stages
+          # @yield [force] to do some stuff with the `force`
+          # @yieldparam force [Ecoportal::API::V2::Page::Force] the created force
+          # @return [Ecoportal::API::V2::Page::Force]
+          def add(name, pos: NOT_USED, before: NOT_USED, after: NOT_USED)
+            force_doc = force_class.new_doc
+            upsert!(force_doc) do |force| #, pos: pos, before: before, after: after) do |section|
+              force.name  = name
+              if weight = scope_weight(force, pos: pos, before: before, after: after)
+                force.weight = weight
+              end
+              fix_weights!
+              yield(force) if block_given?
+            end
+          end
+
+          # Gets the forces ordered by `weight` (as they appear in the page)
+          # @return [Array<Ecoportal::API::V2::Page::Force>] forces ordered by `weight`
+          def ordered
+            self.sort_by.with_index do |force, index|
+              [force.weight, index]
+            end
+          end
+
+          private
+
+          def fix_weights!
+            unless self._parent.is_a?(Ecoportal::API::V2::Pages::PageStage)
+              ordered.each_with_index do |force, index|
+                force.weight = index
+              end
+            end
+          end
+
+          def scope_weight(force, pos: NOT_USED, before: NOT_USED, after: NOT_USED)
+            case
+            when used_param?(pos)
+              if pos    = to_force(pos)
+                pos.weight - 1
+              end
+            when used_param?(before)
+              if before = to_force(before)
+                before.weight - 1
+              end
+            when used_param?(after)
+              if after  = to_force(after)
+                after.weight
+              end
+            end.yield_self do |weight|
+              weight = ordered.reject do |frc|
+                frc.id == force.id
+              end.last&.weight
+              weight ||= force_class.const_get(:INITIAL_WEIGHT)
+            end
+          end
+
+          def to_force(value)
+            case value
+            when Ecoportal::API::V2::Page::Force
+              value
+            when Numeric
+              ordered[value]
+            else
+              get_by_name(value).first
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ecoportal/api/v2/page/permission_flags.rb

@@ -57,9 +57,7 @@ module Ecoportal
             end.yield_self do |unused|
               raise "Unknown configuaration options #{unused}" unless unused.empty?
             end
-
           end
-
         end
       end
     end

data/lib/ecoportal/api/v2/page/section.rb

@@ -3,12 +3,14 @@ module Ecoportal
     class V2
       class Page
         class Section < Common::Content::DoubleModel
+          INITIAL_WEIGHT = 9999
+
           class << self
             def new_doc(split: false)
               {
                 "id"         => new_uuid,
                 "type"       => split ? "split" : "content",
-                "weight"     => 800
+                "weight"     => INITIAL_WEIGHT
               }.tap do |out|
                 component_ids = if split
                     {
@@ -32,19 +34,48 @@ module Ecoportal
           passarray   :component_ids, :left_component_ids, :right_component_ids
           passboolean :minimized
 
+          def ooze
+            self._parent.ooze
+          end
+
+          # @return [Array<Ecoportal::API::V2::Page::Stage>] the stage(s) this section belongs to.
+          def stages
+            ooze.stages.select {|stg| stg.has_section?(self)}
+          end
+
+          # @return [Boolean] whether or not the section appears in an ooze instance
+          def attached?
+            !ooze.stages? || stages.any?
+          end
+
+          # @return [Boolean] whether or not this section is a split section
           def split?
             doc && doc["type"] == "split"
           end
 
+          # @return [Array<String>] all the `ids` of the components/fields in this section
           def all_component_ids
             return component_ids.to_a unless split?
             left_component_ids.to_a | right_component_ids.to_a
           end
 
-          def component?(id)
-            all_component_ids.include?(id)
+          # @raise [ArgumentError] if `com_or_id` is not of any of the allowed types
+          # @param com_or_id [Ecoportal::API::V2::Page::Component, String] Component or `id` thereof
+          # @return [Boolean] whether or not a component/field belongs to this section.
+          def component?(com_or_id)
+            case
+            when Ecoportal::API::V2::Page::Component
+              component?(com_or_id.id)
+            when String
+              all_component_ids.include?(id)
+            else
+              msg = "Missuse: com_or_id should be a Component or a String. Given: #{com_or_id.class}"
+              raise ArgumentError.new(msg)
+            end
           end
 
+          # It looks up the components that belong to this section.
+          # @return [Array<Ecoportal::API::V2::Page::Component>]
           def components(side: nil)
             case side
             when :right
@@ -58,11 +89,17 @@ module Ecoportal
             end
           end
 
+          # It looks up the components that belong to the `left` side of this section.
+          # @raise [Exception] if this is not a `split` section
+          # @return [Array<Ecoportal::API::V2::Page::Component>]
           def components_left
             raise "You are trying to retrieve side components in a Split Section" unless split?
             components_by_id(*left_component_ids)
           end
 
+          # It looks up the components that belong to the `right` side of this section.
+          # @raise [Exception] if this is not a `split` section
+          # @return [Array<Ecoportal::API::V2::Page::Component>]
           def components_right
             raise "You are trying to retrieve side components in a Split Section" unless split?
             components_by_id(*right_component_ids)
@@ -75,32 +112,41 @@ module Ecoportal
           #   - If `after` is specified, it searches field
           #     - On the specific `side`, if specified (and split section)
           #     - And adds the `field` after it, when found, or at the end if `after` is not found
+          # @raise [ArgumentError] if `field` is not a Component
+          # @raise [Exception] if the field does not belong to ooze.components
+          # @raise [Exception] if the field belongs to another section
           # @param field [Ecoportal::API::V2::Page::Component] the field to be added.
-          def add_component(field, after: nil, side: nil)
-            raise "field should be a Ecoportal::API::V2::Page::Component. Given: #{field.class}" unless field.is_a?(Ecoportal::API::V2::Page::Component)
+          def add_component(field, before: nil, after: nil, side: nil)
+            unless field.is_a?(Ecoportal::API::V2::Page::Component)
+              msg = "Expected Ecoportal::API::V2::Page::Component. Given: #{field.class}"
+              raise ArgumentError.new(msg)
+            end
+            unless ooze.components.include?(field)
+              msg  = "The field '#{field.label}' (#{field.id}) is not present in ooze.components.\n"
+              msg += "Review your script (i.e. @var where you store previous ooze runs)."
+              raise msg
+            end
+            # IMPORTANT NOTE: The code below creates objects, because field.section does a search on section.component_ids
             if field.section == self
-              raise "Field with id '#{field.id}' already belongs to this section"
+              puts "Field with id '#{field.id}' already belongs to this section"
             elsif sec = field.section
               # Field belongs to another section
               raise "Field with id '#{field.id}' belongs to section '#{sec.heading || "Unnamed"}' (id: '#{sec.id}')"
             end
 
+            if before
+              before_fld = to_component(before, side: side)
+            elsif after
+              after_fld  = to_component(afterm, side: side)
+            end
+
             if split?
               ids_ary = side == :right ? right_component_ids : left_component_ids
-              fields  = components(side: side || :left)
             else
               ids_ary = component_ids
-              fields  = components
-            end
-            if after
-              after_fld = fields.find do |fld|
-                found   = nil
-                found ||= !!after if after.is_a?(Ecoportal::API::V2::Page::Component)
-                found ||= fld.id == after
-                found ||= same_string?(fld.label, after)
-              end
             end
-            ids_ary.insert_one(field.id, after: after_fld&.id)
+
+            ids_ary.insert_one(field.id, before: before_fld&.id, after: after_fld&.id)
             self
           end
 
@@ -113,6 +159,20 @@ module Ecoportal
             end
           end
 
+          def to_component(value, side: nil)
+            if split?
+              fields  = components(side: side || :left)
+            else
+              fields  = components
+            end
+
+            fields.find do |fld|
+              found   = nil
+              found ||= !!value if value.is_a?(Ecoportal::API::V2::Page::Component)
+              found ||= fld.id == value
+              found ||= same_string?(fld.label, value)
+            end
+          end
         end
       end
     end

data/lib/ecoportal/api/v2/page/sections.rb

@@ -7,12 +7,20 @@ module Ecoportal
 
           self.klass = :section_class
 
+          def ooze
+            self._parent.ooze
+          end
+
           # Creates a new `section`
+          # @note
+          #   - It won't fix weights unless all the sections of the ooze are present
+          #   - This means that it doesn't fix section weights on stages,
+          #     as shared sections could change order in other stages
           def add(name: nil, split: false, pos: NOT_USED, before: NOT_USED, after: NOT_USED)
             sec_doc = section_class.new_doc(split: split)
             upsert!(sec_doc) do |section| #, pos: pos, before: before, after: after) do |section|
               section.heading  = name
-              if weight = scope_weight(pos: pos, before: before, after: after)
+              if weight = scope_weight(section, pos: pos, before: before, after: after)
                 section.weight = weight
               end
               fix_weights!
@@ -20,12 +28,21 @@ module Ecoportal
             end
           end
 
+          # @return [Ecoportal::API::V2::Page::Section]
+          def get_by_id(id)
+            self.find do |sec|
+              sec.id == id
+            end
+          end
+
+          # @return [Array<Ecoportal::API::V2::Page::Section>]
           def get_by_type(type)
             ordered.select do |sec|
               sec.type == type
             end
           end
 
+          # @return [Array<Ecoportal::API::V2::Page::Section>]
           def get_by_heading(heading)
             ordered.select do |sec|
               value = heading == :unnamed ? nil : heading
@@ -34,6 +51,7 @@ module Ecoportal
           end
 
           # Gets all the sections between `sec1` and `sec2`
+          # @return [Array<Ecoportal::API::V2::Page::Section>]
           def between(sec1, sec2, included: false)
             sorted_secs = ordered
             pos1 = (sec1 = to_section(sec1)) && sorted_secs.index(sec1)
@@ -49,15 +67,21 @@ module Ecoportal
           end
 
           # Gets the sections ordered by `weight` (as they appear in the page)
+          # @return [Array<Ecoportal::API::V2::Page::Section>] section sorted by `weight`
           def ordered
             self.sort_by.with_index do |section, index|
-              (section.weight >= 9999) ? [index, index] : [section.weight, index]
+              [section.weight, index]
             end
           end
 
+          # @return [Array<Ecoportal::API::V2::Page::Section>] sections not attached to any stage
+          def unattached
+            select {|sec| !sec.attached?}
+          end
+
           private
 
-          def scope_weight(pos: NOT_USED, before: NOT_USED, after: NOT_USED)
+          def scope_weight(section, pos: NOT_USED, before: NOT_USED, after: NOT_USED)
             case
             when used_param?(pos)
               if pos    = to_section(pos)
@@ -71,6 +95,11 @@ module Ecoportal
               if after  = to_section(after)
                 after.weight
               end
+            end.yield_self do |weight|
+              weight = ordered.reject do |sec|
+                sec.id == section.id
+              end.last&.weight
+              weight ||= section_class.const_get(:INITIAL_WEIGHT)
             end
           end
 
@@ -86,8 +115,10 @@ module Ecoportal
           end
 
           def fix_weights!
-            ordered.each_with_index do |section, index|
-              section.weight = index
+            unless self._parent.is_a?(Ecoportal::API::V2::Pages::PageStage)
+              ordered.each_with_index do |section, index|
+                section.weight = index
+              end
             end
           end
 
@@ -97,7 +128,6 @@ module Ecoportal
             return if pos < 0
             secs[pos]
           end
-
         end
       end
     end

data/lib/ecoportal/api/v2/page/stage.rb

@@ -17,19 +17,55 @@ module Ecoportal
           embeds_one  :creator_flags, klass: "Ecoportal::API::V2::Page::PermissionFlags"
           passthrough :can
 
+          def ooze
+            self._parent.ooze
+          end
+
+          # @yield [section] do some stuff with section.
+          # @yieldparam section [Ecoportal::API::V2::Page::Section] one of the sections of this stage
+          # @return [Array<Ecoportal::API::V2::Page::Section>] sections attached to this stage.
           def sections
             sec_ids = section_ids.to_a
             root.sections.values_at(*sec_ids).select.with_index do |sec, i|
               puts "Warning: section #{id} points to missing section #{sec_ids[i]}" if !sec
               fld && (!block_given? || yield(sec))
-            end.sort_by {|sec| sec.weight}
+            end.sort_by.with_index {|sec, index| [sec.weight, index]}
           end
 
+          # Check if a section belongs to a stage
+          # @raise [ArgumentError] if none of the valid types of `sec_or_id` are used
+          # @param sec_or_id [String, Ecoportal::API::V2::Page::Section]
+          # @return [Boolean] whether or not the section belongs to the stage
+          def section?(sec_or_id)
+            case sec_or_id
+            when Ecoportal::API::V2::Page::Section
+              section?(sec_or_id.id)
+            when String
+              self.section_ids.include?(id)
+            else
+              raise ArgumentError.new("sec_or_id must be either a Section or a String. Given: #{sec_or_id.class}")
+            end
+          end
+
+          # Adds one or more sections to this stage
+          # @raise [ArgumentError] if any of the elements is not a Section
+          # @raise [Exception] if any of the sections does not belong to ooze.sections
+          # @param secs [Array<Ecoportal::API::V2::Page::Section>] sections to be added to this stage.
           def add_section(*secs)
-            secs.each {|sec| section_ids.insert_one(sec.id)}
+            secs.each do |sec|
+              unless sec.is_a?(Ecoportal::API::V2::Page::Section)
+                msg = "Expected Ecoportal::API::V2::Page::Section. Given: #{sec.class}"
+                raise ArgumentError.new(msg)
+              end
+              unless ooze.sections.include?(sec)
+                msg  = "The section '#{sec.heading}' (#{sec.id}) is not present in ooze.sections.\n"
+                msg += "Review your script (i.e. @var where you store previous ooze runs)."
+                raise msg
+              end
+              section_ids.insert_one(sec.id)
+            end
             self
           end
-
         end
       end
     end

data/lib/ecoportal/api/v2/page/stages.rb

@@ -7,6 +7,12 @@ module Ecoportal
 
           self.klass = :stage_class
 
+          def ooze
+            self._parent.ooze
+          end
+
+          # @param name [String, Regexp] the `name` of the stage to find.
+          # @return [Ecoportal::API::V2::Page::Stage, nil]
           def get_by_name(name)
             self.find do |stage|
               same_string?(stage.name, name)
@@ -14,9 +20,9 @@ module Ecoportal
           end
 
           #def ordered
-          #  self.each_with_index.sort_by do |stage, index|
-          #    (stage.ordering >= 9999) ? [index, index] : [stage.ordering, index]
-          #  end.map(&:first)
+          #  self.sort_by.with_index do |stage, index|
+          #    [stage.ordering, index]
+          #  end
           #end
 
         end

data/lib/ecoportal/api/v2/page.rb

@@ -10,7 +10,7 @@ module Ecoportal
           "permits", "mould_counter", "mould",
           "state", "task_priority",
           "votes_enabled", "upvotes", "downvotes",
-          "force_errors", "subtags"
+          "forces", "force_errors", "subtags"
         ]
 
         passkey     :id
@@ -24,10 +24,20 @@ module Ecoportal
         class_resolver :components_class, "Ecoportal::API::V2::Page::Components"
         class_resolver :sections_class,   "Ecoportal::API::V2::Page::Sections"
         class_resolver :stages_class,     "Ecoportal::API::V2::Page::Stages"
+        class_resolver :forces_class,     "Ecoportal::API::V2::Page::Forces"
 
         embeds_many :components, enum_class: :components_class
         embeds_many :sections,   enum_class: :sections_class
         embeds_many :stages,     enum_class: :stages_class
+        embeds_many :forces,     enum_class: :forces_class
+
+        def initialize(doc = [], parent: self, key: nil)
+          super(_doc_bug_fix(doc), parent: parent, key: key)
+        end
+
+        def ooze
+          self
+        end
 
         def as_update
           super.tap do |hash|
@@ -40,6 +50,39 @@ module Ecoportal
           end
         end
 
+        def stages?
+          self.stages.count > 0
+        end
+
+        private
+
+        def _doc_bug_fix(hash)
+          hash.tap do |hash|
+            _fix_doc(hash["stages"], "flow_node_ids", "section_ids") if hash.key?("stages")
+            if hash.key?("sections")
+              _fix_doc(hash["sections"], "membrane_ids", "component_ids")
+              _fix_doc(hash["sections"], "left_membrane_ids", "left_component_ids")
+              _fix_doc(hash["sections"], "right_membrane_ids", "right_component_ids")
+            end
+          end
+        end
+
+        def _fix_doc(value, source, dest)
+          value.tap do |value|
+            case value
+            when Array
+              value.each {|v| _fix_doc(v, source, dest)}
+            when Hash
+              if value.key?(source) && !value.key?(dest)
+                value[dest] = value[source]
+                value.delete(source)
+              end
+            else
+              # Do nothing!
+            end
+          end
+        end
+
       end
     end
   end
@@ -53,3 +96,5 @@ require 'ecoportal/api/v2/page/section'
 require 'ecoportal/api/v2/page/sections'
 require 'ecoportal/api/v2/page/stage'
 require 'ecoportal/api/v2/page/stages'
+require 'ecoportal/api/v2/page/force'
+require 'ecoportal/api/v2/page/forces'

data/lib/ecoportal/api/v2/pages/page_stage.rb

@@ -9,6 +9,57 @@ module Ecoportal
 
           embeds_many :permits, klass: "Ecoportal::API::V2::Page::Permit"
           passarray   :force_errors, :subtags, order_matters: false
+
+          # @return [String] `id` of the stage we got the data of.
+          def current_stage_id
+            doc.dig("active_stage", "id") || doc["current_stage_id"]
+          end
+
+          # @return [Ecoportal::API::V2::Page::Stage]
+          def current_stage
+            if stage_id = current_stage_id
+              stages[stage_id]
+            end
+          end
+
+          # @raise [Exception] if for this page instance, there are any of:
+          #   1. orphaned components (fields not belonging to any section)
+          #   2. components multi-section (fields belonging to more than one section)
+          #   3. orphaned sections (sections not belonging to any stage)
+          def as_update(*args, **kargs)
+            validate.tap do |validation|
+              raise validation if validation.is_a?(String)
+            end
+            super(*args, **kargs)
+          end
+
+          private
+
+          def validate
+            msg   = ""
+            if (orphans = components.unattached).length > 0
+              msg += "There are fields not attached to any sections:"
+              msg += orphans.map do |fld|
+                fld.label
+              end.join("\n  • ") + "\n"
+            end
+
+            if (multi = components.multi_section).length > 0
+              msg += "There are fields attached to more than one section:"
+              msg += orphans.map do |fld|
+                fld.label
+              end.join("\n  • ") + "\n"
+            end
+
+            if (orphans = sections.unattached).length > 0
+              msg += "There are sections not attached to any stage:"
+              msg += orphans.map do |sec|
+                "'#{sec.header}' (#{sec.id})"
+              end.join("\n  • ") + "\n"
+            end
+            msg.empty?? true : msg
+          end
+
         end
       end
     end

data/lib/ecoportal/api/v2/pages.rb

@@ -47,10 +47,13 @@ module Ecoportal
         end
 
         # Requests to update an existing page via api.
+        # @note It won't launch the update unless there are changes
         # @param doc [Hash, Page] data that at least contains an `id` (internal or external) of the target page.
         # @return [Response] an object with the api response.
         def update(doc)
           body = get_body(doc) # , level: "page"
+          # Launch only if there are changes
+          raise "Missing page object" unless body && body["page"]
           id   = get_id(doc)
           client.patch("/pages/#{CGI.escape(id)}", data: body)
         end

data/lib/ecoportal/api/v2/registers/search_results.rb

@@ -0,0 +1,13 @@
+module Ecoportal
+  module API
+    class V2
+      class Registers
+        class SearchResults < Common::Content::DoubleModel
+          passthrough :total, :total_before_filtering
+          passarray   :tags, order_matters: false
+          embeds_many :results, klass: "Ecoportal::API::V2::Registers::PageResult"
+        end
+      end
+    end
+  end
+end