scrivito_sdk 0.18.1 → 0.30.0.rc1

data/lib/generators/scrivito/install/templates/app/views/page/thumbnail.html.erb

@@ -0,0 +1,3 @@
+<%= scrivito_thumbnail 'Page', :content do %>
+  A simple content page with a headline and content consisting of widgets.
+<% end %>

data/lib/generators/scrivito/install/templates/app/views/text_widget/show.html.erb

@@ -0,0 +1 @@
+<%= scrivito_tag :div, widget, :text %>

data/lib/generators/scrivito/install/templates/app/views/text_widget/thumbnail.html.erb

@@ -0,0 +1,3 @@
+<%= scrivito_thumbnail 'Text Widget', :text do %>
+  A widget for text and HTML content.
+<% end %>

data/lib/generators/scrivito/install/templates/config/initializers/scrivito.rb

@@ -0,0 +1,10 @@
+Scrivito.configure do |config|
+  #
+  # Uncomment following lines in order to explicitly set the tenant and the API key.
+  # If not explicitly set, the tenant and the API key are obtained from the environment variables
+  # SCRIVITO_TENANT and SCRIVITO_API_KEY.
+  #
+  # config.tenant = 'my-tenant-123'
+  # config.api_key = 'secret'
+  #
+end

data/lib/generators/scrivito/install/templates/scrivito/migrate/install_scrivito.rb

@@ -0,0 +1,49 @@
+class InstallScrivito < Scrivito::Migration
+  def up
+    Scrivito::ObjClass.create(name: 'Page', attributes: [
+      {name: 'title', type: 'string'},
+      {name: 'body',     type: 'widget'},
+      {name: 'child_order', type: 'referencelist'},
+    ])
+
+    Scrivito::ObjClass.create(name: 'HeadlineWidget', attributes: [
+      {name: 'headline', type: 'string'},
+    ])
+
+    Scrivito::ObjClass.create(name: 'TextWidget', attributes: [
+      {name: 'text', type: 'html'},
+    ])
+
+    Scrivito::ObjClass.create(name: 'Image', attributes:[
+      {name: 'blob', type: 'binary'},
+    ])
+
+    Scrivito::ObjClass.create(name: 'ImageWidget', attributes: [
+      {name: 'image',  type: 'reference'}
+    ])
+
+    Page.create(_path: '/', title: 'Welcome to Scrivito!', body: [
+      HeadlineWidget.new(headline: 'A professional Cloud CMS built for Ruby on Rails.'),
+      TextWidget.new(text: %{
+        <h3>Add content management to your website</h3>
+        <p>
+        With Scrivito, you can develop your website like you always did.
+        It just works, and it just works "The Rails Way".
+        </p>
+        <h3>No training for your editors required.</h3>
+        <p>
+        Your clients can edit content in-place, directly on the website itself.
+        Intuitively, without any training or HTML skills.
+        </p>
+        <h3>No installation required</h3>
+        <p>
+        You should focus on the important things:
+        Developing the functionality and look of your website.
+        That's why we built Scrivito as a cloud service.
+        So you don't have to keep on updating your CMS or worry about uptime all the time.
+        And you always get the newest features.
+        </p>
+      })
+    ])
+  end
+end

data/lib/generators/scrivito/migration/USAGE

@@ -0,0 +1,9 @@
+Description:
+    Creates a new CMS migration.
+
+Example:
+    rails generate scrivito:migration CreateExample
+    rails generate scrivito:migration create_example
+
+    This will create:
+        scrivito/migrate/[timestamp]_create_example.rb

data/lib/generators/{cms → scrivito}/migration/migration_generator.rb

@@ -1,21 +1,16 @@
-module Cms
+module Scrivito
   class MigrationGenerator < ::Rails::Generators::NamedBase
     include ::Rails::Generators::Migration
 
     source_root File.expand_path('../templates', __FILE__)
 
-    class_option :path,
-      type: :string,
-      default: 'cms/migrate',
-      desc: 'Relative path to Rails.root where to place the migration file. Defaults to "cms/migrate".',
-      banner: 'PATH'
-
     def self.next_migration_number(dirname)
       Time.now.utc.strftime('%Y%m%d%H%M%S')
     end
 
     def create_migration_file
