scrivito_sdk 1.0.0 → 1.1.0.rc1

data/lib/scrivito/obj_search_enumerator.rb

@@ -2,7 +2,7 @@
 module Scrivito
   # Provides an enumerator for iterating over the results of searches for CMS objects to retrieve
   # instances of these objects. This is achieved through the
-  # {http://ruby-doc.org/core-2.1.3/Enumerable.html +Enumerable+ mixin}, which provides methods such
+  # {http://ruby-doc.org/core/Enumerable.html +Enumerable+ mixin}, which provides methods such
   # as +map+, +select+ or +take+.
   #
   # This enumerator is lazy. If, for example, you are looking for {Scrivito::BasicObj Obj}s whose
@@ -13,7 +13,7 @@ module Scrivito
   #
   # To start searching, use one of the {Scrivito::BasicObj Obj} methods that return an
   # {Scrivito::ObjSearchEnumerator}. The preferred way is to start with
-  # {Scrivito::BasicObj.where Obj.where}.
+  # {Scrivito::BasicObj.where Obj.where} or {Scrivito::BasicObj.all Obj.all}.
   #
   # == Currently available fields and their values
   #
@@ -24,9 +24,18 @@ module Scrivito
   # [+:_name+]          Name of an {Scrivito::BasicObj Obj}. This is a +string+ 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}.
+  # [+:_last_changed+]  Date of last change to 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.
   #
+  # === Meta Data
+  #
+  # If an {Scrivito::BasicObj Obj} has a +binary+ attribute named +blob+, the meta data of this
+  # attribute is searchable. For a full list of the available meta data attributes, see the
+  # documentation of the {Scrivito::MetaDataCollection MetaDataCollection}. The meta data
+  # attribute name needs to be prefixed with +blob:+ when searching for it. So, for example,
+  # when searching for the width, you need to specify the attribute name using +blob:width+.
+  # Binary attributes other than +blob+ are not searchable.
+  #
   # == Currently available operators
   #
   # === +contains+ and +contains_prefix+
@@ -54,24 +63,15 @@ module Scrivito
   #
   #                       ✔ "Every" (case insensitive)
   #
-  # === +equals+ and +starts_with+
+  # === +equals+
   #
-  # These operators are intended for programmatic comparions of string and date values.
+  # The +equals+ operator is intended for programmatic comparisons of string and date values.
   #
-  # The +equals+ and +prefix+ operators have some limits with regard to string length.
+  # The operator has 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:
+  # For +equals+, 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.
@@ -84,6 +84,22 @@ module Scrivito
   #
   #                       ✘ "Some" (not exact value)
   #
+  # === +starts_with+
+  #
+  # The +starts_with+ is intended for programmatic comparions of string values.
+  #
+  # The +starts_with+ operator 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 +starts_with+ 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 +starts_with+, the examples are based on the following field value:
+  # "Some content."
+  #
   # [+:starts_with+]      The +field+ value needs to start exactly with the +value+ of this subquery.
   #
   #                       Applicable to +string+, +stringlist+, +enum+ and +multienum+ fields.
@@ -98,7 +114,9 @@ module Scrivito
   #
   # === +is_less_than+ and +is_greater_than+
   #
-  # These operators are intended for comparions on +date+ attributes and on numerical metadata, for example the width of an image.
+  # These operators are intended for comparing +date+ values or numerical metadata, for example the width of an image.
+  # It only considers attributes of {Scrivito::BasicObj Obj}s and _not_ of {Scrivito::BasicWidget Widget}s.
+  # Therefore, {Scrivito::BasicWidget Widget} attributes are not searchable using the +is_less_than+ and +is_greater_than+ operators.
   #
   # 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)+
@@ -133,9 +151,10 @@ module Scrivito
     attr_reader :workspace
 
     attr_reader :query
-    def initialize(workspace)
+    def initialize(workspace, batch_size = nil)
       @workspace = workspace
-      @options = {}
+      @batch_size = batch_size
+      @options = { offset: 0 }
     end
 
     # @group Chainable methods
