ecoportal-api-v2 0.8.7 → 0.8.11

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a332d0750443bc0d8be5b549032b9f62c493cbff07905dc353f0949248c5120a
-  data.tar.gz: d89435fd4cebfef7662148f5fc335cc792353666c80e1f5ab07c6dc0a8f73744
+  metadata.gz: 3d906a6021cc5fab91f2b2d8f32084d61449eab23b8162ade9e01308bdce3584
+  data.tar.gz: fe195a200860d2696acfc465accb16ee8758f5dfc00d9cbeffed836d654c1f8c
 SHA512:
-  metadata.gz: 611c6b781a09105bb22a24b85e3b9046513505691bef6256774837fa14a7e1c9ca6061795fe35068b5c5340e82f07d2281682ad2d05b06673495285fabcf1dfb
-  data.tar.gz: 3b9f347aac2994262df8dd864b564010a37ec01a5d7ed2da4ecdc69bb49fff2ff85d8f858cb1761baa770e352131f9ee444fcacd765888ef7b3a338902b567e6
+  metadata.gz: 74b45e1025b675e5675a0d6822fcefee7c464ae0759deb0da1004913793cef32bd2ad14f3656ab5b2177ae80bd5ac79fe9451e74ff9faefac24179f8ba9b621c
+  data.tar.gz: 8cab8147deaa80f9d3cd6dd5b31a42d0ba018001ca825e76a9a388999daef2ff686240c546255e6b8ac1785b1b7236ff4c124761b66d7cc414fef3c018480019

data/CHANGELOG.md

@@ -1,9 +1,90 @@
 # Change Log
 All notable changes to this project will be documented in this file.
 
-## [0.8.7] - 2021-05-xx
+## [0.8.11] - 2021-08-27
 
 ### Added
+  - `Ecoportal::API::V2::Page#stages?`
+  - `Ecoportal::API::V2::Pages::PageStage#current_stage_id`
+  - `Ecoportal::API::V2::Registers#search` added option keyed parameter `:only_first`
+    - which will make the method return the first `Ecoportal::API::V2::Registers::SearchResults`
+    - This has been **added** with the aim of knowing how many results out of how many entries.
+
+### Changed
+  - `Ecoportal::API::V2::Pages::PageStage#update` won't update unless there's something to update.
+
+### Fixed
+
+
+## [0.8.10] - 2021-08-22
+
+### Added
+  - `Ecoportal::API::Common::Content::CollectionModel#[]` now supports position as well
+  - `Ecoportal::API::V2::Page::Component::FilesField#add_file`: support for adding files
+  - `Ecoportal::API::V2::Page::Component::PeopleField#viewable_fields`: support for managing `viewable_fields`
+
+### Changed
+
+### Fixed
+  - `Ecoportal::API::V2::Page::Component::FilesField`: was not requiring `File`
+  - `Ecoportal::API::V2::Page::Component::NumberField#value`: it was missing :/
+  - `Ecoportal::API::Common::Content::HashDiffPatch` did not support nested objects in Arrays, where the nested object wouldn't have a `patch_ver`. This **fix** allows for it
+    - `Ecoportal::API::Common::Content::DoubleModel.passforced` to define `methods` that should always be present. This allows to define `patch_ver` as a forced `key` in models that have it
+      - The enforcement (`self.class.enforce!`) happens on `initialize`
+      - `passenforced` subjacent model `forced_model_keys` is inheritable
+  - `Ecoportal::API::Common::Content::CollectionModel`:
+    - Method `upsert!` was not working fine the parameters `pos`, `before` and `after`
+    - Method `delete!` did not support position
+
+## [0.8.9] - 2021-08-16
+
+### Added
+  - `Ecoportal::API::Common::Content::ModelHelpers`
+    - Starting with `#same_string?`, this lib aims to offer a full set of helper comparers.
+  - `Ecoportal::API::V2::Page::Components#get_by_id`
+    - In future changes, method `[]` might be overriding the method of the parent class `CollectionModel`.
+  - `Ecoportal::API::V2::Page::PermissionFlags` to offer support to `can_permission`, `subscribed`, etc.
+  - `Ecoportal::API::V2::Page::Section#add_component` super handy helper to add fields to sections.
+  - `Ecoportal::API::V2::Page::Component::PeopleField#delete` to remove people using their ids.
+  - `Ecoportal::API::V2::Page::Component::GeoField` **added** suport for `#coordinates`
+    - With embedded object `Ecoportal::API::V2::Page::Component::GeoCoordinates`
+  - `#configure` method, to all the `Component` types (but `ChartField` s)
+    - This method allows to quickly set field properties.
+  - `Ecoportal::API::V2::Page::Sections#between`, aiming to obtain sections between two other ones
+
+
+### Changed
+  - `Ecoportal::API::V2::Page::Section` real support for `split` sections (right vs left)
+    - This is actually a **FIX**
+  - `Ecoportal::API::V2::Page::Component::DateField#create_event`
+    - Now it switches to _allow future dates_
+  - `Ecoportal::API::V2::Page::Component::SelectionField#add_option`, the `name` parameter is now optional
+    - This change aims to make it consistent with the back-end.
+  - To its actual `Boolean` type some properties
+    - All `Component` types
+
+### Fixed
+  - `Ecoportal::API::Common::Content::HashDiffPatch` did not support `Hash` values without `id` or `patch_ver`
+    - This fix should allow them to flow to the update
+  - `Ecoportal::API::V2::Page::Component::ChartField` did not have `doc` for `mode` based configuration
+  - `Ecoportal::API::Common::Content::ArrayModel#insert_one`
+    - When `pos`, `before` & `after` were `nil` it was failing to attach the element.
+  - `Ecoportal::API::V2::Page::Sections#add` was not adding in the correct order
+  - `Ecoportal::API::V2::Page::Section.new_doc` was unnecessarily giving `9999` as default weight
+
+## [0.8.8] - 2021-08-03
+
+### Added
+  - `Ecoportal::API::V2::Page::Component::ChartField::Benchmark`
+  - Support to convert selection options between numeric and text type.
+  - Add `Permit` object to `Page` and `Stage`
+
+### Changed
+  - Removed `Stages.ordered_stages`: detected bug with Enumerable iteration
+
+
+## [0.8.7] - 2021-05-25
+
 ### Changed
   - Upgrade `ecoportal-api` gem
 

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