-      migration_template('migration.erb', "#{options[:path]}/#{file_name}.rb")
+      base_path = Scrivito::Configuration.migration_path
+      migration_template('migration.erb', File.join(base_path, "#{file_name}.rb"))
     end
   end
-end
+end

data/lib/generators/{cms → scrivito}/migration/templates/migration.erb

@@ -4,12 +4,12 @@ class <%= class_name %> < ::Scrivito::Migration
     # content programatically. All Scrivito SDK classes and methods are available and arbitrary Ruby
     # code can be executed.
     #
-    # Use `bundle exec rake cms:migrate` to run all migrations that are new to the `rtc` workspace.
+    # Use `bundle exec rake scrivito:migrate` to run all migrations that are new to the `rtc` workspace.
     # Migrations are identified by an ID and only get executed once. If you migrate the CMS an
     # existing `rtc` workspace is used or a new `rtc` workspace is created. Only one developer at a
     # time can run migrations, which means to quickly try to publish the current migrations.
     #
-    # Use `bundle exec rake cms:migrate:publish` to publish your `rtc` workspace that holds the
+    # Use `bundle exec rake scrivito:migrate:publish` to publish your `rtc` workspace that holds the
     # latest unpublished migrations.
     #
     # To get you started, here is a list of the most common SDK methods to alter the CMS content.
@@ -26,7 +26,7 @@ class <%= class_name %> < ::Scrivito::Migration
     #   Scrivito::ObjClass.find('Homepage').update(is_active: false)
     #
     # @example Add an "enum" attribute named "category" to the obj class named "Homepage".
-    #   Scrivito::ObjClass.find('Homepage').attributes.add(name: 'category', type: :enum, values: %w(tech, social))
+    #   Scrivito::ObjClass.find('Homepage').attributes.add(name: 'category', type: :enum, values: %w(tech social))
     #
     # @example Update the "category" attribute and add another value.
     #   attribute = Scrivito::ObjClass.find('Homepage').attributes['category']

data/lib/generators/scrivito/widget/templates/thumbnail.html.erb

@@ -0,0 +1,3 @@
+<%%= scrivito_thumbnail '<%= class_name %>' do %>
+  <% class_name %> Widget
+<%% end %>

data/lib/generators/{cms → scrivito}/widget/widget_generator.rb

@@ -1,4 +1,4 @@
-module Cms
+module Scrivito
   module Generators
     class WidgetGenerator < ::Rails::Generators::NamedBase
       include ::Rails::Generators::Migration
@@ -23,7 +23,8 @@ module Cms
       end
 
       def generate_migration
-        migration_template('migration.erb', "cms/migrate/create_#{file_name}.rb")
+        base_path = Scrivito::Configuration.migration_path
+        migration_template('migration.erb', File.join(base_path, "/create_#{file_name}.rb"))
       end
     end
   end

data/lib/obj.rb

@@ -1,3 +1,17 @@
-# empty implementation for Obj
-# only unsed in case the app does not define Obj itself
-::Obj = Class.new(Scrivito::BasicObj)
+# The class +Obj+ should be overridden by the application (see example).
+# The SDK provides methods for {Obj} through it's abstract base class, {Scrivito::BasicObj}.
+# The Scrivito SDK provides this empty implementation for {Obj}
+# which will only be used in case the app does not define the class {Obj} itself.
+# @example
+#   # in app/models/obj.rb
+#   class Obj < Scrivito::BasicObj
+#     # put your custom extensions that apply to every Obj here
+#   end
+#
+#   # in app/models/page.rb
+#   class Page < Obj
+#     # put custom extensions that only apply to Objs with class Page here
+#   end
+# @api public
+class Obj < Scrivito::BasicObj
+end

data/lib/scrivito/attribute_collection.rb

@@ -24,24 +24,19 @@ module Scrivito
     # @api public
     def_delegators :@attributes, :each
 
+    #
     # Finds an attribute in this collection by its name.
     #
     # @api public
     #