@@ -168,7 +187,7 @@ module Scrivito
               "Valid operators are: #{valid_boost_operators.join(', ')}"
         end
       end
-      @size = nil
+      reset_for_changed_query
       @query = (query || []) + [subquery]
 
       self
@@ -197,7 +216,7 @@ module Scrivito
       end
       subquery = {:field => field, :operator => real_operator, :value => convert_value(value),
           :negate => true}
-      @size = nil
+      reset_for_changed_query
       @query = (query || []) + [subquery]
 
       self
@@ -210,39 +229,66 @@ module Scrivito
     # 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+).
+    # @overload order(field_name)
+    #   @param [Symbol, String] field_name This parameter specifies the field by
+    #     which the hits are sorted (e.g. +:_path+).
+    #
+    # @overload order(field_and_direction)
+    #   @param [Hash] field_and_direction The field name and sort direction can be
+    #     specfied as the key and value of a hash. Valid directions are
+    #     +:asc+ and +:desc+. The default is +:asc+.
+    #
+    # @example Sorting descending
+    #   Obj.all.order(_last_changed: :desc)
+    #
     # @return [Scrivito::ObjSearchEnumerator]
     # @api public
     def order(field_name)
+      field_name, direction = if field_name.is_a?(Hash)
+        field_name.to_a.first
+      else
+        [field_name, :asc]
+      end
+
       options[:sort_by] = field_name
+      options[:sort_order] = direction.to_sym
 
       self
     end
 
     # Reverses the order of the results. Requires {#order} to be applied before.
     # @return [Scrivito::ObjSearchEnumerator]
+    # @deprecated This method is deprecated and will be removed in the next major
+    #   version. Please specify the direction using {#order}.
     # @api public
     def reverse_order
+      Scrivito::Deprecation.warn_method("reverse_order", "order")
       options[:sort_by].present? or raise "A search order has to be specified"\
           " before reverse_order can be applied."
-      @reverse_order = !@reverse_order
+      options[:sort_order] = options[:sort_order] == :asc ? :desc : :asc
 
       self
     end
 
+    #
     # Number of search results to be returned by each of the internal search requests.
+    #
+    # @api public
+    #
     # 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.
+    # 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 number of search results to be returned by each of the internal search
+    #   requests. Scrivito tries to honor the requested +size+ as much as possible, but there is no
+    #   guarantee. At the time of writing, +size+ is capped at +100+, for example.
     #
-    # @param [Integer] size A value in the range from +1+ to +100+.
     # @return [Scrivito::ObjSearchEnumerator]
-    # @api public
+    #
     def batch_size(size)
-      options[:size] = size
+      @batch_size = size
+      @preload_search_result = true
 
       self
     end
@@ -253,7 +299,6 @@ module Scrivito
     # @return [Scrivito::ObjSearchEnumerator]
     # @api public
     def offset(amount)
-      options[:offset] ||= 0
       options[:offset] += amount
 
       self
@@ -272,21 +317,15 @@ module Scrivito
     # @return [void]
     # @api public
     def each
-      offset = options[:offset] || 0
-      current_batch, total = fetch_next_batch(offset)
-      loop do
-        if current_batch.size == 0
-          if offset < total
-            current_batch, total = fetch_next_batch(offset)
-          else
-            raise StopIteration
-          end
-        end
+      iterator = BatchIterator.new(workspace, search_dsl_params, @preloaded_batch)
 
-        offset += 1
-        hit = current_batch.shift
-        yield hit
+      iterator.each do |batch|
+        batch.objs.each do |obj|
+          yield obj
+        end
       end
+
+      @size = iterator.total
     end
 
     # The total number of hits.
@@ -321,9 +360,7 @@ module Scrivito
     # methods from +Enumerable+, for example +take+.
     # @api public
     def load_batch
-      next_batch = fetch_next_batch(options[:offset] || 0)
-
-      next_batch.first
+      fetch_batch.objs
     end
 
     # @api public
@@ -332,25 +369,38 @@ 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.
+    # @api public
+    # Perform a faceted search over up to ten attributes to retrieve structured results for individual values of these attributes.
     #
