user_definition.rb in scrivito_sdk-0.50.0.rc1

- old
+ new

@@ -1,56 +1,82 @@
 module Scrivito
+  #
   # @api public
+  #
   class UserDefinition
     def initialize(user_id)
       @user_id = user_id
       @explicit_rules = {}
     end
 
+    #
     # Adds an explicit rule, that allows the user to _always_ execute an action.
     # A rule consists of a verb of the action, the subject of the action and an optional message.
+    #
     # @api public
+    #
+    # @note Normally the memberships of a workspace decide whether a user is allowed or not to
+    #   execute a specific action. This method allows to add an exception to this logic and thus
+    #   should be used carefully.
+    # @note By default all users are allowed to create a new workspace.
+    #
     # @param [Symbol] verb the verb of the action (see {Scrivito::User::VERBS}).
     # @param [Symbol] subject the subject of the action. At the moment only +:workspace+ is supported.
     # @param [String] message optional message to be displayed in the UI.
+    #
     # @raise [Scrivito::ScrivitoError] if the given verb is invalid
     # @raise [Scrivito::ScrivitoError] if the specified rule conflicts with a rule specified with
     #   {Scrivito::UserDefinition#can_never}.
-    # @note Normally the memberships of a workspace decide whether a user is allowed or not to
-    #   execute a specific action. This method allows to add an exception to this logic and thus
-    #   should be used carefully.
+    #
     # @see Scrivito::User::VERBS
     # @see Scrivito::UserDefinition#can_never
-    # @example User can _always_ read, write and publish a workspace, ignoring the memberships.
+    #
+    # @example User can _always_ read, write and publish a workspace, ignoring the memberships
     #   Scrivito::User.define('alice') do |user|
     #     user.can_always(:read, :workspace)
     #     user.can_always(:write, :workspace)
-    #     user.can_always(:publish, :workspace, 'You can always publish a workspace.)
+    #     user.can_always(:publish, :workspace, 'You can always publish a workspace')
     #   end
+    #
     def can_always(verb, subject, message = nil)
       assert_no_conflict(:can_never, verb, subject)
       @explicit_rules[[:can_always, verb, subject]] = message
     end
 
+    #
     # Adds an explicit rule, that forbids the user to execute an action.
     # A rule consists of a verb of the action, the subject of the action and an optional message.
+    #
     # @api public
+    #
+    # @note Normally the memberships of a workspace decide whether a user is allowed or not to
+    #   execute a specific action. This method allows to add an exception to this logic and thus
+    #   should be used carefully.
+    # @note By default all users are allowed to create a new workspace. Use this method to forbid a
+    #   user to create a new workspace.
+    #
     # @param [Symbol] verb the verb of the action (see {Scrivito::User::VERBS}).
     # @param [Symbol] subject the subject of the action. At the moment only +:workspace+ is supported.
     # @param [String] message optional message to be displayed in the UI.
+    #
     # @raise [Scrivito::ScrivitoError] if the given verb is invalid
     # @raise [Scrivito::ScrivitoError] if the specified rule conflicts with a rule specified with
     #   {Scrivito::UserDefinition#can_always}.
-    # @note Normally the memberships of a workspace decide whether a user is allowed or not to
-    #   execute a specific action. This method allows to add an exception to this logic and thus
-    #   should be used carefully.
+    #
     # @see Scrivito::User::VERBS
     # @see Scrivito::UserDefinition#can_always
-    # @example User can _never_ publish a workspace, even if she's a workspace owner.
+    #
+    # @example User can _never_ publish a workspace, even if she's a workspace owner
     #   Scrivito::User.define('alice') do |user|
     #     user.can_never(:publish, :workspace, 'You can not publish workspaces.')
     #   end
+    #
+    # @example User cannot create a workspace
+    #   Scrivito::User.define('bob') do |user|
+    #     user.can_never(:create, :workspace)
+    #   end
+    #
     def can_never(verb, subject, message = nil)
       assert_no_conflict(:can_always, verb, subject)
       @explicit_rules[[:can_never, verb, subject]] = message
     end
 
@@ -64,10 +90,11 @@
       User::VERBS.each { |verb| @explicit_rules[[:can_always, verb, :workspace]] ||= nil }
     end
 
     #
     # Defines the user description to be displayed, when the user is shown in the in-place GUI.
+    #
     # @api public
     #
     # @param [String] description_string the description. Defaults to the the user id.
     # @param [Proc] description_proc proc to calculate the description. Defaults to the the user id.
     #
@@ -75,15 +102,13 @@
     # @note The calculated description will be cached.
     #
     # @see Scrivito::User.define
     #
     # @example Display the user +alice+ as +"alice"+ in the in-place GUI
-    #
     #   alice = Scrivito::User.define('alice')
     #
     # @example Display the user +bob+ as +"Bob Doe"+ in the in-place GUI
-    #
     #   bob = Scrivito::User.define('bob') do |user|
     #     user.description('Bob Doe')
     #   end
     #
     #   bob = Scrivito::User.define('bob') do |user|
@@ -98,49 +123,57 @@
       else
         @description_proc = description_proc
       end
     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.
     # If the proc is not set, then {Scrivito::User.find} will be used to fetch the suggested users with input
     # as the user id.
+    #
     # @api public
+    #
+    # @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.
+    #
     # @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 rule of a user to publish a certain object. Each
     # registered callback can access a certain attribute of an object. Multiple
     # callbacks are possible
     #
     # @api public
+    #
+    # @note the callback is only called with {BasicObj Objs} that have the attribute
+    #   specified by the :using option and if it is not a {BasicWidget Widget}-attribute
+    #
     # @param [Hash] options
     # @option options [Symbol] :using 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 :using 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(using: :_path) do |path|
@@ -159,9 +192,10 @@
     #           end
     #         end
     #       end
     #     end
     #   end
+    #
     def restrict_obj_publish(options, &block)
       restriction_set.add(options, &block)
     end
 
     def user