-    # See {Scrivito::ObjClass#attributes} for example of how to find an attribute by name.
+    # @param [String] name the name of the attribute
+    # @return [Scrivito::Attribute] if there is an attribute with name +name+
+    # @return [nil] if there is no attribute with name +name+
+    #
+    # @see Scrivito::ObjClass#attributes Examples of how to find an attribute by name.
     #
-    # @param [String] name
-    # @return [Scrivito::Attribute]
-    # @raise [Scrivito::ResourceNotFound] Raised when no attribute with the given +name+ can be found.
     def [](name)
-      attribute = @attributes.detect { |attribute| attribute.name == name.to_s }
-
-      unless attribute
-        raise ResourceNotFound, "Could not find #{Attribute} with name '#{name}' for" \
-          " obj class '#{@obj_class.name}'."
-      end
-
-      attribute
+      @attributes.detect { |attribute| attribute.name == name.to_s }
     end
 
     # Adds an attribute to this collection and updates the obj class.

data/lib/scrivito/attribute_content.rb

@@ -41,7 +41,7 @@ module AttributeContent
 
   def has_custom_attribute?(name)
     name = name.to_s
-    name != 'blob' && data_from_cms.has_custom_attribute?(name)
+    data_from_cms.has_custom_attribute?(name)
   end
   alias_method :has_attribute?, :has_custom_attribute?
 
@@ -56,11 +56,7 @@ module AttributeContent
   def [](key)
     key = key.to_s
 
-    if key == '_obj_class'
-      obj_class
-    else
-      has_attribute?(key) ? read_attribute(key) : nil
-    end
+    has_attribute?(key) ? read_attribute(key) : nil
   end
 
   # Hook method to control which widget classes should be available for this page.
@@ -124,6 +120,14 @@ module AttributeContent
     end
   end
 
+  def to_show_view_path
+    to_view_path('show')
+  end
+
+  def to_details_view_path
+    to_view_path('details')
+  end
+
   private
 
   attr_writer :data_from_cms
@@ -137,6 +141,10 @@ module AttributeContent
   end
 
   def prepare_attribute_value(attribute_value, attribute_type, attribute_name)
+    if attribute_name == '_obj_class'
+      return obj_class
+    end
+
     case attribute_type
     when "html"
       StringTagging.tag_as_html(attribute_value)
@@ -147,22 +155,30 @@ module AttributeContent
     when "link"
       build_link(attribute_value)
     when "reference"
-      BasicObj.find([attribute_value]).first
+      workspace.objs.find([attribute_value]).first
     when "referencelist"
-      BasicObj.find(attribute_value).compact
+      workspace.objs.find(attribute_value).compact
     when "widget"
       build_widgets(attribute_value, attribute_name)
+    when "binary"
+      build_binary(attribute_value)
     else
       attribute_value
     end
   end
 
+  def build_binary(binary_definition)
+    if binary_definition && binary_definition['id']
+      Binary.new(binary_definition['id'], workspace.published?)
+    end
+  end
+
   def build_links(link_definitions)
     if link_definitions.present?
       link_definitions = link_definitions.map(&:with_indifferent_access)
 
       object_ids = link_definitions.map { |link_data| link_data[:destination] }.compact.uniq
-      objects = object_ids.empty? ? [] : BasicObj.find(object_ids)
+      objects = object_ids.empty? ? [] : workspace.objs.find(object_ids)
       link_definitions.each_with_object([]) do |link_data, links|
         obj = objects.detect { |o| o && o.id == link_data[:destination] }
         link = Link.new(link_data.merge(obj: obj))
