scrivito_sdk 0.16.0 → 0.17.0

data/lib/scrivito/obj_data.rb

@@ -23,6 +23,20 @@ module Scrivito
 
     SPECIAL_KEYS = Set.new(%w[ body title blob ])
 
+    ATTRIBUTE_DEFAULT_VALUES = {
+      "string"        => "",
+      "text"          => "",
+      "html"          => "",
+      "multienum"     => [],
+      "linklist"      => [],
+      "referencelist" => [],
+      "widget"        => [],
+      "enum"          => nil,
+      "binary"        => nil,
+      "date"          => nil,
+      "reference"     => nil,
+      "link"          => nil,
+    }.freeze
 
     def value_of(attribute_name)
       value_and_type_of(attribute_name).first
@@ -105,7 +119,12 @@ module Scrivito
           [ObjData::MissingAttribute.new, nil]
         end
       else
-        value_and_type
+        value, type = value_and_type
+        if value.nil? && has_custom_attribute?(attribute_name)
+          value = ATTRIBUTE_DEFAULT_VALUES[type]
+        end
+
+        [value, type]
       end
     end
 

data/lib/scrivito/obj_params_parser.rb

@@ -50,6 +50,8 @@ module Scrivito
           ContentConversion.convert_html_links(value, @host, @port)
         when 'linklist'
           ContentConversion.convert_linklist_urls(value, @host, @port)
+        when 'link'
+          ContentConversion.convert_link(value, @host, @port)
         when 'widget'
           widget_field_params.convert(value)
         else

data/lib/scrivito/obj_search_builder.rb

@@ -22,7 +22,7 @@ class ObjSearchBuilder < Struct.new(:query)
   end
 
   def enumerator
-    @enumerator ||= ObjSearchEnumerator.new
+    @enumerator ||= ObjSearchEnumerator.new(Workspace.current)
   end
 
   def set_predicates

data/lib/scrivito/obj_search_enumerator.rb

@@ -110,8 +110,11 @@ module Scrivito
 
     include Enumerable
 
+    attr_reader :workspace
+
     attr_reader :query
-    def initialize
+    def initialize(workspace)
+      @workspace = workspace
       @options = {}
     end
 
@@ -284,11 +287,13 @@ module Scrivito
     end
 
     def format(name)
-      if @formatter = Configuration.obj_formats[name]
-        self
-      else
+      @formatter = Configuration.obj_formats[name]
+
+      unless @formatter
         raise UnregisteredObjFormat, "The format with name '#{name}' is not registered."
       end
+
+      self
     end
 
     # @api public
@@ -340,7 +345,7 @@ module Scrivito
       request_result = CmsRestApi.get(resource_path, search_dsl(offset))
 
       obj_ids = request_result['results'].map { |result| result['id'] || result['_id'] }
-      objs = Obj.find_including_deleted(obj_ids)
+      objs = workspace.objs.find_including_deleted(obj_ids)
 
       @size = request_result['total'].to_i
 
@@ -348,7 +353,7 @@ module Scrivito
     end
 
     def resource_path
-      "workspaces/#{Workspace.current.id}/objs/search"
+      "workspaces/#{workspace.id}/objs/search"
     end
 
     def search_dsl(offset)

data/lib/scrivito/objs_collection.rb