-    # Applicable to attribute types +string+, +stringlist+, +enum+, +multienum+.
+    # Applicable to attributes of the following 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.
+    # Please note that by default {Scrivito::ObjSearchEnumerator#facet} does not preload the first batch of the search results.
+    # In order to reduce the number of search requests, +batch_size+ can be explicitly set using the {Scrivito::ObjSearchEnumerator#batch_size} method.
+    # This causes Scrivito to preload the first batch of the search results.
     #
-    # @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.
+    # @overload facet(attribute, options={})
+    #    Single-attribute faceting request.
+    #    @param [String] attribute 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>]
+    #      in the ++facets++ parameter.
+    #      The values of the hash are lists of {Scrivito::ObjFacetValue}.
+    # @overload facet(facets)
+    #    Multi-attribute faceting request. The maximum number of attributes that may be specified is 10.
+    #    @param [Hash] facets a hash where the keys are attribute names and the values are options.
+    #      The available options are identical to the options for single faceting requests.
+    #    @return [Hash] a hash where the keys are identical to the keys given.
+    #      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.
+    #    @raise [Scrivito::ClientError] If the number of attributes exceeds 10.
     #
-    # @example Faceted request: colors of _big_ balloons.
+    # @example Faceted request: colors of _big_ balloons:
     #   facets = Balloon.where(:size, :equals, "big").facet("color")
     #
     #   # Big balloons come in 3 colors:
@@ -371,14 +421,14 @@ module Scrivito
     #   blue_balloons.name #=> "blue"
     #   blue_balloons.count #=> 1
     #
-    # @example Faceted request with limit: at most 2 colors of big balloons.
+    # @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.
+    # @example Faceted request with included Objs:
     #   facets = Balloon.where(:size, :equals, "big").facet("color", include_objs: 2)
     #
     #   facets.each do |facet|
@@ -387,7 +437,7 @@ module Scrivito
     #     end
     #   end
     #
-    #   # If there are 3 big red balloons, 2 big green balloons and 1 big blue balloon,
+    #   # If there are 2 big red balloons, 2 big green balloons and 1 big blue balloon,
     #   # then this will produce:
     #
     #   "big red Balloon"
@@ -396,19 +446,90 @@ module Scrivito
     #   "big green Balloon"
     #   "big blue Balloon"
     #
+    # @example Multiple faceting request:
+    #   facets = Balloon.where(:size, :equals, "big").facet(
+    #     color: {limit: 3, include_objs: 5},
+    #     motif: {limit: 3, include_objs: 5}
+    #   )
+    #
+    #   color_facet_obj_values = facets[:color]
+    #   motif_facet_obj_values = facets[:motif]
+    #
+    #   color_facet_obj_values.each do |facet|
+    #     facet.included_objs.each do |obj|
+    #       puts "#{obj.size} #{obj.color} #{obj.class}"
+    #     end
+    #   end
+    #
+    #   motif_facet_obj_values.each do |facet|
+    #     facet.included_objs.each do |obj|
+    #       puts "#{obj.size} #{obj.motif} #{obj.class}"
+    #     end
+    #   end
+    #
+    #   # If there are 2 big red balloons, 2 big green balloons and 1 big blue balloon,
+    #   # this will produce:
+    #
+    #   "big red Balloon"
+    #   "big red Balloon"
+    #   "big green Balloon"
+    #   "big green Balloon"
+    #   "big blue Balloon"
+    #
+    #   # If there are 1 big birthday balloon and 1 big wedding balloon,
+    #   # this will produce:
+    #
+    #   "big birthday Balloon"
+    #   "big wedding Balloon"
+    #
+    # @example Faceted +where+ query with +batch_size+:
+    #   big_balloons = Balloon.where(:size, :equals, "big")
+    #
+    #   # Without preloading
+    #   balloon_colors = big_balloons.facet("color")
+    #   first_ten_balloons = big_balloons.take(10) # This will cause a search request.
+    #
+    #   # With preloading
+    #   big_balloons.batch_size(10) # Make Scrivito preload the first ten balloons.
+    #   balloon_colors = big_balloons.facet("color")
+    #   first_ten_balloons = big_balloons.take(10) # This will cause _no_ search request.
+    #
     # @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.