@@ -3,7 +3,8 @@ module Ecoportal
     module Common
       module Content
         # Class to handle a plain Array embedded in a Hashed model.
-        # @note its purpose is to handle an Array of basic objects (i.e. `Date`, `String`, `Number`)
+        # @note
+        #   - Its purpose is to handle an Array of basic objects (i.e. `Date`, `String`, `Number`)
         class ArrayModel < Content::DoubleModel
           class TypeMismatchedComparison < Exception
             def initialize (this: nil, that: msg = "Trying to compare objects with different behavior.")
@@ -222,15 +223,16 @@ module Ecoportal
           def insert_one(value, pos: NOT_USED, before: NOT_USED, after: NOT_USED)
             i = index(value)
             return i if (i && uniq?)
-
             pos = case
                   when used_param?(pos)
-                    pos
+                    pos || length
                   when used_param?(before)
-                    index(before)
+                    before ? index(before) : length
                   when used_param?(after)
-                    if i = index(after)
-                      i + 1
+                    if after
+                      if i = index(after) then i + 1 end
+                    else
+                      length
                     end
                   else
                     length

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

@@ -2,6 +2,9 @@ module Ecoportal
   module API
     module Common
       module Content
+        # CollectionModel aims to deal with Arrays of actual objects.
+        # @note to be able to refer to the correct element of the Collection,
+        #   it is required that those elements have a unique `key` that allows to identify them
         class CollectionModel < Content::DoubleModel
 
           class << self
@@ -140,17 +143,21 @@ module Ecoportal
           end
 
           # Get an element usign the `key`.
+          # @param value [String, Hash, Ecoportal::API::Common::Content::DoubleModel]
+          # @return [Object] the `items_class` element object
           def [](value)
             items_by_key[get_key(value)]
           end
 
+          # @return [Array<Object>] the `items_class` element object
           def values_at(*keys)
             keys.map {|key| self[key]}
           end
 
           # Tries to find the element `value`, if it exists, it updates it
