scrivito_sdk 0.66.0 → 0.70.0.rc1

data/lib/scrivito/user_definition.rb

@@ -9,32 +9,33 @@ module Scrivito
     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.
+    # Adds an explicit rule that allows the user to _always_ execute an action.
+    # A rule consists of an action verb, 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
+    # @note Usually, the memberships of a workspace decide whether a user is allowed or not to
+    #   perform a specific action. This method lets you add an exception to this logic and thus
     #   should be used carefully.
-    # @note By default all users are allowed to create a new workspace.
+    # @note By default, all users are allowed to create a new workspace.
+    # @see http://scrivito.com/user-permissions Defining users and their permissions
     #
     # @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 [Symbol] subject the subject of the action. Currently, 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}.
+    # @raise [Scrivito::ScrivitoError] if the specified rule conflicts with a
+    #   {Scrivito::UserDefinition#can_never} rule.
     #
     # @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 from, write to, 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)
@@ -43,34 +44,34 @@ module Scrivito
     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.
+    # Adds an explicit rule that forbids the user to execute an action.
+    # A rule consists of an action verb, 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
+    # @note Usually, the memberships of a workspace decide whether a user is allowed or not to
+    #   perform a specific action. This method lets you 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
+    # @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 [Symbol] subject the subject of the action. Currently, 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}.
+    # @raise [Scrivito::ScrivitoError] if the specified rule conflicts with a
+    #   {Scrivito::UserDefinition#can_always} rule.
     #
     # @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 they're a workspace owner:
     #   Scrivito::User.define('alice') do |user|
-    #     user.can_never(:publish, :workspace, 'You can not publish workspaces.')
+    #     user.can_never(:publish, :workspace, 'You cannot publish workspaces.')
     #   end
     #
-    # @example User cannot create a workspace
+    # @example User cannot create a workspace:
     #   Scrivito::User.define('bob') do |user|
     #     user.can_never(:create, :workspace)
     #   end
@@ -81,8 +82,8 @@ module Scrivito
     end
 
     #
-    # Make the user to be always able to create workspaces, to read, to write, to publish, to delete
-    # and to invite to any workspace.
+    # Enable the user to create workspaces, to read from, write to, publish, delete workspaces,
+    # and to invite others to collaborate on any workspace.
     #
     # @api public
     #
@@ -91,22 +92,21 @@ module Scrivito
     end
 
     #
-    # Defines the user description to be displayed, when the user is shown in the in-place GUI.
+    # Defines the user description to be displayed in the in-place GUI, e.g. in the workspace menu.
     #
     # @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.
+    # @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.
     #
-    # @note The description is calculated "lazy".
-    # @note The calculated description will be cached.
+    # @note The description is calculated "lazyly". The calculated description is cached.
     #
     # @see Scrivito::User.define
     #
-    # @example Display the user +alice+ as +"alice"+ in the in-place GUI
+    # @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
+    # @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
@@ -126,20 +126,20 @@ module Scrivito
     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.
+    # Defines the proc for fetching users for autocompletion purposes in the in-place GUI.
+    # User autocompletion is used in the settings dialog of a workspace.
+    # If the proc is not set, {Scrivito::User.find} is used to fetch the suggested users,
+    # assuming the input is part of the user id.
     #
     # @api public
     #
-    # @note Only the first 20 of the returnes users will be displayed in the in-place GUI.
+    # @note Only the first 20 users returned are 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,
+    # @yieldparam [String] input an arbitrary string originating from the user autocompletion input field,
     #   e.g. the first letters of a user name
-    # @yieldreturn [Array<Scrivito::User>] users that were found for the given input string
+    # @yieldreturn [Array<Scrivito::User>] users that were found on account of the given input string
     #
     # @example
     #   class MyUserModel
@@ -157,20 +157,21 @@ module Scrivito
     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