@@ -185,7 +201,7 @@ module AttributeContent
 
   def build_internal_link(attribute_value)
     properties = {
-      obj: BasicObj.find(attribute_value['destination']),
+      obj: workspace.objs.find(attribute_value['destination']),
       title: attribute_value['title'],
       query: attribute_value['query'],
       fragment: attribute_value['fragment'],
@@ -221,6 +237,10 @@ module AttributeContent
     end
   end
 
+  def to_view_path(view_name)
+    "#{obj_class_name.underscore}/#{view_name}"
+  end
+
   module ClassMethods
     # Instantiate an Obj or Widget instance from obj_data.
     # If a subclass of Obj or Widget with the same name as the property +_obj_class+ exists,
@@ -242,8 +262,7 @@ module AttributeContent
 
     def descendants
       type_computer = TypeComputer.new(self, nil)
-      CmsRestApi.get("workspaces/#{Workspace.current.id}/obj_classes")['results']
-          .map { |obj_class_spec| obj_class_spec['name'] }
+      Workspace.current.obj_classes.map(&:name)
           .sort
           .map { |obj_class_name| type_computer.compute_type(obj_class_name) }
           .compact

data/lib/scrivito/basic_obj.rb

@@ -3,7 +3,11 @@ require 'ostruct'
 require 'active_model/naming'
 
 module Scrivito
-  # The CMS file class
+  # The abstract base class for cms objects.
+  #
+  # @note Please do not use {Scrivito::BasicObj} directly,
+  #   as it is intended as an abstract class.
+  #   Always use {Obj} or a subclass of {Obj}.
   # @api public
   class BasicObj
     UNIQ_ATTRIBUTES = %w[
@@ -33,16 +37,16 @@ module Scrivito
       @_type_computer = nil
     end
 
-    # Create a new {BasicObj Obj} in the cms
+    # Create a new {Scrivito::BasicObj Obj} in the cms
     #
     # This allows you to set the different attributes types of an obj by
     # providing a hash with the attributes names as key and the values you want
     # to set as values
     #
-    # @example Reference lists have to be provided as an Array of {BasicObj Objs}
+    # @example Reference lists have to be provided as an Array of {Scrivito::BasicObj Objs}
     #   Obj.create(:reference_list => [other_obj])
     #
-    # @example Passing an {BasicObj Obj} allows you to set a reference
+    # @example Passing an {Scrivito::BasicObj Obj} allows you to set a reference
     #   Obj.create(:reference => other_obj)
     #
     # @example you can upload files by passing a ruby File object
@@ -72,7 +76,7 @@ module Scrivito
     # @example Arrays of {String Strings} allow you to set multi enum fields
     #   Obj.create(:tags => ["ruby", "rails"])
     #
-    # @example Simply pass an Array of {BasicWidget Widgets} to change a widget field. See {BasicWidget#clone Widget#clone} on how to clone a widget.
+    # @example Simply pass an Array of {Scrivito::BasicWidget Widgets} to change a widget field. See {Scrivito::BasicWidget#clone Widget#clone} on how to clone a widget.
     #   # Add new widgets
     #   Obj.create(:widgets => [Widget.new(_obj_class: 'TitleWidget', title: 'My Title')])
     #
@@ -87,7 +91,7 @@ module Scrivito
     #
     # @api public
     # @param [Hash] attributes
-    # @return [Obj] the newly created {BasicObj Obj}
+    # @return [Obj] the newly created {Scrivito::BasicObj Obj}
     def self.create(attributes)
       attributes = with_default_obj_class(attributes)
       api_attributes, widget_properties = prepare_attributes_for_rest_api(attributes, nil)
@@ -97,7 +101,7 @@ module Scrivito
       obj
     end
 
-    # Create a new {BasicObj Obj} instance with the given values and attributes.
+    # Create a new {Scrivito::BasicObj Obj} instance with the given values and attributes.
     # Normally this method should not be used.
     # Instead Objs should be loaded from the cms database.
     def initialize(attributes = {})
@@ -120,7 +124,7 @@ module Scrivito
 
     ### FINDERS ####################
 
-    # Find a {BasicObj Obj} by its id.
+    # Find a {Scrivito::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>]
@@ -133,7 +137,7 @@ module Scrivito
       Workspace.current.objs.find_by_id(id)
     end
 
-    # Find a {BasicObj Obj} by its id.
+    # Find a {Scrivito::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
@@ -147,7 +151,10 @@ module Scrivito
     #
     # 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}).
+    # @note If invoked on a subclass of Obj, the result will be restricted to instances of that subclass.
+    #
+    # {ObjSearchEnumerator}s can be chained using one of the chainable methods
+    # (e.g. {ObjSearchEnumerator#and} and {ObjSearchEnumerator#and_not}).
     #
     # @example Look for the first 10 Objs whose ObjClass is "Pressrelease" and whose title contains "quarterly":
     #   Obj.where(:_obj_class, :equals, 'Pressrelease').and(:title, :contains, 'quarterly').take(10)
@@ -155,20 +162,33 @@ module Scrivito
     # @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
+    # @raise [ScrivitoError] if called on a subclass of +Obj+ with no corresponding {ObjClass}
+    # @raise [ScrivitoError] if called directly on +BasicObj+. Use +Obj.where+ instead.
     # @return [ObjSearchEnumerator]
     # @api public
     def self.where(field, operator, value, boost = nil)
-      Workspace.current.objs.where(field, operator, value, boost)
+      assert_not_basic_obj('.where')
+      if self == ::Obj
+        Workspace.current.objs.where(field, operator, value, boost)
+      else
+        assert_has_obj_class('.where')
+        Workspace.current.objs.where(:_obj_class, :equals, name)
+            .and(field, operator, value, boost)
+      end
     end
 
-    # Returns a {ObjSearchEnumerator} of all {BasicObj Obj}s.
+    # Returns a {ObjSearchEnumerator} of all {Scrivito::BasicObj Obj}s.
     # If invoked on a subclass of Obj, the result will be restricted to instances of that subclass.
     # @return [ObjSearchEnumerator]
+    # @raise [ScrivitoError] if called on a subclass of +Obj+ with no corresponding {ObjClass}
+    # @raise [ScrivitoError] if called directly on +BasicObj+. Use +Obj.all+ instead.
     # @api public
     def self.all
-      if superclass == Scrivito::BasicObj
+      assert_not_basic_obj('.all')
+      if self == ::Obj
         Workspace.current.objs.all
       else
+        assert_has_obj_class('.all')
         find_all_by_obj_class(name)
       end
     end
@@ -181,19 +201,19 @@ module Scrivito
       Workspace.current.objs.find_all_by_obj_class(obj_class)
     end
 
-    # Find the {BasicObj Obj} with the given path.
+    # Find the {Scrivito::BasicObj Obj} with the given path.
     # Returns +nil+ if no matching Obj exists.
-    # @param [String] path Path of the {BasicObj Obj}.
+    # @param [String] path Path of the {Scrivito::BasicObj Obj}.
     # @return [Obj]
     # @api public
     def self.find_by_path(path)
       Workspace.current.objs.find_by_path(path)
     end
 
-    # Find an {BasicObj Obj} with the given name.
+    # Find an {Scrivito::BasicObj Obj} with the given name.
     # If several Objs with the given name exist, an arbitrary one of these Objs is chosen and returned.
     # If no Obj with the name exits, +nil+ is returned.
-    # @param [String] name Name of the {BasicObj Obj}.
+    # @param [String] name Name of the {Scrivito::BasicObj Obj}.
     # @return [Obj]
     # @api public
     def self.find_by_name(name)
@@ -201,23 +221,25 @@ module Scrivito
     end
 
     # Returns a {ObjSearchEnumerator} of all Objs with the given name.
-    # @param [String] name Name of the {BasicObj Obj}.
+    # @param [String] name Name of the {Scrivito::BasicObj Obj}.
     # @return [ObjSearchEnumerator]
     # @api public
     def self.find_all_by_name(name)
       where(:_name, :equals, name)
     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}.
+    # Returns the {Scrivito::BasicObj Obj} with the given permalink, or +nil+ if no matching Obj
+    # exists.
+    # @param [String] permalink The permalink of the {Scrivito::BasicObj Obj}.
     # @return [Obj]
     # @api public
     def self.find_by_permalink(permalink)
       Workspace.current.objs.find_by_permalink(permalink)
     end
 
-    # Returns the {BasicObj Obj} with the given permalink, or raise ResourceNotFound if no matching Obj exists.
-    # @param [String] permalink The permalink of the {BasicObj Obj}.
+    # Returns the {Scrivito::BasicObj Obj} with the given permalink, or raise ResourceNotFound if
+    # no matching Obj exists.
+    # @param [String] permalink The permalink of the {Scrivito::BasicObj Obj}.
     # @return [Obj]
     # @api public
     def self.find_by_permalink!(permalink)
@@ -245,10 +267,10 @@ module Scrivito
     def self.valid_page_classes_beneath(parent_path)
     end
 
-    # Update the {BasicObj Obj} with the attributes provided.
+    # Update the {Scrivito::BasicObj Obj} with the attributes provided.
     #
     # For an overview of which values you can set via this method see the
-    # documentation of {BasicObj.create Obj.create}.
+    # documentation of {Scrivito::BasicObj.create Obj.create}.
     #
     # Additionally, +update+ accepts a +_widget_pool+ hash in +attributes+ to modify widgets.
     # The keys of +_widget_pool+ are widget instances, the values are the modified attributes of
@@ -299,7 +321,7 @@ module Scrivito
       self.class.find(json['_id'])
     end
 
-    # Destroys the {BasicObj Obj} in the current {Workspace}
+    # Destroys the {Scrivito::BasicObj Obj} in the current {Workspace}
     # @api public
     def destroy
       if children.any?
@@ -312,12 +334,12 @@ module Scrivito
       id
     end
 
-    # return the {BasicObj Obj} that is the parent of this Obj.
+    # return the {Scrivito::BasicObj Obj} that is the parent of this Obj.
     # returns +nil+ for the root Obj.
     # @api public
     def parent
       if child_path?
-        BasicObj.find_by_path(parent_path)
+        workspace.objs.find_by_path(parent_path)
       end
     end
 
@@ -334,7 +356,7 @@ module Scrivito
       Workspace.current.objs.find_by_paths(ancestor_paths)
     end
 
-    # return a list of all child {BasicObj Obj}s.
+    # return a list of all child {Scrivito::BasicObj Obj}s.
     # @return [Array<Obj>]
     # @api public
     def children
@@ -345,13 +367,13 @@ module Scrivito
 
     ### ATTRIBUTES #################
 
-    # returns the {BasicObj Obj}'s path as a String.
+    # returns the {Scrivito::BasicObj Obj}'s path as a String.
     # @api public
     def path
       read_attribute('_path')
     end
 
-    # returns the {BasicObj Obj}'s name, i.e. the last component of the path.
+    # returns the {Scrivito::BasicObj Obj}'s name, i.e. the last component of the path.
     # @api public
     def name
       if child_path?
@@ -361,12 +383,14 @@ module Scrivito
       end
     end
 
-    # Returns the root {BasicObj Obj}, i.e. the Obj with the path "/"
+    # Returns the root {Scrivito::BasicObj Obj}, i.e. the Obj with the path "/"
     # @return [Obj]
     # @api public
     def self.root
-      BasicObj.find_by_path("/") or raise ResourceNotFound,
-          "Obj.root not found: There is no Obj with path '/'."
+      BasicObj.find_by_path('/') or raise ResourceNotFound,
+          '"Obj.root" not found: There is no "Obj" with path "/". '\
+          'Maybe you forgot the migration when setting up your Scrivito application? '\
+          'Try "rake scrivito:migrate" and "rake scrivito:migrate:publish".'
     end
 
     # Returns the homepage obj. This can be overwritten in your application's +Obj+.
@@ -427,18 +451,27 @@ module Scrivito
       (title || '').parameterize
     end
 
-    # This method determines the description that is shown in the changes list.
-    # It can be overriden by a custom value.
+    #
+    # This method determines the description that is shown in the UI
+    # and defaults to {Scrivito::BasicObj#display_title}. It can be overriden by a custom value.
+    #
     # @api public
+    #
     def description_for_editor
-      slug.presence || path
+      display_title
     end
 
-    # Returns the title of the content or the name.
-    # @return [String]
+    #
+    # Calculates appropriate title for an +Obj+.
+    #
     # @api public
+    #
+    # @return [String] {Scrivito::Binary#filename} if +Obj+ is +binary+ and has a +filename+.
+    # @return [String] {Scrivito::BasicObj#title} if +Obj+ has a non-empty +title+.
+    # @return [String] a placeholder +<untitled MyClass>+ otherwise.
+    #
     def display_title
-      self.title || name
+      (binary_title || title).presence || "<untitled #{obj_class_name}>"
     end
 
     # @api public
@@ -446,9 +479,25 @@ module Scrivito
       read_attribute('title')
     end
 
-    # Returns true if image? or generic?
+    # @api public
+    # This method indicates if the Obj represents binary data. Binaries are
+    # handled differently in that they are not rendered using the normal layout
+    # but sent as a file. Examples of binary resources are Images or PDFs.
+    #
+    # By default every Obj that has an attribute +blob+ of the type +binary+ is
+    # considered a binary
+    #
+    # @note you can override this method to indicate that an Obj is binary,
+    #   if the default behavior doesn't fit your needs
+    #
+    # @return true if this Obj represents a binary resource.
     def binary?
-      [:image, :generic].include?(read_attribute('_obj_type').to_sym)
+      if obj_type = read_attribute('_obj_type')
+        [:image, :generic].include?(obj_type.to_sym)
+      else
+        blob_attribute = obj_class.attributes['blob']
+        blob_attribute && blob_attribute.type == 'binary'
+      end
     end
 
     # Returns true if this object is the root object.
@@ -468,9 +517,10 @@ module Scrivito
       toclist
     end
 
-    # @param objs_to_be_sorted [Array<BasicObj>] unsorted list of Objs
-    # @param list [Array<BasicObj>] list of Objs that defines the order
-    # @return [Array<BasicObj>] a sorted list of Objs. Any objs present in +objs_to_be_sorted+ but not in +list+ are appended at the end, sorted by +Obj#id+
+    # @param objs_to_be_sorted [Array<Scrivito::BasicObj>] unsorted list of Objs
+    # @param list [Array<Scrivito::BasicObj>] list of Objs that defines the order
+    # @return [Array<Scrivito::BasicObj>] a sorted list of Objs. Any objs present in
+    #   +objs_to_be_sorted+ but not in +list+ are appended at the end, sorted by +Obj#id+
     def self.sort_by_list(objs_to_be_sorted, list)
       (list & objs_to_be_sorted) + (objs_to_be_sorted - list).sort_by(&:id)
     end
@@ -482,6 +532,7 @@ module Scrivito
       _last_changed
       _path
       _permalink
+      _obj_class
       title
     ])
 