@@ -0,0 +1,130 @@
+module Scrivito
+  # This class allows you to retrieve Objects from a specific working copy.
+  # You can get an instance by accessing {Workspace#objs}.
+  # @api public
+  class ObjsCollection
+    attr_reader :workspace
+
+    def initialize(workspace)
+      @workspace = workspace
+    end
+
+    # Find a {BasicObj Obj} by its id.
+    # If the parameter is an Array containing ids, return a list of corresponding Objs.
+    # @param [String, Integer, Array<String, Integer>]id_or_list
+    # @return [Obj, Array<Obj>]
+    # @api public
+    def find(id_or_list)
+      find_filtering_deleted(id_or_list, false)
+    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.
+    # @param [String, Integer, Array<String, Integer>]id_or_list
+    # @return [Obj, Array<Obj>]
+    # @api public
+    def find_including_deleted(id_or_list)
+      find_filtering_deleted(id_or_list, true)
+    end
+
+    # Find the {BasicObj Obj} with the given path.
+    # Returns +nil+ if no matching Obj exists.
+    # @param [String] path Path of the {BasicObj Obj}.
+    # @return [Obj]
+    # @api public
+    def find_by_path(path)
+      find_by(:path, [path]).first.first
+    end
+
+    # Returns the {BasicObj Obj} with the given permalink, or +nil+ if no matching Obj exists.
+    # @param [String] permalink The permalink of the {BasicObj Obj}.
+    # @return [Obj]
+    # @api public
+    def find_by_permalink(permalink)
+      find_by(:permalink, [permalink]).first.first
+    end
+
+    # Returns a {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.
+    #
+    # {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
+    # @param [String, Array<String>] value See {ObjSearchEnumerator#and} for details
+    # @param [Hash] boost See {ObjSearchEnumerator#and} for details
+    # @return [ObjSearchEnumerator]
+    # @api public
+    def where(field, operator, value, boost = nil)
+      ObjSearchEnumerator.new(workspace)
+        .and(field, operator, value, boost)
+    end
+
+    # Returns a {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 ObjClass.
+    # @return [ObjSearchEnumerator]
+    # @api public
+    def find_all_by_obj_class(obj_class)
+      all.and(:_obj_class, :equals, obj_class)
+    end
+
+    def find_by_parent_path(path)
+      find_by(:ppath, [path]).first
+    end
+
+    def find_by_id(id)
+      find_by(:id, [id]).first.first
+    end
+
+    def find_by_paths(paths)
+      find_by(:path, paths).map(&:first)
+    end
+
+    private
+
+    def find_filtering_deleted(id_or_list, include_deleted)
+      case id_or_list
+      when Array
+        find_by(:id, id_or_list, include_deleted).map(&:first).compact
+      else
+        obj = find_by(:id, [id_or_list.to_s], include_deleted).first.first
+        obj or raise ResourceNotFound, "Could not find Obj with id #{id_or_list}"
+      end
+    end
+
+    # accepts the name of an "obj_by" - view, a list of keys
+    # and an "include_deleted" flag
+    # returns a list of lists of Objs: a list of Objs for each given keys.
+    def find_by(view, keys, include_deleted = false)
+      if include_deleted
+        finder_method_name = :find_obj_data_including_deleted_by
+      else
+        finder_method_name = :find_obj_data_by
+      end
+
+      result = CmsBackend.instance.public_send(
+        finder_method_name,
+        workspace.revision,
+        view,
+        keys)
+
+      result.map do |list|
+        list.map do |obj_data|
+          obj = BasicObj.instantiate(obj_data)
+          obj.revision = workspace.revision
+
+          obj
+        end
+      end
+    end
+  end
+end

data/lib/scrivito/restriction_set.rb

@@ -0,0 +1,54 @@
+module Scrivito
+  class RestrictionSet
+    Restriction = Struct.new(:attribute, :callable) do
+      def call(obj)
+        if skip?(obj)
+          false
+        else
+          value = obj[attribute]
+
+          callable.call(value)
+        end
+      end
+
+      private
+
+      def skip?(obj)
+        !obj.has_attribute?(attribute) || obj.type_of_attribute(attribute) == 'widget'
+      end
+    end
+
+    def add(options, &block)
+      options = options.with_indifferent_access
+      attribute = options.fetch(:uses) do
+        raise ScrivitoError, 'No "uses" option given when adding a publish restriction'
+      end
+
+      unless block_given?
+        raise ScrivitoError, 'No block provided when adding a publish restriction'
+      end
+
+      restrictions << Restriction.new(attribute, block)
+    end
+
+    def restriction_messages_for(obj)
+      restriction_messages = restrictions.inject([]) do |messages, restriction|
+        message = restriction.call(obj)
+
+        if message
+          messages << message.to_s
+        end
+
+        messages
+      end
+
+      restriction_messages.uniq
+    end
+
+    private
+
+    def restrictions
+      @restrictions ||= []
+    end
+  end
+end

data/lib/scrivito/user.rb