-          # Otherwise it pushes it to the end
-          # @return the element
+          #   Otherwise it pushes it to the end
+          # @value [Hash, Ecoportal::API::Common::Content::DoubleModel] the eleement to be added
+          # @return [Object] the `items_class` element object
           def upsert!(value, pos: NOT_USED, before: NOT_USED, after: NOT_USED)
             unless value.is_a?(Hash) || value.is_a?(Content::DoubleModel)
               raise "'Content::DoubleModel' or 'Hash' doc required"
@@ -160,15 +167,20 @@ module Ecoportal
             if item = self[value]
               item.replace_doc(item_doc)
             else
-              _doc_upsert(item_doc, pos: pos, before: before, after: after)
+              pos_idx = _doc_upsert(item_doc, pos: pos, before: before, after: after)
             end
             (item || self[item_doc]).tap do |item|
               yield(item) if block_given?
             end
           end
 
+          # Deletes `value` from this `CollectionModel` instance
+          # @param value [String, Hash, Ecoportal::API::Common::Content::DoubleModel]
+          #   - When used as `String`, the `key` value (i.e. `id` value) is expected
+          #   - When used as `Hash`, it should be the `doc` of the target element
+          #   - When used as `DoubleModel`, it should be the specific object to be deleted
           def delete!(value)
-            unless value.is_a?(Hash) || value.is_a?(Content::DoubleModel)
+            unless value.is_a?(Hash) || value.is_a?(Content::DoubleModel) || value.is_a?(String)
               raise "'Content::DoubleModel' or 'Hash' doc required"
             end
             if item = self[value]
@@ -186,7 +198,7 @@ module Ecoportal
             variables_remove!
           end
 
-          # Gets the `key` of the object
+          # Gets the `key` of the object `value`
           def get_key(value)
             case value
             when Content::DoubleModel
@@ -195,6 +207,8 @@ module Ecoportal
               value[items_key]
             when String
               value
+            when Numeric
+              get_key(self.to_a[value])
             end
           end
 
@@ -235,27 +249,22 @@ module Ecoportal
             super
           end
 
+          # Deletes `value` from `doc` (here referred as `_doc_items`)
+          # @return [Object] the element deleted from `doc`
           def _doc_delete(value)
             if current_pos = _doc_key(value)
-              _doc_items.delete_at(current_pos)
-              on_change
+              _doc_items.delete_at(current_pos).tap do |deleted|
+                on_change
+              end
             end
           end
 
           def _doc_upsert(value, pos: NOT_USED, before: NOT_USED, after: NOT_USED)
-            current_pos = _doc_key(value)
-            pos = case
-              when used_param?(pos)
-                pos
-              when used_param?(before)
-                _doc_key(before)
-              when used_param?(after)
-                #puts "to add after #{after.id}"
-                if i = _doc_key(after)
-                  i + 1
-                end
-              end
+            current_pos = if elem = self[value]
+              _doc_key(elem)
+            end
 
+            pos   = scope_position(pos: pos, before: before, after: after)
             pos ||= current_pos
 
             if current_pos && pos
@@ -264,7 +273,6 @@ module Ecoportal
             end
 
             pos = (pos && pos < _doc_items.length)? pos : _doc_items.length
-
             pos.tap do |i|
               _doc_items.insert(pos, value)
               on_change
@@ -272,6 +280,23 @@ module Ecoportal
 
           end
 
+          def scope_position(pos: NOT_USED, before: NOT_USED, after: NOT_USED)
+            case
+            when used_param?(pos)
+              if elem = self[pos]
+                _doc_key(elem) - 1
+              end
+            when used_param?(before)
+              if elem = self[before]
+                _doc_key(elem) - 1
+              end
+            when used_param?(after)
+              if elem = self[after]
+                _doc_key(elem)
+              end
+            end
+          end
+
         end
       end
     end

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

@@ -10,6 +10,7 @@ module Ecoportal
         class DoubleModel < Common::BaseModel
           NOT_USED = Common::Content::ClassHelpers::NOT_USED
           extend Common::Content::ClassHelpers
+          include Common::Content::ModelHelpers
 
           class UnlinkedModel < Exception
             def initialize (msg = "Something went wrong when linking the document.", from: nil, key: nil)