+    #   The 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]
+    def facet(*args)
+      if args.length == 1 && args[0].is_a?(Hash)
+        return {} if args[0].empty?
+        facets_params = multiple_facet_params(args)
+        get_facet_value_objs(facets_params, args[0].keys)
+      else
+        facets_params = [single_facet_params(*args)]
+        attribute_name = args[0]
+        result = get_facet_value_objs(facets_params, [attribute_name])
+        result[attribute_name]
+      end
+    end
+
+    def fetch_batch(continuation=nil)
+      batch =
+        if @preloaded_batch && !continuation
+          @preloaded_batch
+        else
+          QueryExecutor.new(workspace).call(search_dsl_params, continuation)
+        end
+
+      @size = batch.total
+      batch
     end
 
     private
 
     attr_reader :options
 
+    def reset_for_changed_query
+      @size, @preloaded_batch = nil
+    end
+
     def convert_value(value)
       if value.kind_of?(Array)
         value.map{ |v| convert_single_value(v) }
@@ -449,6 +570,18 @@ module Scrivito
       result
     end
 
+    def multiple_facet_params(facets)
+      facet_params = []
+      facets.first.map do |k, v|
+        facet_params << single_facet_params(k, v)
+      end
+      facet_params
+    end
+
+    def single_facet_params(attribute, options = {})
+      { attribute: attribute }.merge!(options)
+    end
+
     def get_objs_facet_ids(facet)
       result = []
       if included_ids = facet["results"]
@@ -460,27 +593,33 @@ module Scrivito
     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 = prepare_facet_search_params facets_params
 
-      params.reverse_merge!(size: 0)
+      batch = QueryExecutor.new(workspace).call(params)
+      @preloaded_batch = batch if @preload_search_result
 
-      request_result = CmsBackend.instance.search_objs(workspace, params)
-      request_result['facets'].each do |facets_array|
+      batch.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|
+      obj_collection = workspace.objs.find(included_objs_ids)
+      batch.facets.each_with_index do |facets_array, index|
         result[result.keys[index]] += create_facet_value_objs(facets_array, obj_collection)
       end
       result
     end
 
+    def prepare_facet_search_params(facet_params)
+      params = { facets: facet_params }
+
+      if query
+        params.merge! search_dsl_params
+      end
+
+      params.reverse_merge(size: 0)
+    end
+
     def operator_mapping(operator)
       case operator.to_sym
       when :contains
@@ -496,29 +635,15 @@ module Scrivito
       when :is_less_than
         :less_than
       else
-        raise "Operator '#{operator}'' is not valid!"
+        raise "Operator '#{operator}' is not valid!"
       end
     end
 
-    def fetch_next_batch(offset)
-      request_result = CmsBackend.instance.search_objs(workspace, search_dsl(offset))
-
-      obj_ids = request_result['results'].map { |result| result['id'] || result['_id'] }
-      objs = workspace.objs.find_including_deleted(obj_ids)
-
-      @size = request_result['total'].to_i
-
-      [objs, @size]
-    end
-
-    def search_dsl(offset)
+    def search_dsl_params
       patches = {
-        offset: offset,
         query: query,
       }
