ecoportal-api-v2 0.8.13 → 0.8.14

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 146b0998371f28683143b8a95ae1b68e11f8f079698502bede31c8e29369fc97
-  data.tar.gz: 4ce0f3dd75e4e1d822d4540fa0ff1e3e18a7c7dca1c54d7030bdb475adc21a93
+  metadata.gz: 3480ab100855337eef9de50609f4f4776418de1b09a5a1eac3ee31f936f4cd00
+  data.tar.gz: 2520bf687a1d00df3d925788600f78c266fcc6599ac816dac1f7df08703bc9e9
 SHA512:
-  metadata.gz: 21605169ab88cb159ee32a2f6f36e3100b183a03a7f9c895b33631934811bb9e3f16c6bc6101ddfac562854f8762f545a743b68c55d662c97be54ff35fc5b9e8
-  data.tar.gz: d2a66296e4b9194667983ba5c37c646fd6a12e037138870aa2771c743fc75dbf9b2ee91d07af7b1e4b501ad1afd846b427a8b92f5dc99ee4551200cc742dcd20
+  metadata.gz: 011752c7161177026fdcd59a01ee7eb048094eb29c5688e2b68e6ad2aec0a263e93990726c1fca86eb1bfc86d000d360db4d8cf685783f7c2ab8257570258740
+  data.tar.gz: 012ed55b7472c56f76b2e1bdafd3ce8cb926c67d5d94e6b3349a7c21ade9ff3a20c2caa4974fe9cdc30a6dba8312663edc633ae7d0a66b31117b57e795727dde

data/CHANGELOG.md

@@ -1,12 +1,49 @@
 # Change Log
 All notable changes to this project will be documented in this file.
 
-## [0.8.13] - 2021-08-xx
+## [0.8.14] - 2021-09-xx
 
 ### Added
+  - `Ecoportal::API::Common::Content::CollectionModel`
+    - `#_doc_pos` for clarity
+    - `#include?` to check if an element is present in the collection
+  - `Ecoportal::API::V2::Page::Stage#section?` check if section belongs to stage
+  - `Ecoportal::API::V2::Page::Sections`
+    - `#get_by_id`
+    - `#unattached` sections that are not attached to any stage
+  - `Ecoportal::API::V2::Page::Section`
+    - `#add_component` **added** parameter `before`: to cover case where you want to add it at the beginning
+    - `#component?` **widened** parameter type
+    - `#stages` stages where this section is attached
+    - `attached?` whether or not the section is attached
+  - `Ecoportal::API::V2::Page::Component`
+    - `#attached?` whether or not the field is attached to some section
+    - `#multi_section?` if the field is attached to more than one section :/
+  - **added** support for `forces`
+    - `Ecoportal::API::V2::Page::Force`
+    - `Ecoportal::API::V2::Page::Forces`
+    - `Ecoportal::API::V2::Page::Force::Binding`
+    - `Ecoportal::API::V2::Page::Force::Bindings`
+  - **added** shortcut to `#ooze` throughout all the model
+  - **validations** in some methods
+    - `Ecoportal::API::V2::Page::Stage#add_section`: section should be in `ooze.sections`
+    - `Ecoportal::API::V2::Page::Section#add_component`: component should be in `ooze.components`
+    - `Ecoportal::API::V2::Page::Force::Bindings#add`:
+      - section to be in `ooze.sections`
+      - component to be in `ooze.components`
+    - `Ecoportal::API::V2::Pages::PageStage#as_update` on page instances, it checks that
+      - Fields do not belong to more than one section
+      - Fields belong at least to one section
+      - Sections belong to at least one stage
+
 ### Changed
 ### Fixed
-  - `Ecoportal::API::V2::Stage::Sections`
+  - `Ecoportal::API::Common::Content::ArrayModel#insert_one` was not inserting when not found. Should insert at least at the end.
+
+## [0.8.13] - 2021-09-03
+
+### Fixed
+  - `Ecoportal::API::V2::Page::Sections`
     - `weight` fixing should only happen on entire page, **not** on stage sections that could change the order of section shared with other stages
     - `#scope_weight` was not excluding the section when using `weight` of the last one
   - Several classes with `embeds_many` were performing the `ordering` of those elements in the wrong way

data/lib/ecoportal/api/common/content/array_model.rb

