scrivito_sdk 0.71.2 → 0.90.0.rc1

data/lib/scrivito/meta_data_collection.rb

@@ -1,18 +1,52 @@
 module Scrivito
+# @api public
 #
 # This class represents a collection of meta data attributes.
 #
-# @api beta
+# == Available meta data attributes
+# All binaries have the meta attributes +content_length+ and +content_type+, in addition, PDFs
+# and images have attributes specfic to their type.
 #
+# If not specified otherwise, the attributes contain +string+ values.
+#
+# [+content_length (Number)+]         Size in bytes of the given file.
+# [+content_type+]                    MIME-type of the given file.
+#
+# == Available meta data attributes for PDFs
+#
+# [+text+]                            Text content of the PDF document.
+#
+# == Available meta data attributes for Images
+#
+# The meta data attributes starting with +iptc_+ or +exif_+ are extracted from the image itself
+# and therefore may not be available for every image. +Iptc+ and +exif+ are both standardized
+# formats supported by a wide array of software and hardware, like cameras and phones.
+#
+# [+width (Number)+]                  Width in pixels.
+# [+height (Number)+]                 Height in pixels.
+# [+exif_copyright+]                  Copyright of the image.
+# [+exif_date_time+]                  The date at which the image was produced.
+#
+# [+iptc_keywords (Array<String>)+ ]  A list of keywords associated with the image.
+# [+iptc_headline+]                   The headline of the image.
+# [+iptc_copyright+]                  Copyright of the image.
+# [+iptc_byline+]                     The name of the image creator.
+# [+iptc_credit+]                     Contains the persons or companies that should be credited.
+# [+iptc_source+]                     The original copyright holder.
+# [+iptc_profile+]                    The color profile of the image.
+# [+iptc_city+]                       The city in which the image was produced.
+# [+iptc_state+]                      The state in which the image was produced.
+# [+iptc_country_name+]               The country in which the image was produced.
+# [+iptc_country_code+]               The code of the country in which the image was produced.
 class MetaDataCollection
   def initialize(attributes)
     @attributes = ActiveSupport::HashWithIndifferentAccess.new(attributes)
   end
 
+  # @api public
   #
   # Find value of a meta data attribute.
   #
-  # @api beta
   # @param name [Symbol, String] the name of the meta data attribute.
   # @return [String, Array, Fixnum, Date, nil] meta data attribute value if found or +nil+ otherwise.
   def [](name)

data/lib/scrivito/obj_collection.rb

@@ -29,21 +29,38 @@ module Scrivito
       find_using(id_or_list, :find_by_including_deleted)
     end
 
-    # Find the {BasicObj Obj} that has the given path.
-    # Returns +nil+ if no matching object exists.
-    # @param [String] path Path of the {BasicObj Obj}.
-    # @return [Obj,NilClass]
+    #
+    # Find the {Scrivito::BasicObj Obj} that has the given +path+.
+    #
     # @api public
+    #
+    # @note If there is more than one {Scrivito::BasicObj Obj} with the given +path+,
+    #   then the {Scrivito::BasicObj Obj} with the smallest +id+ will be returned.
+    #
+    # @param [String] path Path of the {Scrivito::BasicObj Obj}.
+    #
+    # @return [Scrivito::BasicObj] if an {Scrivito::BasicObj Obj} with the given +path+ exists.
+    # @return [NilClass] if no {Scrivito::BasicObj Obj} with the given +path+ exists.
+    #
     def find_by_path(path)
-      find_by(:path, [path]).first.first
+      find_by(:path, [path]).first.min_by(&:id)
     end
 
-    # Returns the {BasicObj Obj} that has the given permalink, or +nil+ if no matching object exists.
-    # @param [String] permalink The permalink of the {BasicObj Obj}.
-    # @return [Obj,NilClass]
+    #
+    # Returns the {Scrivito::BasicObj Obj} that has the given +permalink+.
+    #
     # @api public
+    #
+    # @note If there is more than one {Scrivito::BasicObj Obj} with the given +permalink+,
+    #   then the {Scrivito::BasicObj Obj} with the smallest +id+ will be returned.
+    #
+    # @param [String] permalink The permalink of the {BasicObj Obj}.
+    #
+    # @return [Scrivito::BasicObj] if an {Scrivito::BasicObj Obj} with the given +permalink+ exists.
+    # @return [NilClass] if no {Scrivito::BasicObj Obj} with the given +permalink+ exists.
+    #
     def find_by_permalink(permalink)