+    # Lets you restrict a user's capability to publish a specific CMS object. Each
+    # registered callback may refer to one 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
+    # @note The callback is only executed for {BasicObj Objs} equipped with the attribute
+    #   specified using the +:using+ option. It is not executed for a {BasicWidget Widget}
+    #   with this attribute.
     #
     # @param [Hash] options
-    # @option options [Symbol] :using the attribute you need in the callback
+    # @option options [Symbol] :using the attribute you with to refer to 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
+    # @yieldreturn [String, false] either return a message for the user or +false+ if
+    #   no restriction applies
     #
     # @example
     #   class MyUserModel
@@ -180,7 +181,7 @@ module Scrivito
     #           if path.start_with?("/en")
     #             false
     #           else
-    #             "You are only allowed to edit the English site"
+    #             "You are only allowed to edit the English site."
     #           end
     #         end
     #
@@ -188,7 +189,7 @@ module Scrivito
     #           if obj_class_name == 'BlogPost'
     #             false
     #           else
-    #             'You are only allowed to edit Blog Posts'
+    #             'You are only allowed to edit Blog Posts.'
     #           end
     #         end
     #       end

data/lib/scrivito/widget_tag.rb

@@ -5,6 +5,17 @@ class WidgetTag < Struct.new(:view, :widget, :placement_modification, :template_
 
   include TagRenderer
 
+  def render
+    super
+  rescue => error
+    if !['development', 'test'].include?(Rails.env) &&
+        view.controller.respond_to?(:on_scrivito_widget_error)
+      view.controller.on_scrivito_widget_error(widget, error)
+    else
+      raise error
+    end
+  end
+
   def tag_name
     inner_tag || DEFAULT_TAG
   end

data/lib/scrivito/workspace.rb

@@ -2,8 +2,12 @@ require 'active_model/naming'
 
 module Scrivito
 
-# This class represents a CMS workspace
 # @api public
+# This class represents a CMS workspace, called "working copy" in the UI. A working copy lets
+# editors create and modify content independently of the published content or other working copies.
+# On creation, a working copy is based on the currently published content.
+# @see http://scrivito.com/about-working-copies About working copies
+
 class Workspace
   extend ActiveModel::Naming
 
@@ -11,7 +15,7 @@ class Workspace
 
   PublishPreventedDueToContentChange = Class.new(ScrivitoError)
 
-  # Set the currently used workspace
+  # Set the workspace to use for subsequent workspace operations.
   # @api public
   # @param [Scrivito::Workspace] workspace
   def self.current=(workspace)
@@ -22,7 +26,7 @@ class Workspace
     @current = workspace_proc
   end
 
-  # Returns the currently used workspace
+  # Returns the currently used workspace.
   # @api public
   # @return [Scrivito::Workspace]
   def self.current
@@ -33,7 +37,7 @@ class Workspace
     end
   end
 
-  # Returns all the workspaces
+  # Returns all workspaces.
   # @api public
   # @return [Array<Scrivito::Workspace>]
   def self.all
@@ -48,7 +52,24 @@ class Workspace
     find("published")
   end
 
-  # Find a workspace by its id
+  def self.published_with_fallback
+    cached_workspace_data = CmsBackend.instance.find_workspace_data_from_cache('published')
+
+    if cached_workspace_data
+      workspace_data = begin
+        CmsBackend.instance.find_workspace_data_by_id('published', 0.5)
+      rescue => e
+        warn_backend_not_available(e.message)
+        cached_workspace_data
+      end
+
+      from_workspace_data('published', workspace_data)
+    else
+      published
+    end
+  end
+
+  # Find a workspace by its id.
   # @api public
   # @param [String] id
   # @return [Scrivito::Workspace]
@@ -57,17 +78,13 @@ class Workspace
     cache.fetch(id) do
       workspace_data = CmsBackend.instance.find_workspace_data_by_id(id)
 
-      unless workspace_data
-        raise ResourceNotFound, "Could not find #{self} with id #{id}"
-      end
-
-      cache[id] = Workspace.new(workspace_data)
+      from_workspace_data(id, workspace_data)
     end
   end
 
   # Find a workspace by its title.
   # If multiple workspaces share the same title, one of them is returned.
-  # If no workspace with the given title can be found, nil is returned.
+  # If no workspace with the given title can be found, +nil+ is returned.
   # @api public
   # @param [String] title
   # @return [Scrivito::Workspace]
@@ -108,7 +125,9 @@ class Workspace
   delegate :content_state_id, :base_content_state_id, :content_state,
     :base_revision_id, :base_content_state, to: :data
 
-  # Create a new workspace
+  # Create a new workspace.
+  # @example Create a workspace, providing its title:
+  #   Scrivito::Workspace.create(title: "Jane")
   # @api public
   # @param [Hash] attributes
   # @return [Scrivito::Workspace]
@@ -118,8 +137,8 @@ class Workspace
     self.find(workspace_json["id"])
   end
 
-  # reloads the current workspace to reflect any changes to it that may have happened concurrently
-  # since it was loaded
+  # Reloads the current workspace to reflect the changes that were made to it concurrently
+  # since it was loaded.
   # @api public
   def self.reload
     current.reload
@@ -130,19 +149,19 @@ class Workspace
   end
 
   def initialize(workspace_data)
-    @workspace_data = workspace_data
+    update_data(workspace_data)
+    @id = data.id
   end
 
-  # Reloads this workspace to reflect any changes to it that may have happened concurrently since
-  # it was loaded
+  # Reloads this workspace to reflect the changes that were made to it concurrently since
+  # it was loaded.
   # @api public
   def reload
-    @workspace_data = CmsBackend.instance.find_workspace_data_by_id(self.id)
+    update_data(method(:fetch_workspace_data))
+  end
 
-    # Clear all cached instance variables.
-    @base_revision = nil
-    @memberships   = nil
-    @revision      = nil
+  def eager_reload
+    update_data(fetch_workspace_data)
   end
 
   def api_request(verb, path, payload = nil)
@@ -155,7 +174,7 @@ class Workspace
     CmsRestApi.task_unaware_request(verb, "#{backend_url}#{path}", payload)
   end
 
-  # Updates this workspace's attributes
+  # Updates the attributes of this workspace.
   # @api public
   # @param [Hash] attributes
   # @return [Scrivito::Workspace]
@@ -165,14 +184,14 @@ class Workspace
     reload
   end
 
-  # Destroy this workspace
+  # Destroy this workspace.
   # @api public
   def destroy
     reset_workspace_if_current
     CmsRestApi.delete(backend_url)
   end
 
-  # Publish the changes of this workspace
+  # Publish the changes that were made to this workspace.
   # @api public
   def publish
     CmsRestApi.put("#{backend_url}/publish", {})
@@ -182,42 +201,47 @@ class Workspace
     reset_workspace_if_current
   end
 
-  # Rebases the current workspace on the published content
+  # Rebases the current workspace from the published content in order to integrate the changes
+  # that were published in the meantime.
   # @api public
   def rebase
     CmsRestApi.put("#{backend_url}/rebase", {})
     reload
   end
 
-  # Returns the id of the workspace
+  # Returns the id of the workspace.
   # @api public
   # @return [String]
   def id
-    @workspace_data.id
+    @id
   end
 
   def revision_id
-    @workspace_data.revision_id
+    data.revision_id
   end
 
-  # Returns the title of the workspace or an empty +String+
+  # Returns the title of the workspace if present. Otherwise, and for the published content,
+  # an empty +String+ is returned.
   # @api public
   # @return [String]
   def title
     return '' if published?
-    @workspace_data.title || ''
+    data.title || ''
   end
 
   # @api public
-  # Returns the members of this workspace and their roles
-  #
+  # Returns the memberships (users and their roles) of this workspace.
   # @return [MembershipCollection]
   def memberships
     @memberships ||= MembershipCollection.new(self)
   end
 
   def data
-    @workspace_data
+    if @workspace_data.respond_to?(:call)
+      @workspace_data = @workspace_data.call
+    else
+      @workspace_data
+    end
   end
 
   def published?
@@ -265,7 +289,7 @@ class Workspace
     raise ScrivitoError, 'published workspace is not modifiable' if published?
   end
 
-  # {ObjCollection} for this working copy
+  # Returns an {ObjCollection} of this working copy for accessing its CMS objects.
   # @api public
   # @return {ObjCollection}
   def objs
@@ -294,6 +318,19 @@ class Workspace
 
   private
 
+  def update_data(new_data)
+    @workspace_data = new_data
+
+    # Clear all cached instance variables.
+    @base_revision = nil
+    @memberships   = nil
+    @revision      = nil
+  end
+
+  def fetch_workspace_data
+    CmsBackend.instance.find_workspace_data_by_id(id)
+  end
+
   def backend_url
     "/workspaces/#{id}"
   end
@@ -305,6 +342,27 @@ class Workspace
       Workspace.current = Workspace.published
     end
   end
+
+  class << self
+    private
+
+    def from_workspace_data(id, data)
+      unless data
+        raise ResourceNotFound, "Could not find #{self} with id #{id}"
+      end
+
+      cache[id] = Workspace.new(data)
+    end
+
+    def warn_backend_not_available(error_message)
+      message = <<-EOS
+        Couldn't connect to backend to fetch published workspace.
+        #{error_message}
+        Serving from cache.
+      EOS
+      Rails.logger.warn(message)
+    end
+  end
 end
 
 end

data/lib/scrivito/workspace_selection_middleware.rb

@@ -7,8 +7,15 @@ class WorkspaceSelectionMiddleware
 
   def call(env)
     Workspace.current = proc do
-      env[EditingContextMiddleware::ENVKEY].visible_workspace
+      editing_context = env[EditingContextMiddleware::ENVKEY]
+
+      if editing_context.authenticated_editor?
+        editing_context.visible_workspace
+      else
+        Workspace.published_with_fallback
+      end
     end
+
     @app.call(env)
   end
 

data/lib/scrivito_sdk.rb

@@ -4,7 +4,7 @@ require "scrivito/errors"
 module Scrivito
   #
   # Configures the Scrivito SDK.
-  # The configuration keys +tenant+ and +api_key+ _must_ be provided.
+  # The +tenant+ and +api_key+ configuration keys _must_ be provided.
   #
   # @example
   #   Scrivito.configure do |config|
@@ -19,23 +19,23 @@ module Scrivito
   end
 
   #
-  # Configures which models Scrivito assumes as pages and widgets.
+  # Configures which models Scrivito regards as pages and widgets.
   #
   # @api public
   #
   # In order to display a page class selection dialog and a widget class selection dialog, Scrivito
-  # needs to know which page models and widget models are available. That models can be defined in
+  # needs to know which page models and widget models are available. These models can be defined in
   # the Rails application itself or in 3rd-party gems.
   #
-  # Scrivito will automatically assume all the classes descending from {Scrivito::BasicObj}, whose
-  # class names are ending with +Page+ are pages (e.g. +MyPage+, +HomePage+, +BlogPostPage+ etc.).
-  # It will also automatically assume all the classes descending from {Scrivito::BasicWidget}, whose
-  # class names are ending with +Widget+ are widgets (e.g. +TextWidget+, +ImageWdidget+ etc.).
+  # Scrivito assumes that all the classes descending from {Scrivito::BasicObj}, whose
+  # class names end with +Page+ are pages (e.g. +MyPage+, +HomePage+, +BlogPostPage+ etc.).
+  # It also assumes that all the classes descending from {Scrivito::BasicWidget}, whose
+  # class names end with +Widget+ are widgets (e.g. +TextWidget+, +ImageWdidget+ etc.).
   #
-  # Scrivito will recursively scan for such models in all directories from
+  # Scrivito recursively scans for such models in all directories from
   # {Scrivito::ModelLibrary#paths Scrivito.models.paths}, which is an array of strings.
-  # It by default includes the directory +app/models+ of the Rails application. For example it will
-  # find following page and widget models:
+  # By default, Scrivito includes the +app/models+ directory of the Rails application when searching
+  # for models. It will, for example, find the following page and widget models:
   #
   # +app/models/my_page.rb+
   #
@@ -49,10 +49,10 @@ module Scrivito
   #
   # +app/models/my_namespace/my_other_namespace/my_other_special_widget.rb+
   #
-  # Also {Scrivito::ModelLibrary#paths Scrivito.models.paths} will include all directories ending
-  # with +app/models+ of any available Rails engine, as long as that directory is included in the
-  # autoload paths of Rails (which is the default). For example it will find following page and
-  # widget models in an engine:
+  # Also, {Scrivito::ModelLibrary#paths Scrivito.models.paths} includes all +app/models+
+  # directories of any available Rails engine, provided that these directories are included in the
+  # autoload paths of Rails (which is the default). For example, it will find the following page
+  # and widget models in an engine:
   #
   # +/../some_engine/app/models/my_page.rb+
   #
@@ -67,23 +67,23 @@ module Scrivito
   # +/../some_engine/app/models/my_namespace/my_other_namespace/my_other_special_widget.rb+
   #
   # You can add custom directories to scan for models and register single page and widget models
-  # with {Scrivito::ModelLibrary#define Scrivito.models.define} (see examples below).
+  # using {Scrivito::ModelLibrary#define Scrivito.models.define} (see examples below).
   #
   # The loaded pages can be inspected with {Scrivito::ModelLibrary#pages Scrivito.models.pages},
-  # which will return a {Scrivito::ClassCollection} containing all available pages.
+  # which will return a {Scrivito::ClassCollection} containing the available pages.
   # The loaded widgets can be inspected with {Scrivito::ModelLibrary#widgets Scrivito.models.widgets},
-  # which will return a {Scrivito::ClassCollection} containing all available widgets.
+  # which will return a {Scrivito::ClassCollection} containing the available widgets.
   #
-  # The scan results are cached. If +Rails.application.config.cache_classes+ is +false+, then the
-  # cache will be cleared on every request. Otherwise the cache will be kept between the requests.
-  # You can clear the cache with {Scrivito::ModelLibrary#clear_cache Scrivito.models.clear_cache}.
+  # The scan results are cached. If +Rails.application.config.cache_classes+ is +false+, the
+  # cache is cleared on every request. Otherwise, the cache is kept between the requests.
+  # You can clear the cache using {Scrivito::ModelLibrary#clear_cache Scrivito.models.clear_cache}.
   #
-  # @example Register a custom path
+  # @example Register a custom path:
   #   Scrivito.models.define do
   #     paths << Rails.root + 'lib/special_models'
   #   end
   #
-  # @example Register pages and widgets with inconvenient names
+  # @example Register pages and widgets with unusual names:
   #   Scrivito.models.define do
   #     page 'MyCrazyPageModel'
   #     page 'MyOtherCrazyPageModel1', 'MyOtherCrazyPageModel2'
@@ -92,7 +92,7 @@ module Scrivito
   #     widget 'MyOtherCrazyWidgetModel1', 'MyOtherCrazyWidgetModel2'
   #   end
   #
-  # @example Iterate over available pages
+  # @example Iterate over the available pages:
   #   Scrivito.models.pages.each do |page_class|
   #     puts page_class.name
   #   end
@@ -100,7 +100,7 @@ module Scrivito
   #   #=> "MyOtherPage"
   #   # ...
   #
-  # @example Iterate over available widgets
+  # @example Iterate over the available widgets:
   #   Scrivito.models.widgets.each do |widget_class|
   #     puts widget_class.name
   #   end