@@ -583,19 +634,8 @@ module Scrivito
       end
     end
 
-    # For a binary Obj, the content_type is equal to the content_type of its body (i.e. its data).
-    # For non-binary Objs, a the default content_type is "text/html".
-    # Override this method in subclasses to define a different content_type.
-    # Note that only Objs with content_type "text/html"
-    # will be rendered with layout and templates by the DefaultCmsController.
-    # @return [String]
-    # @api public
     def content_type
-      if binary?
-        body_content_type
-      else
-        "text/html"
-      end
+      raise "The method `content_type' and `mime_type' were removed. Please use `binary_content_type' instead"
     end
     alias mime_type content_type
 
@@ -619,42 +659,55 @@ module Scrivito
       end
     end
 
-    # for binary Objs body_length equals the file size
-    # for non-binary Objs body_length equals the number of characters in the body (main content)
     # @api public
-    def body_length
-      if binary?
-        blob = find_blob
-        blob ? blob.length : 0
-      else
-        (body || "").length
-      end
+    # This method is intended for Objs that represent binary resources like
+    # images or pdf documents. If this Obj represents a binary file, an instance
+    # of {Binary} is returned.
+    # The default implementation returns the attribute "blob" (if available and
+    # of type +binary+).
+    # @note You may override this method in your subclasses.
+    # @return [Binary, nil]
+    def binary
+      self[:blob] if self[:blob].is_a?(Binary)
     end
 