-      if @reverse_order
-        patches[:sort_order] = options[:sort_by].present? ? :desc : :asc
-      end
+      patches[:size] = @batch_size if @batch_size
 
       if @include_deleted
         patches[:options] = {

data/lib/scrivito/obj_update_params_parser.rb

@@ -18,6 +18,7 @@ module Scrivito
       params['_widget_pool'].each_pair do |widget_id, widget_params|
         if widget_params.present?
           widget = obj.widgets[widget_id]
+          raise_widget_not_found_error(widget_id) unless widget
           widget_pool[widget] = convert_field_params(widget_params, widget.attribute_definitions)
         end
       end

data/lib/scrivito/preset_routes.rb

@@ -0,0 +1,25 @@
+module Scrivito
+  module PresetRoutes
+    def self.install_into(route_set)
+      return if Scrivito::Configuration.scrivito_route_enabled?
+
+      Scrivito::Configuration.with_scrivito_route_enabled do
+        route_set.draw do
+          scrivito_route '/', using: "homepage", via: :all
+
+          if Scrivito::Configuration.legacy_routing
+            scrivito_route ':id(/*slug)', using: "slug_id", via: :all
+          else
+            scrivito_route '(/)(*slug-):id', using: "slug_id", via: :all
+
+            match ':id(/*slug)', to: 'scrivito/legacy_redirect#index', via: :all, constraints: {
+              id: /[a-z0-9]{16}/
+            }
+          end
+
+          scrivito_route '/*permalink', using: "permalink", format: false, via: :all
+        end
+      end
+    end
+  end
+end

data/lib/scrivito/revision.rb

@@ -5,10 +5,6 @@ class Revision < Struct.new(:id, :workspace, :base)
     super(*options.values_at(:id, :workspace, :base))
   end
 
-  def content_state
-    base ? workspace.base_content_state : workspace.content_state
-  end
-
   def content_state_id
     base ? workspace.base_content_state_id : workspace.content_state_id
   end
@@ -41,18 +37,24 @@ class Revision < Struct.new(:id, :workspace, :base)
 
   private
 
-  def internal_obj_search(query, result)
-    response = workspace.api_request(:get, "/objs/search", {
-      query: query, include_deleted: true, size: 100, offset: result.size
-    })
+  def internal_obj_search(query, result, continuation=nil, tentative=false)
+    response = workspace.api_request(:get, "/objs/search",
+      query: query,
+      include_deleted: true,
+      size: 100,
+      continuation: continuation,
+      consistent_with: content_state_id
+    )
 
     cur_result = response['results'].map { |obj_data| obj_data['id'] }
     result += cur_result
+    continuation = response['continuation']
+    tentative ||= !!response['tentative']
 
-    if result.size >= response['total'].to_i
-      result
+    if continuation
+      internal_obj_search(query, result, continuation, tentative)
     else
-      internal_obj_search(query, result)
+      [result.uniq, tentative]
     end
   end
 

data/lib/scrivito/route.rb

@@ -0,0 +1,62 @@
+module Scrivito
+
+class Route
+
+  class << self
+    VALID_ROUTE_NAMES = %i(homepage slug_id permalink).freeze
+
+    def register(route_set, name)
+      assert_valid_route_name(name)
+      registry(route_set)[name] = new(name)
+    end
+
+    def defined?(route_set, name)
+      !!registry(route_set)[name]
+    end
+
+    def find(route_set, name)
+      registry(route_set)[name] or raise InternalError, "route #{name} not found"
+    end
+
+    private
+
+    def registry(route_set)
+      @registry ||= {}
+      @registry[route_set] ||= {}
+    end
+
+    def assert_valid_route_name(name)
+      unless VALID_ROUTE_NAMES.include?(name)
+        valid_values = VALID_ROUTE_NAMES.join(', ')
+        raise ScrivitoError,
+            %("#{name}" is not a valid scrivito route name. Valid values are: #{valid_values}.)
+      end
+    end
+  end
+
+  def initialize(name)
+    @name = name
+  end
+
+  def helper_name
+    # use a random name to prevent users from getting the idea
+    # that the internally unsed routing helpers might be a stable API
+    random_segment = Digest::SHA1.hexdigest(@name.to_s)[0..15]
+    @helper_name ||= "scrivito_#{random_segment}"
+  end
+
+  def generate_path(context, options = {})
+    generate(context, :path, options)
+  end
+
+  def generate_url(context, options = {})
+    generate(context, :url, options)
+  end
+
+  def generate(context, path_or_url, options = {})
+    context.public_send("#{helper_name}_#{path_or_url}", options)
+  end
+
+end
+
+end