-      find_by(:permalink, [permalink]).first.first
+      find_by(:permalink, [permalink]).first.min_by(&:id)
     end
 
     # Returns an {ObjSearchEnumerator} with the given initial subquery consisting of the four arguments.

data/lib/scrivito/obj_facet_value.rb

@@ -0,0 +1,40 @@
+# Instances of this class represent the result of a faceted search.
+# @api beta
+class ObjFacetValue
+
+  def initialize(value, total, included_objs = [])
+    @name = value
+    @count = total
+    @included_objs = included_objs
+  end
+
+  # @api beta
+  # The value of the attribute name of this ObjFacetValue.
+  #
+  # @return [String]
+  def name
+    @name
+  end
+
+  # @api beta
+  # Total number of Objs available that have this value.
+  #
+  # Note that this refers to all Objs,
+  # not just the Objs included in this search.
+  # Also note that the count is approximate.
+  # @return [Integer]
+  def count
+    @count
+  end
+
+  # @api beta
+  # The Objs that were included in this search.
+  #
+  # if you did not specify +include_objs+ in your facet options,
+  # an empty array is returned.
+  # The Objs are ordered by relevance.
+  # @return [Array<BasicObj>]
+  def included_objs
+    @included_objs
+  end
+end

data/lib/scrivito/obj_search_enumerator.rb

@@ -22,23 +22,19 @@ module Scrivito
   # [+:id+]             Id of an {Scrivito::BasicObj Obj}. This is a +string+ field.
   # [+:_path+]          Path of an {Scrivito::BasicObj Obj}. This is a +string+ field.
   # [+:_name+]          Name of an {Scrivito::BasicObj Obj}. This is a +string+ field.
-  # [+:title+]          Title of an {Scrivito::BasicObj Obj}. This is a +string+ field.
-  # [+:body+]           Body of an {Scrivito::BasicObj Obj}. This is an +html+ field. Thus, only the
-  #                     +contains+ and +contains_prefix+ operators can be applied to this field.
   # [+:_obj_class+]     Object class of an {Scrivito::BasicObj Obj}. This is a +string+ field.
   # [+:_permalink+]     Permalink of an {Scrivito::BasicObj Obj}. This is a +string+ field.
   # [+:_last_changed+]  Date of last change of an {Scrivito::BasicObj Obj}.
   # [every +_:custom_attribute_+] Custom attribute of an {Scrivito::BasicObj Obj}. Note that depending on the attribute type (e.g. an +html+ field), some operators cannot be applied.
   #
-  # All values are stored as strings.
+  # == Currently available operators
   #
-  # Date values are stored in the format +YYYYMMDDHHMMSS+ in UTC. For example, 2000-01-01 00:00:00
-  # UTC is stored as "+20000101000000+". This is relevant for string comparisons in which the
-  # +is_less_than+ and +is_greater_than+ operators are used.
+  # === +contains+ and +contains_prefix+
   #
-  # == Currently available operators
+  # These operators are intended for full text search of natural language texts.
+  # They are applicable to +string+, +stringlist+, +enum+, +multienum+ and +html+ fields.
   #
-  # For +:contains+ and +:contains_prefix+, the examples are based on the following field value:
+  # For +contains+ and +contains_prefix+, the examples are based on the following field value:
   # "Behind every cloud is another cloud."
   #
   # [+:contains+]         Searches for one or more whole words. Each word needs to be present.
@@ -50,7 +46,7 @@ module Scrivito
   #                       ✘ "behi clo" (not whole words)
   #
   #                       ✘ "behind everything" (second word does not match)
-  # [+:contains_prefix+]  Searches for one prefix. A whole word also counts as a prefix.
+  # [+:contains_prefix+]  Searches for a word prefix.
   #
   #                       Example subquery values:
   #
@@ -58,12 +54,29 @@ module Scrivito
   #
   #                       ✔ "Every" (case insensitive)
   #