@@ -224,25 +224,18 @@ module Ecoportal
             i = index(value)
             return i if (i && uniq?)
             pos = case
-                  when used_param?(pos)
-                    pos || length
-                  when used_param?(before)
-                    before ? index(before) : length
-                  when used_param?(after)
-                    if after
-                      if i = index(after) then i + 1 end
-                    else
-                      length
-                    end
-                  else
-                    length
+                  when used_param?(pos) && pos
+                    pos
+                  when used_param?(before) && before
+                    index(before)
+                  when used_param?(after) && after
+                    if i = index(after) then i + 1 end
                   end
 
+            pos ||= length
             pos.tap do |i|
-              unless !i
-                _items.insert(pos, value)
-                on_change
-              end
+              _items.insert(pos, value)
+              on_change
             end
           end
 

data/lib/ecoportal/api/common/content/collection_model.rb

@@ -109,6 +109,10 @@ module Ecoportal
             self.class.klass
           end
 
+          def _doc_pos(value)
+            _doc_key(value)
+          end
+
           # Transforms `value` into the actual `key` to access the object in the doc `Array`
           # @note
           #   - The name of the method is after the paren't class method
@@ -152,6 +156,13 @@ module Ecoportal
             items_by_key[get_key(value)]
           end
 
+          # Checks if an element exists in the collection
+          # @param value [String, Hash, Ecoportal::API::Common::Content::DoubleModel]
+          # @return [Boolean] whether or not it is included
+          def include?(value)
+            items_by_key.key?(get_key(value))
+          end
+
           # @return [Array<Object>] the `items_class` element object
           def values_at(*keys)
             keys.map {|key| self[key]}

data/lib/ecoportal/api/common/content/hash_diff_patch.rb

@@ -60,7 +60,7 @@ module Ecoportal
               a == b
             end
 
-            # Compares `a` as charring changes of `b`
+            # Compares `a` as carrying changes of `b`
             # @return [Hash] patch data object with only changes
             def patch_data(a, b = nil, delete: false)
               {}.tap do |data_hash|

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

@@ -93,6 +93,10 @@ module Ecoportal
           passboolean :hide_view, :hidden_on_reports, :hidden_on_mobile
           passarray   :refs
 
+          def ooze
+            self._parent.ooze
+          end
+
           def ref_backend
             refs.first
           end
@@ -103,10 +107,23 @@ module Ecoportal
             end
           end
 
+          # Looks up the section that this component belongs to.
+          # @return [Ecoportal::API::V2::Page::Section, nil] the section where this field is attached to.
           def section
             root.sections.find {|sec| sec.component?(id)}
           end
 
+          # @return [Boolean] whether or not this field is attached to any section.
+          def attached?
+            !!section
+          end
+
+          # @return [Boolean] whether or not the component has been attached to more than one section.
+          def multi_section?
+            secs = ooze.sections.select {|sec| sec.component?(id)}
+            secs.length > 1
+          end
+
           def indexable_label
             self.class.indexable_label(label)
           end

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

@@ -13,18 +13,27 @@ module Ecoportal
 
           order_matters = true
 
+          def ooze
+            self._parent.ooze
+          end
+
+          # @return [Ecoportal::API::V2::Page::Component] the field with `id`
           def get_by_id(id)
             self.find do |comp|
               comp.id == id
             end
           end
 
+          # @return [Array<Ecoportal::API::V2::Page::Component>] the fields of that `type`
           def get_by_type(type)
             self.select do |comp|
               comp.type.downcase == type.to_s.strip.downcase
             end
           end
 
+          # @param name [String, Regexp] the `name` to search the field based on their `label`
+          # @param type [String] the `type` of the fields to be included
+          # @return [Array<Ecoportal::API::V2::Page::Component>] the fields that match `name`.
           def get_by_name(name, type: nil)
             pool = type ? get_by_type(type) : self
             pool.select do |comp|
@@ -32,6 +41,12 @@ module Ecoportal
             end
           end
 
+          # It creates a **new** component
+          # @param label [String, nil]
+          # @param type [String] the type of the field
+          # @yield [field] do some stuff with field
+          # @yieldparam [Ecoportal::API::V2::Page::Component] the created field
+          # @return [Ecoportal::API::V2::Page::Component] the created field.
           def add(label:, type:)
             fld_doc = component_class.new_doc(type: type)
             upsert!(fld_doc) do |fld|
