scrivito_sdk 0.66.0 → 0.70.0.rc1

data/lib/scrivito/obj_collection.rb

@@ -1,5 +1,5 @@
 module Scrivito
-  # This class allows you to retrieve Objects from a specific working copy.
+  # This class allows you to retrieve CMS objects from a specific working copy.
   # You can get an instance by accessing {Workspace#objs}.
   # @api public
   class ObjCollection
@@ -9,8 +9,9 @@ module Scrivito
       @workspace = workspace
     end
 
-    # Find a {BasicObj Obj} by its id.
-    # If the parameter is an Array containing ids, return a list of corresponding Objs.
+    # Find an {BasicObj Obj} by its id.
+    # If the parameter is an Array containing ids, return a list of the
+    # corresponding {Scrivito::BasicObj Obj}s.
     # @param [String, Integer, Array<String, Integer>]id_or_list
     # @return [Obj, Array<Obj>]
     # @api public
@@ -19,8 +20,8 @@ module Scrivito
     end
 
     # Find a {BasicObj Obj} by its id.
-    # If the parameter is an Array containing ids, return a list of corresponding Objs.
-    # The results include deleted objects as well.
+    # If the parameter is an Array containing ids, return a list of the
+    # corresponding {Scrivito::BasicObj Obj}s. The results include deleted objects as well.
     # @param [String, Integer, Array<String, Integer>]id_or_list
     # @return [Obj, Array<Obj>]
     # @api public
@@ -28,8 +29,8 @@ module Scrivito
       find_using(id_or_list, :find_by_including_deleted)
     end
 
-    # Find the {BasicObj Obj} with the given path.
-    # Returns +nil+ if no matching Obj exists.
+    # 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]
     # @api public
@@ -37,7 +38,7 @@ module Scrivito
       find_by(:path, [path]).first.first
     end
 
-    # Returns the {BasicObj Obj} with the given permalink, or +nil+ if no matching Obj exists.
+    # 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]
     # @api public
@@ -45,11 +46,12 @@ module Scrivito
       find_by(:permalink, [permalink]).first.first
     end
 
-    # Returns a {ObjSearchEnumerator} with the given initial subquery consisting of the four arguments.
+    # Returns an {ObjSearchEnumerator} with the given initial subquery consisting of the four arguments.
     #
-    # Note that +field+ and +value+ can also be arrays for searching several fields or searching for several values.
+    # Note that +field+ and +value+ may also be arrays for searching several fields or searching for several values.
     #
-    # {ObjSearchEnumerator}s can be chained using one of the chainable methods (e.g. {ObjSearchEnumerator#and} and {ObjSearchEnumerator#and_not}).
+    # {ObjSearchEnumerator}s can be chained using one of the chainable methods
+    # (e.g. {ObjSearchEnumerator#and} and {ObjSearchEnumerator#and_not}).
     #
     # @param [Symbol, String, Array<Symbol, String>] field See {ObjSearchEnumerator#and} for details
     # @param [Symbol, String] operator See {ObjSearchEnumerator#and} for details
@@ -62,15 +64,15 @@ module Scrivito
         .and(field, operator, value, boost)
     end
 
-    # Returns a {ObjSearchEnumerator} of all {BasicObj Obj}s.
+    # Returns an {ObjSearchEnumerator} of all {BasicObj Obj}s.
     # @return [ObjSearchEnumerator]
     # @api public
     def all
       ObjSearchEnumerator.new(workspace).batch_size(1000)
     end
 
-    # Returns a {ObjSearchEnumerator} of all Objs with the given +obj_class+.
-    # @param [String] obj_class name of the obj class.
+    # Returns an {ObjSearchEnumerator} of all {BasicObj Obj}s with the given +obj_class+.
+    # @param [String] obj_class name of the object class.
     # @return [ObjSearchEnumerator]
     # @api public
     def find_all_by_obj_class(obj_class)
@@ -115,8 +117,8 @@ module Scrivito
       end
     end
 