-  # For +:equals+ and +:starts_with+, the examples are based on the following field value:
+  # === +equals+ and +starts_with+
+  #
+  # These operators are intended for programmatic comparions of string and date values.
+  #
+  # The +equals+ and +prefix+ operators have some limits with regard to string length.
+  # String values are only guaranteed to be considered if they are at most 1000 characters in length.
+  # String values of more than 1000 characters may be ignored by these operators.
+  #
+  # The +prefix+ operator also has a precision limit:
+  # Only prefixes of up to 20 characters are guaranteed to be matched.
+  # If you supply a prefix of more than 20 characters, the additional characters may be ignored.
+  #
+  # When combined with the system attribute +_path+, the operator +prefix+ has some special functionality:
+  # There is not precision limit, i.e. a prefix of arbitrary length may be used to match on +_path+.
+  # Also, prefix matching on +_path+ automatically matches entire path components,
+  # i.e. the prefix matching is delimited by slashes (the character +'/'+).
+  #
+  # For +equals+ and +starts_with+, the examples are based on the following field value:
   # "Some content."
   #
   # [+:equals+]           The +field+ value needs to be identical to the +value+ of this subquery.
   #
-  #                       Only applicable to +string+, +enum+, +multienum+ and +date+ fields.
+  #                       Applicable to +string+, +stringlist+, +enum+, +multienum+ and +date+ fields.
   #
   #                       Example subquery values:
   #
@@ -73,7 +86,7 @@ module Scrivito
   #
   # [+:starts_with+]      The +field+ value needs to start exactly with the +value+ of this subquery.
   #
-  #                       Only applicable to +string+, +enum+, +multienum+ and +date+ fields.
+  #                       Applicable to +string+, +stringlist+, +enum+ and +multienum+ fields.
   #
   #                       Example subquery values:
   #
@@ -83,28 +96,35 @@ module Scrivito
   #
   #                       ✘ "content" (not prefix of the whole value)
   #
-  # For +:is_less_than+ and +:is_greater_than+, the examples are based on the following field value (date string):
-  # "20000101000000"
+  # === +is_less_than+ and +is_greater_than+
   #
-  # [+:is_less_than+]     Matches if the field string value is less than the subquery string value.
+  # These operators are intended for comparions on +date+ attributes and on numerical metadata, for example the width of an image.
   #
-  #                       Only applicable to +string+, +enum+, +multienum+ and +date+ fields.
+  # For +is_less_than+ and +is_greater_than+, the examples are based on the following date value:
+  # +Time.new(2000,01,01,00,00,00)+
   #
-  #                       Example subquery values:
+  # [+:is_less_than+]     Matches if the field value is less than the subquery string value.
   #
-  #                       ✔ "19991231235959" (is less than "20000101000000")
+  #                       Example subquery values:
   #
-  #                       ✘ "20000101000000" (equal, not less than)
+  #                       ✔ +Time.new(1999,12,31,23,59,59)+ (is less than)
   #
-  # [+:is_greater_than+]  Matches if the field string value is greater than the subquery string value.
+  #                       ✘ +Time.new(2000,01,01,00,00,00)+ (equal, not less than)
   #
-  #                       Only applicable to +string+, +enum+, +multienum+ and +date+ fields.
+  # [+:is_greater_than+]  Matches if the field value is greater than the subquery string value.
   #
   #                       Example subquery values:
   #
-  #                       ✔ "20000101000001" (is greater than "20000101000000")
+  #                       ✔ +Time.new(2000,01,01,00,00,01)+ (is greater than)
+  #
+  #                       ✘ +Time.new(2000,01,01,00,00,00)+ (equal, not greater than)
   #
-  #                       ✘ "20000101000000" (equal, not greater than)
+  # == Matching +multienum+ and +stringlist+
+  #
+  # Attributes of type +multienum+ and +stringlist+ contain an array of strings.
+  # Each of these strings is searched individually.
+  # A search query matches a +multienum+ or +stringlist+, if at least one string in the list matches.
+  # Example: A query using the operator +:equals+ and the value +"Eggs"+ matches an Obj containing +["Spam","Eggs"]+ in a +stringlist+ or +multienum+ attribute.
   #
   # @api public
   class ObjSearchEnumerator
