ecoportal-api-v2 0.8.12 → 0.8.16

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 692fe87a2a9dd089ee091bae7133915ac5c9ae4b0643be6086b57206569a1044
-  data.tar.gz: 4d9866b6e5727b176caaff881cb44a3cd13ca08418884e69283f8c64c0e80272
+  metadata.gz: 4655b94325aaad222aabf7ec6376aa4e0be39f03db94338ceab8fcd77dca229b
+  data.tar.gz: af7d89a41346d634dce2acea3c689e0f823b9ec85f68d662807939c2222e843d
 SHA512:
-  metadata.gz: b812fc350ccdfd173d8ca7b02b05bd0676eda8dac97e2a981cd6c87e1e62c7170744a352ef962144ffb24b3bf9eb43011156c78c09f22a00db154431fd2be5ca
-  data.tar.gz: 00c551099e991a339125e5a985f98aa918b8f9844e03b7b6ba79c6cc2fc5d9ffa4303eaee51c2acc6205932472cdf5324692a73d875e647ba0bcd685f676c60c
+  metadata.gz: a749ce7f98f2765c133d662c4257ba7f3bac24fb2b35a369f8e060dc97ff5ccd13a5c91be65fb004f3de31c98b3559eb4f91fdf6fb15e71d178004e66c407ac8
+  data.tar.gz: 454fc8004933d15357f0e4dc0e5d7e923b42876bb049cad72ea58a8b32a0b3246a3316c8fad05df22d16fa4c87296a9e8bdbda0932a73f7cad8e16ae4b386a41

data/CHANGELOG.md

@@ -1,12 +1,75 @@
 # Change Log
 All notable changes to this project will be documented in this file.
 
-## [0.8.12] - 2021-08-xx
+## [0.8.16] - 2021-09-xx
 
 ### Added
-  - `Ecoportal::API::V2::Pages::PageStage#current_stage`
-
 ### Changed
+### Fixed
+
+
+## [0.8.15] - 2021-09-29
+
+### Fixed
+  - Typo in `Section#component?`
+
+## [0.8.14] - 2021-09-28
+
+### 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
+
+### Fixed
+  - `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
+  - `Ecoportall::API::Common::Content::DoubleModel`
+    - `#replace_original_doc` had a couple of typos
+    - `#replace_doc` should only remove the variable referring to the current object and only if `new_doc` is `nil`
+  - `Ecoportal::API::Common::Content::CollectionModel` on insertion and deletion it was removing instance variable objects.
+    - There was no need for this approach, as the only necessary thing is to just keep those variable instances up to date in the correct unique access point to do so.
+    - Aside note: the reason why this was initially designed this way is because there were some difficulties to identify the existing elements in the subjacent model. Once `#passkey` as added, this difficulty could be overcome.
+  - `Ecoportal::API::Common::Content::ArrayModel` on initialize, default `doc` should be an `Array`
+
+## [0.8.12] - 2021-08-30
+
+### Added
+  - `Ecoportal::API::V2::Pages::PageStage#current_stage`
 
 ### Fixed
   - `Ecoportal::API::Common::Content::DocHelpers#get_body` typo and wrong parameters on call.

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

@@ -33,7 +33,7 @@ module Ecoportal
 
           end
 
-          def initialize(doc = {}, parent: self, key: nil)
+          def initialize(doc = [], parent: self, key: nil)
             super(doc, parent: parent, key: key)
           end
 
@@ -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,7 +109,14 @@ 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
+          #   - This method would have been better called `_doc_pos` :)
           def _doc_key(value)
             #print "*(#{value.class})"
             return super(value) unless value.is_a?(Hash) || value.is_a?(Content::DoubleModel)
@@ -149,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]}
@@ -167,7 +181,10 @@ module Ecoportal
             if item = self[value]
               item.replace_doc(item_doc)
             else
-              pos_idx = _doc_upsert(item_doc, pos: pos, before: before, after: after)
+              _doc_upsert(item_doc, pos: pos, before: before, after: after).tap do |pos_idx|
+                _items.insert(pos_idx, new_item(item_doc))
+                @indexed = false
+              end
             end
             (item || self[item_doc]).tap do |item|
               yield(item) if block_given?
@@ -185,6 +202,8 @@ module Ecoportal
             end
             if item = self[value]
               _doc_delete(item.doc)
+              @indexed = false
+              _items.delete(item)
             end
           end
 
@@ -195,7 +214,8 @@ module Ecoportal
           def items_key;      self.class.items_key;     end
 
           def on_change
-            variables_remove!
+            @indexed = false
+            #variables_remove!
           end
 
           # Gets the `key` of the object `value`
@@ -253,9 +273,7 @@ module Ecoportal
           # @return [Object] the element deleted from `doc`
           def _doc_delete(value)
             if current_pos = _doc_key(value)