@@ -36,6 +37,8 @@ module Ecoportal
 
             # Same as `attr_reader` but links to a subjacent `Hash` model property
             # @note it does **not** create an _instance variable_
+            # @param methods [Array<Symbol>] the method that exposes the value
+            #   as well as its `key` in the underlying `Hash` model.
             def pass_reader(*methods)
               methods.each do |method|
                 method = method.to_s.freeze
@@ -51,6 +54,8 @@ module Ecoportal
 
             # Same as `attr_writer` but links to a subjacent `Hash` model property
             # @note it does **not** create an _instance variable_
+            # @param methods [Array<Symbol>] the method that exposes the value
+            #   as well as its `key` in the underlying `Hash` model.
             def pass_writer(*methods)
               methods.each do |method|
                 method = method.to_s.freeze
@@ -69,6 +74,8 @@ module Ecoportal
             #  no chance you can avoid invinite loop for `get_key` without setting an
             #  instance variable key at the moment of the object creation, when the
             #  `doc` is firstly received
+            # @param method [Symbol] the method that exposes the value
+            #   as well as its `key` in the underlying `Hash` model.
             def passkey(method)
               method   = method.to_s.freeze
               var      = instance_variable_name(method)
@@ -90,7 +97,33 @@ module Ecoportal
               self
             end
 
+            # These are methods that should always be present in patch update
+            # @note
+            #    - `DoubleModel` can be used with objects that do not use `patch_ver`
+            #    - This ensures that does that do, will get the correct patch update model
+            # @param method [Symbol] the method that exposes the value
+            #   as well as its `key` in the underlying `Hash` model.
+            # @param default [Value] the default value that
+            #   this `key` will be written in the model when it doesn't exixt
+            def passforced(method, default: , read_only: false)
+              model_forced_keys[method.to_s.freeze] = default
+              passthrough(method, read_only: read_only)
+            end
+
+            # Ensures `doc` has the `model_forced_keys`. If it doesn't, it adds those missing
+            #   with the defined `default` values
+            def enforce!(doc)
+              return unless doc && doc.is_a?(Hash)
+              return if model_forced_keys.empty?
+              model_forced_keys.each do |key, default|
+                doc[key] = default unless doc.key?(key)
+              end
+              doc
+            end
+
             # Same as `attr_accessor` but links to a subjacent `Hash` model property
+            # @param methods [Array<Symbol>] the method that exposes the value
+            #   as well as its `key` in the underlying `Hash` model.
             # @param read_only [Boolean] should it only define the reader?
             def passthrough(*methods, read_only: false)
               pass_reader *methods
@@ -100,6 +133,8 @@ module Ecoportal
 
             # To link as a `Time` date to a subjacent `Hash` model property
             # @see Ecoportal::API::Common::Content::DoubleModel#passthrough
+            # @param methods [Array<Symbol>] the method that exposes the value
+            #   as well as its `key` in the underlying `Hash` model.
             # @param read_only [Boolean] should it only define the reader?
             def passdate(*methods, read_only: false)
               pass_reader(*methods) {|value| to_time(value)}
@@ -109,7 +144,21 @@ module Ecoportal
               self
             end
 
+            # To link as a `Boolean` to a subjacent `Hash` model property
+            # @param methods [Array<Symbol>] the method that exposes the value
+            #   as well as its `key` in the underlying `Hash` model.
+            # @param read_only [Boolean] should it only define the reader?
+            def passboolean(*methods, read_only: false)
+              pass_reader(*methods) {|value| value}
+              unless read_only
+                pass_writer(*methods) {|value| !!value}
+              end
+              self
+            end
+
             # To link as plain `Array` to a subjacent `Hash` model property
+            # @param methods [Array<Symbol>] the method that exposes the value
+            #   as well as its `key` in the underlying `Hash` model.
             # @param order_matters [Boolean] does the order matter
             # @param uniq [Boolean] should it contain unique elements
             def passarray(*methods, order_matters: true, uniq: true)
@@ -131,6 +180,10 @@ module Ecoportal
             end
 
             # Helper to embed one nested object under one property