-    # returns an URL to retrieve the Obj's body for binary Objs.
-    # returns +nil+ for non-binary Objs.
-    # @return [String]
     # @api public
-    def body_data_url
-      if binary?
-        blob = find_blob
-        blob.url if blob
-      end
+    # This method returns the length in bytes of the binary of this obj
+    # @return [Fixnum] If no binary is set it will return 0
+    def binary_length
+      binary.try(:content_length) || 0
     end
 
-    # returns the content type of the Obj's body for binary Objs.
-    # returns +nil+ for non-binary Objs.
-    # @return [String]
     # @api public
+    # This method returns the content type of the binary of this obj if it is set.
+    # @return [String, nil]
+    def binary_content_type
+      binary.try(:content_type)
+    end
+
+    # @api public
+    # This method returns the url under which the content of this binary is
+    # available to the public if the binary is set.
+    #
+    # See {Binary#url} for details
+    # @return [String, nil]
+    def binary_url
+      binary.try(:url)
+    end
+
+    def body_length
+      raise %(
+        The method `body_length' was removed. Please use
+        `binary_length' or `body.length' instead
+      )
+    end
+
+    def body_data_url
+      raise "The method `body_data_url' was removed. Please use `binary_url' instead"
+    end
+
     def body_content_type
-      if binary?
-        blob = find_blob
-        if blob
-          blob.content_type
-        else
-          "application/octet-stream"
-        end
-      end
+      raise "The method `body_content_type' was removed. Please use `binary_content_type' instead"
     end
 
     def inspect