-    # accepts the name of an "obj_by" - view, a list of keys
-    # returns a list of lists of Objs: a list of Objs for each given keys.
+    # Accepts the name of an "obj_by" view, a list of keys.
+    # Returns a list of lists of Objs: a list of Objs for each given key.
     def find_by_including_deleted(view, keys)
       result = CmsBackend.instance.find_obj_data_by(
         workspace.revision,

data/lib/scrivito/obj_params_parser.rb

@@ -51,7 +51,7 @@ module Scrivito
     end
 
     def parse_date_params(params)
-      DateAttribute.parse(params)
+      DateAttribute.parse_iso8601(params)
     end
   end
 end

data/lib/scrivito/obj_search_enumerator.rb

@@ -1,38 +1,38 @@
 # encoding: UTF-8
 module Scrivito
-  # Provides an enumerator for iterating over obj search results and retrieving obj instances.
-  # This is done using the {http://ruby-doc.org/core-2.1.3/Enumerable.html <code>Enumerable</code> mixin},
+  # 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 <code>Enumerable</code> mixin},
   # which provides methods such as <code>map</code>, <code>select</code> or <code>take</code>.
   #
-  # This enumerator is lazy. If for example you are looking for {BasicObj Obj}s with the obj class "Publication",
-  # and there are 93 objs in total, than <code>enum.take(10)</code> will fetch the first 10 objs only,
-  # ignoring the other 83 objs.
-  # This also means, that iterating multiple times over this enumerator causes the search results and objs to be fetched again.
-  # If you want to get all objs at once, use <code>enum.to_a</code>.
+  # This enumerator is lazy. If, for example, you are looking for {BasicObj Obj}s whose object class is "Publication",
+  # and there are 93 objects in total, then <code>enum.take(10)</code> fetches the first 10 objects only,
+  # ignoring the other 83.
+  # This implies that repeatedly iterating over this enumerator causes the search results and the objects to be fetched again and again.
+  # If you want to get all objects at once, use <code>enum.to_a</code>.
   #
-  # To start searching use one of the {BasicObj Obj} methods that returns an {ObjSearchEnumerator}. The preferred way is to start with {BasicObj.where Obj.where}.
+  # To start searching, use one of the {BasicObj Obj} methods that return an {ObjSearchEnumerator}. The preferred way is to start with {BasicObj.where Obj.where}.
   #
   # == Currently available fields and their values
   #
   # [+:*+]              Searches all fields.
-  #                     This is only possible with the operators +contais+ or +starts_with+.
+  #                     This is only possible with the +contains+ and +starts_with+ operators.
   # [+:id+]             Id of an {BasicObj Obj}. This is a +string+ field.
   # [+:_path+]          Path of an {BasicObj Obj}. This is a +string+ field.
   # [+:_name+]          Name of an {BasicObj Obj}. This is a +string+ field.
   # [+:title+]          Title of an {BasicObj Obj}. This is a +string+ field.
   # [+:body+]           Body of an {BasicObj Obj}. This is an +html+ field. Thus, only the +contains+ and
   #                     +contains_prefix+ operators can be applied to this field.
-  # [+:_obj_class+]     obj class of an {BasicObj Obj}. This is a +string+ field.
+  # [+:_obj_class+]     Object class of an {BasicObj Obj}. This is a +string+ field.
   # [+:_permalink+]     Permalink of an {BasicObj Obj}. This is a +string+ field.
   # [+:_last_changed+]  Date of last change of an {BasicObj Obj}.
   # [every <em><code>:custom_attribute</code></em>] Custom attribute of an {BasicObj Obj}. Note that
   #                                                 depending on the attribute type (e.g. an
-  #                                                 +html+ field), some operators can not be applied.
+  #                                                 +html+ field), some operators cannot be applied.
   #
   # All values are stored as strings.
   #
   # Date values are stored in the format YYYYMMDDHHMMSS in UTC. For example, 2000-01-01 00:00:00 UTC is stored as "<code>20000101000000</code>".
-  # This is relevant for string comparisons using the +is_less_than+ and +is_greater_than+ operators.
+  # This is relevant for string comparisons in which the +is_less_than+ and +is_greater_than+ operators are used.
   #
   # == Currently available operators
   #
@@ -48,7 +48,7 @@ module Scrivito
   #                       ✘ "behi clo" (not whole words)
   #
   #                       ✘ "behind everything" (second word does not match)
-  # [+:contains_prefix+]  Searches for one prefix. A whole word is also a prefix.
+  # [+:contains_prefix+]  Searches for one prefix. A whole word also counts as a prefix.
   #
   #                       Example subquery values:
   #
@@ -118,16 +118,16 @@ module Scrivito
 
     # @group Chainable methods
 
-    # Adds this additional AND subquery to this {ObjSearchEnumerator}.
+    # Adds the given AND subquery to this {ObjSearchEnumerator}.
     #
     # Compares the +field(s)+ with the +value(s)+ using the +operator+ of this subquery.
-    # All objs to which this criterion applies remain in the result set.
+    # All CMS objects to which this criterion applies remain in the result set.
     #
     # @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" at the top.
-    # @param [String, Array<String>] value The value(s) with which the field value(s) are compared using the +operator+ of this subquery.
-    #   For arrays, the subquery matches, if the condition is met for one or more of the array elements.
+    #   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 +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 factors.
     #   Boosting factors must be in the range from 1 to 10.
     #   Boosting can only be applied to subqueries in which the +contains+ or +contains_prefix+ operator is used.
@@ -151,18 +151,18 @@ module Scrivito
       self
     end
 
-    # Adds this additional negated AND subquery to this {ObjSearchEnumerator}.
+    # Adds the given negated AND subquery to this {ObjSearchEnumerator}.
     #
     # Compares the +field(s)+ with the +value(s)+ using the negated +operator+ of this subquery.
-    # All objs to which this criterion applies are removed from the result set.
+    # All CMS objects to which this criterion applies are removed from the result set.
     #
     # @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.
+    #   For arrays, the subquery matches if one or more of these fields meet this criterion.
     # @param [Symbol, String] operator Only applicable to subqueries in which the +equals+,
-    #   +starts_with+, +is_greater_than+ and +is_less_than+ operator is used
-    #   (See "Currently available operators" at the top).
-    # @param [String, Array<String>] value The value(s) with which the field value(s) are compared using the +operator+ of this subquery.
-    #   For arrays, the subquery matches, if the condition is met for one or more of the array elements.
+    #   +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 +operator+ of this subquery.
+    #   For arrays, the subquery matches if the condition is met for one or more of the array elements.
     # @return [ObjSearchEnumerator]
     # @api public
     def and_not(field, operator, value)
@@ -180,7 +180,7 @@ module Scrivito
     end
 
     # Orders the results by +field_name+.
-    # @param [Symbol, String] field_name This parameter determines by which field the hits are sorted (e.g. +:_path+).
+    # @param [Symbol, String] field_name This parameter specifies the field by which the hits are sorted (e.g. +:_path+).
     # @return [ObjSearchEnumerator]
     # @api public
     def order(field_name)
@@ -189,7 +189,7 @@ module Scrivito
       self
     end
 
-    # Reverses the order of the results. Requires {#order} to be specified before.
+    # Reverses the order of the results. Requires {#order} to be applied before.
     # @return [ObjSearchEnumerator]
     # @api public
     def reverse_order
@@ -201,7 +201,7 @@ module Scrivito
     end
 
     # Number of search results to be returned by each of the internal search requests.
-    # The default is +10+. The server may limit a large batch size to a reasonable value.
+    # The default is +10+. The server may reduce large batches to a reasonable size.
     # @param [Integer] size A value in the range from +1+ to +100+.
     # @return [ObjSearchEnumerator]
     # @api public
@@ -212,7 +212,7 @@ module Scrivito
     end
 
 
-    # Omits the first +amount+ number of {BasicObj Obj}s from the results. The default is +0+.
+    # Omits the first +amount+ of {BasicObj Obj}s from the results. The default is +0+.
     # @param [Integer] amount
     # @return [ObjSearchEnumerator]
     # @api public
@@ -272,10 +272,10 @@ module Scrivito
       @size ||= CmsBackend.instance.search_objs(workspace, size_query)['total'].to_i
     end
 
-    # load a single batch of search results from the backend.
-    # returns an array of Objs.
-    # will usually return `batch_size` results if available,
-    # but may occasionally return fewer than `batch_size` results (due to rate limit, for example).
+    # Loads a single batch of search results from the backend.
+    # @return [Array] of {BasicObj Obj}.
+    # Usually returns +batch_size+ results if available,
+    # but may occasionally return fewer than +batch_size+ results (due to rate limit, for example).
     # @api public
     def load_batch
       next_batch = fetch_next_batch(options[:offset] || 0)
@@ -305,7 +305,7 @@ module Scrivito
       if value.is_a?(Time) || value.is_a?(Date)
         DateAttribute.serialize(value)
       else
-        value
+        value.to_s
       end
     end
 

data/lib/scrivito/page_config.rb

@@ -0,0 +1,55 @@
+module Scrivito
+
+class PageConfig < Struct.new(:obj, :editing_context, :lookup_context)
+
+  def initialize(**named_params)
+    named_params.each { |key, value| self[key] = value }
+  end
+
+  def to_json
+    {
+      current_page: current_page_config,
+      user_id: user_id_config,
+    }.to_json
+  end
+
+  private
+
+  def user_id_config
+    editor.id
+  end
+
+  def current_page_config
+    return {} unless obj
+    {
+      id: obj.id,
+      obj_class_name: obj.obj_class_name,
+      has_children: obj.children.any?,
+      has_conflict: obj.has_conflict?,
+      has_details_view: obj_has_details_view?,
+      modification: modification(obj),
+      restriction_messages: editor.restriction_messages_for(obj),
+    }
+  end
+
+  def obj_has_details_view?
+    lookup_context.find(obj.details_view_path).present?
+  rescue ActionView::MissingTemplate
+    false
+  end
+
+  def modification(obj_or_resource)
+    comparison = editing_context.comparison
+    if comparison.active?
+      comparison.modification(obj_or_resource)
+    else
+      obj_or_resource.modification
+    end
+  end
+
+  def editor
+    editing_context.editor
+  end
+end
+
+end

data/lib/scrivito/request_homepage.rb

@@ -0,0 +1,23 @@
+module Scrivito
+  module RequestHomepage
+    HOMEPAGE_ENV_KEY = "SCRIVITO_HOMEPAGE"
+
+    class << self
+      def call(env)
+        env[HOMEPAGE_ENV_KEY] ||= fetch_homepage(env)
+      end
+
+      private
+
+      def fetch_homepage(env)
+        callback_result = Scrivito::Configuration.choose_homepage_callback.call(env)
+        if callback_result.is_a?(Obj)
+          callback_result
+        else
+          raise "choose_homepage callback did not return an Obj. "\
+            "Instead saw #{callback_result.class}."
+        end
+      end
+    end
+  end
+end

data/lib/scrivito/routing_helper.rb

@@ -1,21 +1,21 @@
 module Scrivito
   #
-  # The helper contains methods to generate URLs to CMS content.
+  # This helper contains methods for generating URLs that point to CMS content.
   # Use {Scrivito::RoutingHelper#scrivito_path} or {Scrivito::RoutingHelper#scrivito_url} when linking or
-  # redirecting to CMS objects. These methods are available in boths your views and your controllers.
+  # redirecting to CMS objects. These methods are available in both your views and your controllers.
   #
   # @api public
   #
   module RoutingHelper
     #
-    # Returns the (URL-)path for a cms object.
+    # Returns the (URL-)path of a CMS object.
     #
     # @api public
     #
     # @param target [Obj, Link, Array<Link>, Binary]
     #   If +target+ is an +Array+ of +Links+, it must be non-empty.
-    #   The first {Link} from the +Array+ will be used.
-    # @param options [Hash] include url settings such as path parameters or protocol.
+    #   Only the first {Link} of the +Array+ is used.
+    # @param options [Hash] include url settings such as path parameters or the protocol.
     #
     # @return [String]
     #
@@ -24,14 +24,14 @@ module Scrivito
     end
 
     #
-    # Returns the absolute URL for a cms object.
+    # Returns the absolute URL of a CMS object.
     #
     # @api public
     #
     # @param target [Obj, Link, Array<Link>, Binary]
     #   If +target+ is an +Array+ of +Links+, it must be non-empty.
-    #   The first {Link} from the +Array+ will be used.
-    # @param options [Hash] include url settings such as path parameters or protocol.
+    #   Only the first {Link} of the +Array+ is used.
+    # @param options [Hash] include url settings such as path parameters or the protocol.
     #
     # @return [String]
     #

data/lib/scrivito/sdk_engine.rb

@@ -1,7 +1,6 @@
 require 'rails'
 
 require 'jbuilder'
-require 'jquery-rails'
 require 'net/http/post/multipart'
 
 module ::Scrivito
@@ -43,8 +42,8 @@ module ::Scrivito
     initializer 'scrivito.add_sdk_assets' do |app|
       # Specify which file should be precompiled for packaging
       app.config.assets.precompile += %w[
-        scrivito_sdk.css
-        scrivito_sdk.js
+        scrivito.css
+        scrivito.js
         scrivito_ui.css
         scrivito_ui.js
       ]

data/lib/scrivito/ui_config.rb

@@ -0,0 +1,85 @@
+module Scrivito
+
+class UiConfig < Struct.new(:editing_context, :resource, :return_to, :app_extension_tags)
+  def initialize(**named_params)
+    named_params.each { |key, value| self[key] = value }
+  end
+
+  def to_json
+    {
+      editing_context:     editing_context_config,
+      i18n:                i18n_config,
+      is_development_mode: Rails.env.development?,
+      resource_dialog:     resource_dialog_config,
+      user:                user_config,
+      user_permissions:    user_permissions_config,
+      app_extension_tags:  app_extension_tags,
+    }.to_json
+  end
+
+  private
+
+  def editing_context_config
+    {
+      display_mode:       editing_context.display_mode,
+      selected_workspace: workspace_config(selected_workspace),
+      visible_workspace:  workspace_config(visible_workspace),
+    }
+  end
+
+  def workspace_config(workspace)
+    {
+      id: workspace.id,
+      memberships: workspace.memberships.map do |membership|
+        {
+          user_id: membership.user_id,
+          role: membership.role,
+          description: membership.user.description
+        }
+      end,
+      outdated: workspace.outdated?,
+      title: workspace.title,
+    }
+  end
+
+  def i18n_config
+    {locale: Scrivito::Configuration.ui_locale || I18n.locale}
+  end
+
+  def resource_dialog_config
+    return {} unless resource
+    {
+      obj: Configuration.obj_formats.fetch('_default').call(resource, editor),
+      return_to: return_to,
+    }
+  end
+
+  def user_permissions_config
+    {
+      create_workspace: editor.can?(:create, :workspace),
+      publish_workspace: editor.can?(:publish, selected_workspace),
+    }
+  end
+
+  def user_config
+    {
+      current: {
+        id: editor.id
+      }
+    }
+  end
+
+  def editor
+    editing_context.editor
+  end
+
+  def selected_workspace
+    editing_context.selected_workspace
+  end
+
+  def visible_workspace
+    editing_context.visible_workspace
+  end
+end
+
+end

data/lib/scrivito/user.rb

@@ -22,9 +22,9 @@ module Scrivito
       #
       # @api public
       #
-      # @param [String] id the unique, unalterable id of the user.
+      # @param [String] id The unique, unalterable id of the user.
       #   The user id is used to associate the user with the corresponding CMS resources.
-      #   It will be persisted in the CMS.
+      #   It is persisted in the CMS.
       #
       # @raise [Scrivito::ScrivitoError] if id is blank
       # @raise [Scrivito::ScrivitoError] if id is more than 64 characters long
@@ -38,21 +38,21 @@ module Scrivito
       # @see Scrivito::UserDefinition#suggest_users
       #
       # @example
-      #   Scrivito::User.define('alice') do |user|
-      #     user.description { 'Alice Almighty' }
+      #   Scrivito::User.define('alice') do |user_definition|
+      #     user_definition.description { 'Alice Almighty' }
       #
-      #     user.can_always(:read, :workspace)
-      #     user.can_always(:write, :workspace)
-      #     user.can_always(:publish, :workspace, 'You can always publish workspaces.')
+      #     user_definition.can_always(:read, :workspace)
+      #     user_definition.can_always(:write, :workspace)
+      #     user_definition.can_always(:publish, :workspace, 'You can always publish workspaces.')
       #   end
       #
-      #   Scrivito::User.define('bob') do |user|
-      #     user.description('Bob Doe')
+      #   Scrivito::User.define('bob') do |user_definition|
+      #     user_definition.description('Bob Doe')
       #
-      #     user.can_never(:create, :workspace, 'You are not allowed to create workspaces.')
-      #     user.can_always(:read, :workspace)
+      #     user_definition.can_never(:create, :workspace, 'You are not allowed to create workspaces.')
+      #     user_definition.can_always(:read, :workspace)
       #
-      #     user.restrict_obj_publish(using: :_obj_class_name) do |obj_class_name|
+      #     user_definition.restrict_obj_publish(using: :_obj_class_name) do |obj_class_name|
       #       if obj_class_name == 'BlogPost'
       #         false
       #       else
@@ -67,8 +67,15 @@ module Scrivito
       end
 
       #
-      # Returns an anonymous system user, who can always create workspaces, can always read, write,
-      # publish, delete and invite to any workspace.
+      # Returns an anonymous system user who can always create workspaces, can always read, write,
+      # publish, delete, and invite others to collaborate on any workspace.
+      # @example Check whether the user may publish a particular object:
+      #   Scrivito::User.system_user.can_publish?(Obj.root)
+      #   # => true
+      #
+      # @example Get the notification messages for publishing restrictions. An empty array indicates that no restrictions exist.
+      #   Scrivito::User.system_user.restriction_messages_for(Obj.root)
+      #   # => []
       #
       # @api public
       # @return [Scrivito::User] the system user
@@ -145,24 +152,24 @@ module Scrivito
     end
 
     #
-    # Verifies if the User is able to publish changes to a certain {BasicObj Obj}
+    # Checks whether the User may publish changes to a specific {Scrivito::BasicObj Obj}.
     #
     # @api public
-    # @param [BasicObj] obj the obj that should be published
-    # @return [Boolean] true if the user is allowed to publish otherwise false
+    # @param [BasicObj] obj the object to be published
+    # @return [Boolean] true if the user is allowed to publish the object, otherwise false
     #
     def can_publish?(obj)
       restriction_messages_for(obj).empty?
     end
 
     #
-    # Checks if the User is able to publish changes and returns the message
-    # specified in a {UserDefinition#restrict_obj_publish} callback if they are not
-    # If the user can publish the obj an empty array is returned
+    # Checks whether the User may publish changes to an {Scrivito::BasicObj Obj} and returns
+    # the message specified in a {UserDefinition#restrict_obj_publish} callback if they may not.
+    # If the user may publish the CMS object, an empty array is returned.
     #
     # @api public
-    # @param [BasicObj] obj the obj that should be published
-    # @return [Array<String>] Hints why the user can't publish
+    # @param [BasicObj] obj the object to be published
+    # @return [Array<String>] Hints on why the user cannot publish the object
     #
     def restriction_messages_for(obj)
       assert_restrictions_applicable(obj)
@@ -193,7 +200,7 @@ module Scrivito
       end
     end
 
-    # Per convention only anonymous admin has a nil id.
+    # By convention, only the anonymous admin user has a +nil+ id.
     def system_user?
       id.nil?
     end