@@ -128,7 +148,7 @@ module Scrivito
     # @param [Symbol, String, Array<Symbol, String>] field Name(s) of the field(s) to be searched.
     #   For arrays, the subquery matches if one or more of these fields meet this criterion.
     # @param [Symbol, String] operator See "Currently available operators" above.
-    # @param [String, Array<String>] value The value(s) to compare with the field value(s) using the
+    # @param [String, Date, Time, Array<String, Date, Time>] value The value(s) to compare with the field value(s) using the
     #   +operator+ of this subquery. For arrays, the subquery matches if the condition is met for
     #   one or more of the array elements.
     # @param [Hash] boost A hash where the keys are field names and their values are boosting
@@ -164,7 +184,7 @@ module Scrivito
     # @param [Symbol, String] operator Only applicable to subqueries in which the +equals+,
     #   +starts_with+, +is_greater_than+ or +is_less_than+ operator is used.
     #   (See "Currently available operators" above).
-    # @param [String, Array<String>] value The value(s) to compare with the field value(s) using the
+    # @param [String, Date, Time, Array<String, Date, Time>] value The value(s) to compare with the field value(s) using the
     #   +operator+ of this subquery. For arrays, the subquery matches if the condition is met for
     #   one or more of the array elements.
     # @return [Scrivito::ObjSearchEnumerator]
@@ -184,6 +204,12 @@ module Scrivito
     end
 
     # Orders the results by +field_name+.
+    #
+    # Applicable to the attribute types +string+, +enum+ and +date+.
+    #
+    # There is a precision limit when sorting string values:
+    # Only the first 50 characters of a string are guaranteed to be considered when sorting search results.
+    #
     # @param [Symbol, String] field_name This parameter specifies the field by which the hits are
     #   sorted (e.g. +:_path+).
     # @return [Scrivito::ObjSearchEnumerator]
@@ -206,7 +232,12 @@ module Scrivito
     end
 
     # Number of search results to be returned by each of the internal search requests.
-    # The default is +10+. The server may reduce large batches to a reasonable size.
+    # The default is +10+.
+    #
+    # Scrivito makes a best effort to return the given number of search results,
+    # but may under certain circumstances return larger or smaller batches due to technical
+    # reasons.
+    #
     # @param [Integer] size A value in the range from +1+ to +100+.
     # @return [Scrivito::ObjSearchEnumerator]
     # @api public
@@ -259,6 +290,11 @@ module Scrivito
     end
 
     # The total number of hits.
+    #
+    # This number is an approximation. Scrivito makes a best effort to deliver
+    # the exact number of hits. But due to technical reasons, the returned number may differ
+    # from the actual number under certain circumstances.
+    #
     # @return [Integer]
     # @api public
     def size
@@ -280,7 +316,9 @@ module Scrivito
     # Loads a single batch of search results from the backend.
     # @return [Array] of {Scrivito::BasicObj Obj}.
     # Usually returns +batch_size+ results if available,
-    # but may occasionally return fewer than +batch_size+ results (due to rate limit, for example).
+    # but may occasionally return more or fewer than +batch_size+ results
+    # (due to technical reasons). If you need an exact number of hits, use
+    # methods from +Enumerable+, for example +take+.
     # @api public
     def load_batch
       next_batch = fetch_next_batch(options[:offset] || 0)
@@ -294,6 +332,79 @@ module Scrivito
     # @api public
     alias_method :count, :size
 