@@ -0,0 +1,114 @@
+module Scrivito
+  # @api beta
+  class User < Struct.new(:id, :abilities, :description_proc, :suggest_users_proc, :restriction_set)
+    class << self
+      # Defines a new user.
+      # @api beta
+      # @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.
+      # @raise [Scrivito::ScrivitoError] if id is blank
+      # @raise [Scrivito::ScrivitoError] if id is more than 64 characters long
+      # @yieldparam [Scrivito::UserDefinition] user object to define abilities on
+      # @see Scrivito::UserDefinition#can
+      # @see Scrivito::UserDefinition#description
+      # @example
+      #   Scrivito::User.define('alice') do |user|
+      #     user.can(:publish_workspace) { true }
+      #   end
+      #
+      #   Scrivito::User.define('bob') do |user|
+      #     user.description { 'Bob Doe' }
+      #     user.can(:publish_workspace) { true }
+      #   end
+      def define(id, &block)
+        assert_valid_id(id)
+        user_definition = UserDefinition.new(id)
+        yield user_definition
+        user_definition.user
+      end
+
+      def anonymous_admin
+        User.new(
+          id: nil,
+          abilities: Hash.new(-> {true}).with_indifferent_access,
+          description_proc: nil,
+          suggest_users_proc: nil
+        )
+      end
+
+      def find(id)
+        if Configuration.find_user_proc
+          user = Scrivito::Configuration.find_user_proc.call(id)
+          assert_valid_user(user)
+          user
+        end
+      end
+
+      private
+
+      def assert_valid_id(id)
+        raise ScrivitoError.new('User id can not be blank') if id.blank?
+        raise ScrivitoError.new('User id is too long (max length 64)') if id.length > 64
+      end
+
+      def assert_valid_user(user)
+        unless user.is_a?(User) || user.nil?
+          raise ScrivitoError.new("Expected an instance of #{self} or nil, but got #{user.inspect}")
+        end
+      end
+    end
+
+    def initialize(options)
+      super(*options.values_at(:id, :abilities, :description_proc,
+        :suggest_users_proc, :restriction_set))
+    end
+
+    def able_to?(ability_name)
+      !!abilities[ability_name].call
+    end
+
+    # Verfies if the User is able to publish changes to a certain {BasicObj Obj}
+    #
+    # @api beta
+    # @param [BasicObj] obj the obj that should be published
+    # @return [Boolean] true if the user is allowed to publish 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
+    #
+    # @api beta
+    # @param [BasicObj] obj the obj that should be published
+    # @return [Array<String>] Hints why the user can't publish
+    def restriction_messages_for(obj)
+      return [] if able_to?(UserDefinition::ADMINISTRATE_CMS_ABILITY)
+
+      if obj.modification == Modification::EDITED
+        base_revision_obj = obj.in_revision(obj.revision.workspace.base_revision)
+
+        restriction_set.restriction_messages_for(obj) |
+          restriction_set.restriction_messages_for(base_revision_obj)
+      else
+        restriction_set.restriction_messages_for(obj)
+      end
+    end
+
+    def description
+      @description ||= calculate_description
+    end
+
+    def suggest_users(input)
+      suggest_users_proc ? suggest_users_proc.call(input) : []
+    end
+
+    private
+
+    def calculate_description
+      description_proc ? description_proc.call : id
+    end
+  end
+end

data/lib/scrivito/user_definition.rb