+            # @param method [Symbol] the method that exposes the embeded object
+            # @param key [Symbol] the `key` that embeds it to the underlying `Hash` model
+            # @nullable [Boolean] to specify if this object can be `nil`
+            # @param klass [Class, String] the class of the embedded object
             def embeds_one(method, key: method, nullable: false, klass:)
               embed(method, key: key, nullable: nullable, multiple: false, klass: klass)
             end
@@ -138,7 +191,11 @@ module Ecoportal
             # @note
             #   - if you have a dedicated `Enumerable` class to manage `many`, you should use `:enum_class`
             #   - otherwise, just indicate the child class in `:klass` and it will auto generate the class
-            # @param
+            # @param method [Symbol] the method that exposes the embeded object
+            # @param key [Symbol] the `key` that embeds it to the underlying `Hash` model
+            # @param order_matters [Boolean] to state if the order will matter
+            # @param klass [Class, String] the class of the individual elements it embeds
+            # @param enum_class [Class, String] the class of the collection that will hold the individual elements
             def embeds_many(method, key: method, order_matters: false, order_key: nil, klass: nil, enum_class: nil)
               if enum_class
                 eclass = enum_class
@@ -175,8 +232,15 @@ module Ecoportal
               end
             end
 
+            # The list of keys that will be forced in the model
+            def model_forced_keys
+              @forced_model_keys ||= {}
+            end
+
           end
 
+          inheritable_class_vars :forced_model_keys
+          
           attr_reader :_parent, :_key
 
           def initialize(doc = {}, parent: self, key: nil)
@@ -184,6 +248,8 @@ module Ecoportal
             @_parent   = parent || self
             @_key      = key    || self
 
+            self.class.enforce!(doc)
+
             if _parent == self
               @doc          = doc
               @original_doc = JSON.parse(@doc.to_json)
@@ -200,11 +266,13 @@ module Ecoportal
             _parent.root
           end
 
+          # @return [String] the `value` of the `key` method (i.e. `id` value)
           def key
             raise "No key_method defined for #{self.class}" unless key_method?
             self.method(key_method).call
           end
 
+          # @param [String] the `value` of the `key` method (i.e. `id` value)
           def key=(value)
             raise "No key_method defined for #{self.class}" unless key_method?
             method = "#{key_method}="
@@ -223,16 +291,25 @@ module Ecoportal
             end
           end
 
+          # @return [nil, Hash] the underlying `Hash` model as is (carrying current changes)
           def doc
             raise UnlinkedModel.new(from: "#{self.class}#doc", key: _key) unless linked?
-            return @doc if is_root?
-            _parent.doc.dig(*[_doc_key(_key)].flatten)
+            if is_root?
+              @doc
+            else
+              _parent.doc.dig(*[_doc_key(_key)].flatten)
+            end
           end
 
+          # The `original_doc` holds the model as is now on server-side.
+          # @return [nil, Hash] the underlying `Hash` model as after last `consolidate!` changes
           def original_doc
             raise UnlinkedModel.new(from: "#{self.class}#original_doc", key: _key) unless linked?
-            return @original_doc if is_root?
-            _parent.original_doc.dig(*[_doc_key(_key)].flatten)
+            if is_root?
+              @original_doc
+            else
+              _parent.original_doc.dig(*[_doc_key(_key)].flatten)
+            end
           end
 
           def as_json
@@ -243,19 +320,31 @@ module Ecoportal
             doc.to_json(*args)
           end
 
+          # @return [nil, Hash] the patch `Hash` model including only the changes between
+          #   `original_doc` and `doc`
           def as_update
             new_doc = as_json
             Common::Content::HashDiffPatch.patch_diff(new_doc, original_doc)
           end
 
+          # @return [Boolean] stating if there are changes
           def dirty?
             as_update != {}
           end
 
+          # It makes `original_doc` to be like `doc`
+          # @note
+          #   - after executing it, there will be no pending changes
+          #   - you should technically run this command, after a successful update request to the server
           def consolidate!
             replace_original_doc(JSON.parse(doc.to_json))
           end
 
+          # It makes `doc` to be like `original`
+          # @note
+          #   - after executing it, changes in `doc` will be lost
+          #   - you should technically run this command only if you want to remove certain changes
+          # @key [Symbol] the specific part of the model you want to `reset`
           def reset!(key = nil)
             if key
               keys    = [key].flatten.compact