@@ -675,10 +728,21 @@ module Scrivito
       find_blob.try(:id)
     end
 
-    # Reverts changes of this object.
-    # After calling this method it's as if this object has been never modified in the current working copy.
-    # This method does not work with +new+ or +deleted+ objects.
-    # This method also does also not work for the +published+ workspace or the +rtc+ working copy.
+    #
+    # Reverts all changes made to the +Obj+ in the current workspace.
+    #
+    # @api public
+    #
+    # @note This method does not support +Obj+s, which are +new+.
+    #   Please use {Scrivito::BasicObj#destroy Obj#destroy} to destroy them.
+    # @note This method does not support +Obj+s, which are +deleted+.
+    #   Please use {Scrivito::BasicObj.restore Obj.restore} to restore them.
+    #
+    # @raise [ScrivitoError] If the current workspace is +published+.
+    # @raise [ScrivitoError] If the current workspace is the +rtc+ workspace.
+    # @raise [ScrivitoError] If the +Obj+ is +new+.
+    # @raise [ScrivitoError] If the +Obj+ is +deleted+.
+    #
     def revert
       assert_revertable
 
@@ -759,6 +823,12 @@ module Scrivito
       data_from_cms.to_h.except(*GENERATED_ATTRIBUTES)
     end
 
+    def parent_path
+      unless root?
+        path.gsub(/\/[^\/]+$/, '').presence || '/'
+      end
+    end
+
     private
 
     def cms_data_for_revision(revision)