@@ -40,6 +55,15 @@ module Ecoportal
             end
           end
 
+          # @return [Array<Ecoportal::API::V2::Page::Component>] **orphaned** fields (with no section).
+          def unattached
+            select {|comp| !comp.attached?}
+          end
+
+          # @return [Array<Ecoportal::API::V2::Page::Component>] fields belonging to more than one section.
+          def multi_section
+            select {|comp| comp.multi_section?}
+          end
         end
       end
     end

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

@@ -0,0 +1,54 @@
+module Ecoportal
+  module API
+    class V2
+      class Page
+        class Force
+          class Binding < Common::Content::DoubleModel
+            class << self
+              def new_doc
+                {
+                  "id"      => new_uuid
+                }
+              end
+            end
+            COMPONENT_TYPE = "membrane_binding"
+            SECTION_TYPE   = "flow_node_binding"
+
+            passkey     :id
+            passforced  :patch_ver, default: 1
+            passthrough :name, :reference_id, :type
+
+            def ooze
+              self._parent.ooze
+            end
+
+            # @return [Boolean] whether or not this the binding refers to a Component
+            def component?
+              type == COMPONENT_TYPE
+            end
+
+            # @return [Boolean] whether or not this the binding refers to a Section
+            def section?
+              type == SECTION_TYPE
+            end
+
+            # @return [Ecoportal::API::V2::Page::Component] field referenced by this binding.
+            def component
+              raise "This is not a component binding, but a section binding" unless component?
+              ooze.components.get_by_id(reference_id)
+            end
+
+            # @return [Ecoportal::API::V2::Page::Section] section referenced by this binding.
+            def section
+              raise "This is not a section binding, but a component binding" unless section?
+              ooze.sections.get_by_id(reference_id)
+            end
+          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/force/bindings.rb

@@ -0,0 +1,126 @@
+module Ecoportal
+  module API
+    class V2
+      class Page
+        class Force
+          class Bindings < Common::Content::CollectionModel
+            class_resolver :binding_class, "Ecoportal::API::V2::Page::Force::Binding"
+
+            self.klass    = :binding_class
+            order_matters = true
+
+            def ooze
+              self._parent.ooze
+            end
+
+            # @param id [String] the `id` of the binding to find.
+            # @return [Ecoportal::API::V2::Page::Force::Binding] binding with `id`
+            def get_by_id(id)
+              self.find do |bind|
+                bind.id == id
+              end
+            end
+
+            # @param type [String] target `type` of binding
+            #   1. Ecoportal::API::V2::Page::Force::Binding::COMPONENT_TYPE
+            #   2. Ecoportal::API::V2::Page::Force::Binding::SECTION_TYPE
+            # @return [Array<Ecoportal::API::V2::Page::Force::Binding>] the bindings of type `type`
+            def get_by_type(type = Ecoportal::API::V2::Page::Force::Binding::COMPONENT_TYPE)
+              self.select do |bind|
+                bind.type.downcase == type.to_s.strip.downcase
+              end
+            end
+
+            # @param type [String] target `type` of binding
+            #   1. Ecoportal::API::V2::Page::Force::Binding::COMPONENT_TYPE
+            #   2. Ecoportal::API::V2::Page::Force::Binding::SECTION_TYPE
+            # @return [Array<Ecoportal::API::V2::Page::Force::Binding>] the bindings matching `name`
+            def get_by_name(name, type: nil)
+              pool = type ? get_by_type(type) : self
+              pool.select do |bind|
+                same_string?(bind.name, name)
+              end
+            end
+
+            # Creates a new `binding`
+            # @note
+            #   - As there's no position property, it will upsert to the array of bindings
+            # @raise [ArgumentError] when `reference` is neither of Component or Section
+            # @raise [Exception] when
+            #   1. `reference` is a field missing in ooze.components
+            #   2. `reference` is a section missing in ooze.sections
+            # @param reference [Ecoportal::API::V2::Page::Component, Ecoportal::API::V2::Page::Section]
+            #   The field or the section to bind.
+            # @yield [binding] do some stuff with binding
+            # @yieldparam binding [Ecoportal::API::V2::Page::Force::Binding] the created binding
+            # @return [Ecoportal::API::V2::Page::Force::Binding] the created binding.
+            def add(reference, name:, pos: NOT_USED, before: NOT_USED, after: NOT_USED)
+              binding_doc = binding_class.new_doc
+
+              type = case reference
+                      when Ecoportal::API::V2::Page::Component
+                        unless ooze.components.include?(reference)
+                          msg  = "The field '#{reference.label}' (#{reference.id}) is not present in ooze.components.\n"
+                          msg += "Review your script (i.e. @var where you store previous ooze runs)."
+                          raise msg
+                        end
+                        Ecoportal::API::V2::Page::Force::Binding::COMPONENT_TYPE
+                      when Ecoportal::API::V2::Page::Section
+                        unless ooze.sections.include?(reference)
+                          msg  = "The section '#{reference.heading}' (#{reference.id}) is not present in ooze.sections.\n"
+                          msg += "Review your script (i.e. @var where you store previous ooze runs)."
+                          raise msg
+                        end
+                        Ecoportal::API::V2::Page::Force::Binding::SECTION_TYPE
+                      else
+                        msg = "You can only create bindings with Component and Section. Given: #{reference.class}"
+                        raise ArgumentError.new(msg)
+                      end
+
+              position = scope_position(pos: pos, before: before, after: after)
+              upsert!(binding_doc, pos: position) do |bind|
+                bind.name         = name
+                bind.reference_id = reference.id
+                bind.type         = type
+                yield(bind) if block_given?
+              end
+            end
+
+            private
+
+            def scope_position(pos: NOT_USED, before: NOT_USED, after: NOT_USED)
+              case
+              when used_param?(pos)
+                if pos    = to_binding(pos)
+                  _doc_pos(pos) - 1
+                end
+              when used_param?(before)
+                if before = to_binding(before)
+                  _doc_pos(before) - 1
+                end
+              when used_param?(after)
+                if after  = to_binding(after)
+                  _doc_pos(after) - 1
+                end
+              end.yield_self do |position|
+                position ||= self.count
+              end
+            end
+
+            def to_binding(value)
+              case value
+              when Ecoportal::API::V2::Page::Force::Binding
+                value
+              when Numeric
+                self[value]
+              else
+                get_by_name(value).first
+              end
+            end
+
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -34,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
@@ -60,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)
@@ -77,9 +112,20 @@ 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
               puts "Field with id '#{field.id}' already belongs to this section"