-              _doc_items.delete_at(current_pos).tap do |deleted|
-                on_change
-              end
+              _doc_items.delete_at(current_pos)
             end
           end
 
@@ -275,7 +293,6 @@ module Ecoportal
             pos = (pos && pos < _doc_items.length)? pos : _doc_items.length
             pos.tap do |i|
               _doc_items.insert(pos, value)
-              on_change
             end
 
           end

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

@@ -240,7 +240,7 @@ module Ecoportal
           end
 
           inheritable_class_vars :forced_model_keys
-          
+
           attr_reader :_parent, :_key
 
           def initialize(doc = {}, parent: self, key: nil)
@@ -367,8 +367,8 @@ module Ecoportal
               @doc = new_doc
             else
               dig_set(_parent.doc, [_doc_key(_key)].flatten, new_doc)
-              _parent.variable_remove!(_key)
-              variables_remove!
+              _parent.variable_remove!(_key) unless new_doc
+              #variables_remove!
             end
           end
 
@@ -385,9 +385,9 @@ module Ecoportal
           def replace_original_doc(new_doc)
             raise UnlinkedModel.new(from: "#{self.class}#replace_original_doc", key: _key) unless linked?
             if is_root?
-              @orginal_doc = new_doc
+              @original_doc = new_doc
             else
-              dig_set(_parent.orginal_doc, [_doc_key(_key)].flatten, new_doc)
+              dig_set(_parent.original_doc, [_doc_key(_key)].flatten, new_doc)
             end
           end
 
@@ -409,11 +409,21 @@ module Ecoportal
 
           # Removes all the persistent variables
           def variables_remove!
+            #puts "going to remove vars: #{@_dim_vars} on #{self.class} (parent: #{identify_parent(self._parent)})"
             @_dim_vars.dup.map {|k| variable_remove!(k)}
           end
 
           private
 
+          def identify_parent(object)
+            case object
+            when Ecoportal::API::V2::Page::Stage
+              "stage #{object.name}"
+            when Ecoportal::API::V2::Page::Section
+              "section #{object.heading}"
+            end
+          end
+
           def instance_variable_name(key)
             self.class.instance_variable_name(key)
           end

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/action.rb

@@ -8,7 +8,7 @@ module Ecoportal
               def new_doc
                 {
                   "id"         => new_uuid,
-                  "weight"     => 9999
+                  "weight"     => 99
                 }
               end
             end

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

@@ -25,9 +25,9 @@ module Ecoportal
             end
 
             def ordered_tasks
-              actions.each_with_index.sort_by do |task, index|
-                (task.weight >= 9999) ? [index, index] : [task.weight, index]
-              end.map(&:first)
+              actions.sort_by.with_index do |task, index|
+                [task.weight, index]
+              end
             end
 
             # Quick config helper

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

@@ -19,9 +19,9 @@ module Ecoportal
             end
 
             def ordered_items
-              items.each_with_index.sort_by do |item, index|
-                (item.weight >= 9999) ? [index, index] : [item.weight, index]
-              end.map(&:first)
+              items.sort_by.with_index do |item, index|
+                [item.weight, index]
+              end
             end
 
             private

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

@@ -8,7 +8,7 @@ module Ecoportal
               def new_doc
                 {
                   "id"         => new_uuid,
-                  "position"   => 9999
+                  "position"   => 99
                 }
               end
             end

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

@@ -19,9 +19,9 @@ module Ecoportal
             end
 
             def ordered_files
-              items.each_with_index.sort_by do |file, index|
-                (file.position >= 9999) ? [index, index] : [file.position, index]
-              end.map(&:first)
+              items.sort_by.with_index do |file, index|
+                [file.position, index]
+              end
             end
 
             private

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

@@ -21,9 +21,9 @@ module Ecoportal
             end
 
             def ordered_stops
-              stops.each_with_index.sort_by do |stop, index|
-                (stop.threshold >= 9999) ? [index, index] : [stop.threshold, index]
-              end.map(&:first)
+              stops.sort_by.with_index do |stop, index|
+                [stop.threshold, index]
+              end
             end
 
           end

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

@@ -58,9 +58,9 @@ module Ecoportal
             end
 
             def ordered_options
-              options.each_with_index.sort_by do |option, index|
-                (option.weight >= 9999) ? [index, index] : [option.weight, index]
-              end.map(&:first)
+              options.sort_by.with_index do |option, index|
+                [option.weight, index]
+              end
             end
 
             # Quick config helper

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

@@ -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.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 com_or_id
+            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|
@@ -44,6 +54,35 @@ module Ecoportal
           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
@@ -57,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.12"
+    GEM2_VERSION = "0.8.16"
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ecoportal-api-v2
 version: !ruby/object:Gem::Version
-  version: 0.8.12
+  version: 0.8.16
 platform: ruby
 authors:
 - Oscar Segura
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2021-08-30 00:00:00.000000000 Z
+date: 2021-09-28 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