+    # @api public beta
+    # Perform a faceted search over an attribute to retrieve structured results for individual values of this attribute.
+    #
+    # Applicable to attribute types +string+, +stringlist+, +enum+, +multienum+.
+    #
+    # Please note that there is a precision limit for faceting:
+    # Only the first 50 characters of a string are guaranteed to be considered for faceting.
+    # If two string values have the same first 50 characters, they may be grouped into the same facet value.
+    #
+    # @param [String] attribute_name the name of an attribute
+    # @param [Hash] options the options to facet a request with.
+    # @option options [Integer] :limit maximum number of unique values to return. Defaults to 20.
+    # @option options [Integer] :include_objs number of Objs to fetch for each unique value. Defaults to 0.
+    #
+    # @return [Array<Scrivito::ObjFacetValue>]
+    #   A list of unique values that were found for the given attribute name. The list is
+    #   ordered by frequency, i.e. values occurring more frequently come first.
+    #
+    # @example Faceted request: colors of _big_ balloons.
+    #   facets = Balloon.where(:size, :equals, "big").facet("color")
+    #
+    #   # Big balloons come in 3 colors:
+    #   facets.count #=> 3
+    #
+    #   # There are 3 big red balloons:
+    #   red_balloons = facets.first
+    #   red_balloons.name #=> "red"
+    #   red_balloons.count #=> 3
+    #
+    #   # There are 2 big green balloons:
+    #   green_balloons = facets.second
+    #   green_balloons.name #=> "green"
+    #   green_balloons.count #=> 2
+    #
+    #   # There is 1 big blue balloon:
+    #   blue_balloons = facets.third
+    #   blue_balloons.name #=> "blue"
+    #   blue_balloons.count #=> 1
+    #
+    # @example Faceted request with limit: at most 2 colors of big balloons.
+    #   facets = Balloon.where(:size, :equals, "big").facet("color", limit: 2)
+    #
+    #   # Although there are 3 different colors of big balloons,
+    #   # only the first 2 colors will be taken into account.
+    #   facets.count # => 2
+    #
+    # @example Faceted request with included Objs.
+    #   facets = Balloon.where(:size, :equals, "big").facet("color", include_objs: 2)
+    #
+    #   facets.each do |facet|
+    #     facet.included_objs.each do |obj|
+    #       puts "#{obj.size} #{obj.color} #{obj.class}"
+    #     end
+    #   end
+    #
+    #   # If there are 3 big red balloons, 2 big green balloons and 1 big blue balloon,
+    #   # then this will produce:
+    #
+    #   "big red Balloon"
+    #   "big red Balloon"
+    #   "big green Balloon"
+    #   "big green Balloon"
+    #   "big blue Balloon"
+    #
+    # @raise [Scrivito::ClientError] If the maximum number of results has been exceeded.
+    #   The maximum number of results is limited to 100 with respect to the facets themselves and the included objs.
+    #
+    def facet(attribute_name, options = {})
+      facets_params = [{ attribute: attribute_name }.merge!(options)]
+      result = get_facet_value_objs(facets_params, [attribute_name])
+      result[attribute_name]
+    end
+
     private
 
     attr_reader :options
@@ -314,6 +425,62 @@ module Scrivito
       end
     end
 
+    def create_facet_value_objs(facet_arrays, obj_collection)
+      result = []
+      facet_arrays.map do |facet|
+        included_objs = []
+        if included_ids = get_objs_facet_ids(facet)
+          obj_collection.each do |basic_obj|
+            if included_ids.include? basic_obj.id
+              included_objs << basic_obj unless included_objs.include? basic_obj
+            end
+          end
+        end
+        result << ObjFacetValue.new(facet["value"], facet["total"], included_objs)
+      end
+      result
+    end
+
+    def get_all_facets_ids(facet_array)
+      result = []
+      facet_array.map do |facet|
+        result += get_objs_facet_ids(facet)
+      end
+      result
+    end
+
+    def get_objs_facet_ids(facet)
+      result = []
+      if included_ids = facet["results"]
+        included_ids.each { |obj| result << obj["id"] }
+      end
+      result
+    end
+
+    def get_facet_value_objs(facets_params, attributes_list = [])
+      result = attributes_list.each_with_object({}) { |v,h| h[v] = [] }
+      included_objs_ids = []
+      params = { facets: facets_params }
+
+      if query
+        offset = options[:offset] || 0
+        params.merge! search_dsl(offset)
+      end
+
+      params.reverse_merge!(size: 0)
+
+      request_result = CmsBackend.instance.search_objs(workspace, params)
+      request_result['facets'].each do |facets_array|
+        included_objs_ids += get_all_facets_ids(facets_array)
+      end
+
+      obj_collection = Scrivito::BasicObj.find(included_objs_ids)
+      request_result['facets'].each_with_index do |facets_array, index|
+        result[result.keys[index]] += create_facet_value_objs(facets_array, obj_collection)
+      end
+      result
+    end
+
     def operator_mapping(operator)
       case operator.to_sym
       when :contains