@@ -785,18 +855,12 @@ module Scrivito
       end
     end
 
-    def parent_path
-      raise "parent_path called for root" if root?
-      path.gsub(/\/[^\/]+$/, "").presence || "/"
-    end
-
     def as_date(value)
       DateAttribute.parse(value) unless value.nil?
     end
 
     def find_blob
-      blob_spec = read_attribute('blob')
-      Blob.find(blob_spec["id"]) if blob_spec
+      read_attribute('blob')
     end
 
     def workspace
@@ -823,13 +887,39 @@ module Scrivito
 
     def assert_revertable
       workspace.assert_revertable
-      raise "revert not supported for binary objs" if binary?
       if modification == Modification::NEW || modification == Modification::DELETED
         raise ScrivitoError, "cannot revert changes, since obj is #{modification}."
       end
     end
 
+    def binary_title
+      binary.filename if binary? && binary
+    end
+
     class << self
+
+      def assert_not_basic_obj(method_name)
+        if self == Scrivito::BasicObj
+          raise ScrivitoError, "Can not call #{method_name} on Scrivito::BasicObj."
+            + " Only call it on Obj or subclasses of Obj"
+        end
+      end
+
+      def assert_has_obj_class(method_name)
+        unless Workspace.current.obj_classes[name].present?
+          raise ScrivitoError, "#{name} has no corresponding ObjClass."
+            + " Please use Obj.#{method_name} instead."
+        end
+      end
+
+      #
+      # Restores a previously deleted +Obj+.
+      #
+      # @api public
+      #
+      # @raise [ScrivitoError] If the current workspace is +published+.
+      # @raise [ScrivitoError] If the current workspace is the +rtc+ workspace.
+      #
       def restore(obj_id)
         Workspace.current.assert_revertable
         base_revision_path = "revisions/#{Workspace.current.base_revision_id}/objs/#{obj_id}"