@@ -88,24 +134,19 @@ module Ecoportal
               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
 
@@ -118,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,6 +7,10 @@ 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
@@ -24,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
@@ -38,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)
@@ -53,12 +67,18 @@ 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, 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(section, pos: NOT_USED, before: NOT_USED, after: NOT_USED)
@@ -108,7 +128,6 @@ module Ecoportal
             return if pos < 0
             secs[pos]
           end
-
         end
       end
     end

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

@@ -17,6 +17,13 @@ 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|
@@ -25,11 +32,40 @@ module Ecoportal
             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)

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,15 +24,21 @@ 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|
             unless !hash
@@ -90,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

@@ -10,7 +10,7 @@ module Ecoportal
           embeds_many :permits, klass: "Ecoportal::API::V2::Page::Permit"
           passarray   :force_errors, :subtags, order_matters: false
 
-          # `id` of the stage we got the data of.
+          # @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
@@ -22,6 +22,44 @@ module Ecoportal
             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_version.rb

@@ -1,5 +1,5 @@
 module Ecoportal
   module API
-    GEM2_VERSION = "0.8.13"
+    GEM2_VERSION = "0.8.14"
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ecoportal-api-v2
 version: !ruby/object:Gem::Version
-  version: 0.8.13
+  version: 0.8.14
 platform: ruby
 authors:
 - Oscar Segura
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2021-09-02 00:00:00.000000000 Z
+date: 2021-09-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -218,6 +218,10 @@ files:
 - lib/ecoportal/api/v2/page/component/signature_field.rb
 - lib/ecoportal/api/v2/page/component/tag_field.rb
 - lib/ecoportal/api/v2/page/components.rb
+- lib/ecoportal/api/v2/page/force.rb
+- lib/ecoportal/api/v2/page/force/binding.rb
+- lib/ecoportal/api/v2/page/force/bindings.rb
+- lib/ecoportal/api/v2/page/forces.rb
 - lib/ecoportal/api/v2/page/permission_flags.rb
 - lib/ecoportal/api/v2/page/permit.rb
 - lib/ecoportal/api/v2/page/section.rb