@@ -0,0 +1,159 @@
+module Scrivito
+  # @api beta
+  class UserDefinition < Struct.new(:user_id)
+    # Allows user to publish a workspace.
+    # @api beta
+    PUBLISH_WORKSPACE_ABILITY = 'publish_workspace'
+
+    # Allows user to do everything.
+    # @api beta
+    ADMINISTRATE_CMS_ABILITY = 'administrate_cms'
+
+    # @api beta
+    ABILITY_NAMES = [
+      ADMINISTRATE_CMS_ABILITY,
+      PUBLISH_WORKSPACE_ABILITY,
+    ]
+
+    # Defines a user ability.
+    # @api beta
+    # @param [String, Symbol] ability_name name of the ability
+    # @param [Proc] ability_proc proc to check if the ability can be granted
+    # @raise [Scrivito::ScrivitoError] if the given ability name is unknown
+    # @raise [Scrivito::ScrivitoError] if no ability proc is given
+    # @yieldreturn If the block returns a "truthy" value, then the ability will be granted
+    # @yieldreturn If the block returns a "falsy" value, then the ability will be prohibited
+    # @see ABILITY_NAMES
+    # @see Scrivito::User.define
+    # @example
+    #   allowed_user = nil
+    #
+    #   alice = Scrivito::User.define('alice') do |user|
+    #     user.can(:publish_workspace) { allowed_user == 'alice' }
+    #   end
+    #
+    #   bob = Scrivito::User.define('bob') do |user|
+    #     user.can(:publish_workspace) { allowed_user == 'bob' }
+    #   end
+    #
+    #   # The users `alice` and `bob` will both be not allowed to publish workspace.
+    #
+    #   allowed_user = 'alice'
+    #   # The user `alice` will now be allowed to publish workspace,
+    #   # but the user `bob` will still be not allowed.
+    #
+    #   allowed_user = 'bob'
+    #   # The user `bob` will now be allowed to publish workspace,
+    #   # but the user `alice` will be not allowed again.
+    def can(ability_name, &ability_proc)
+      assert_valid_ability(ability_name, ability_proc)
+      abilities[ability_name] = ability_proc
+    end
+
+    # Defines the user description to be displayed, when the user is shown in the in-place GUI.
+    # @api beta
+    # @param [Proc] description_proc proc to calculate the description. Defaults to the the user id.
+    # @note The description is calculated "lazy".
+    # @note The calculated description will be cached.
+    # @see Scrivito::User.define
+    # @example
+    #   alice = Scrivito::User.define('alice') {}
+    #   # User `alice` will be displayed as "alice" in the in-place GUI.
+    #
+    #   bob = Scrivito::User.define('bob') do |user|
+    #     user.description { 'Bob Doe' }
+    #   end
+    #   # User `bob` will be displayed as "Bob Doe" in the in-place GUI.
+    def description(&description_proc)
+      @description_proc = description_proc
+    end
+
+    # Defines the proc for fetching users for the user autocompletion of the in-place GUI.
+    # The user autocompletion is for example used in the details dialog of a workspace.
+    # @api beta
+    # @param [Proc] suggest_users_proc proc for fetching users to be suggested in the in-place GUI
+    # @yieldparam [String] input an arbitrary string from the input field of a user autocompletion,
+    #   e.g. the first letters of a user name
+    # @yieldreturn [Array<Scrivito::User>] users that were found for the given input string
+    # @note Only the first 20 of the returnes users will be displayed in the in-place GUI.
+    # @note +suggest_users_proc+ may also be invoked with an empty string.
+    # @example
+    #   class MyUserModel
+    #     def to_scrivito_user
+    #       Scrivito::User.define(id) do |user|
+    #         user.suggest_users do |input|
+    #           MyUserModel.find_by_prefix(input).map(&:to_scrivito_user)
+    #         end
+    #       end
+    #     end
+    #   end
+    def suggest_users(&suggest_users_proc)
+      @suggest_users_proc = suggest_users_proc
+    end
+
+    # Lets you restrict the ability of a user to publish a certain object. Each
+    # registered callback can access a certain attribute of an object. Multiple
+    # callbacks are possible
+    #
+    # @api beta
+    # @param [Hash] options
+    # @option options [Symbol] :uses the attribute you need in the callback
+    # @yield [attribute] the value of the specified attribute
+    # @yieldreturn [String, false] either return a message for the user or false if
+    #   no restriction is needed
+    #
+    # @note the callback is only called with {BasicObj Objs} that have the attribute
+    #   specified by the :uses option and if it is not a {BasicWidget Widget}-attribute
+    #
+    # @example
+    #   class MyUserModel
+    #     def to_scrivito_user
+    #       Scrivito::User.define(id) do |user|
+    #         user.restrict_obj_publish(uses: :_path) do |path|
+    #           if path.start_with?("/en")
+    #             false
+    #           else
+    #             "You are only allowed to edit the English site"
+    #           end
+    #         end
+    #
+    #         user.restrict_obj_publish(uses: :_obj_class) do |obj_class|
+    #           if obj_class == "BlogPost"
+    #             false
+    #           else
+    #             "You are only allowed to edit Blog Posts"
+    #           end
+    #         end
+    #       end
+    #     end
+    #   end
+    def restrict_obj_publish(options, &block)
+      restriction_set.add(options, &block)
+    end
+
+    def user
+      User.new(id: user_id, abilities: abilities, description_proc: @description_proc,
+        suggest_users_proc: @suggest_users_proc, restriction_set: restriction_set)
+    end
+
+    private
+
+    def restriction_set
+      @restriction_set ||= RestrictionSet.new
+    end
+
+    def abilities
+      @abilities ||= Hash.new(-> { false }).with_indifferent_access
+    end
+
+    def assert_valid_ability(ability_name, ability_proc)
+      unless ABILITY_NAMES.include?(ability_name.to_s)
+        raise ScrivitoError.new("'#{ability_name}' is not a valid ability name")
+      end
+
+      unless ability_proc
+        raise ScrivitoError.new("No proc given for ability '#{ability_name}'")
+      end
+    end
+  end
+end