scrivito_sdk.rb in scrivito_sdk-1.2.0.rc1

- old
+ new

@@ -17,83 +17,100 @@
   def self.configure
     yield Configuration
   end
 
   #
-  # Configures which models Scrivito regards as pages and widgets.
+  # Configures which classes Scrivito regards as CMS models.
   #
   # @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. These models can be defined in
-  # the Rails application itself or in 3rd-party gems.
+  # In order to provide access to CMS class details, Scrivito needs to know which CMS model classes
+  # are available. These models can be defined in the Rails application itself or in 3rd-party gems.
   #
-  # 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 assumes that all the classes descending from {Scrivito::BasicObj}, whose class names
+  # end with +"Page"+ are pages (e.g. +MyPage+, +HomePage+, +BlogPostPage+ etc.) and all the classes
+  # descending from {Scrivito::BasicWidget}, whose class names end with +"Widget"+ are widgets (e.g.
+  # +TextWidget+, +ImageWidget+ etc.).
+  # It also assumes that all the classes descending from {Scrivito::BasicObj}, regardless of the
+  # class names, are CMS object models (e.g. all pages, but also +Obj+, +Image+, +Download+ etc.).
   #
-  # Scrivito recursively scans for such models in all directories from
+  # The loaded pages can be inspected with {Scrivito::ModelLibrary#pages Scrivito.models.pages},
+  # which will return a {Scrivito::ClassCollection} containing the available pages and the loaded
+  # widgets can be inspected with {Scrivito::ModelLibrary#widgets Scrivito.models.widgets}, which
+  # will return a {Scrivito::ClassCollection} containing the available widgets.
+  # All available CMS object models can be inspected with
+  # {Scrivito::ModelLibrary#objs Scrivito.models.objs}.
+  # The {Scrivito::ModelLibrary#pages Scrivito.models.pages} will also include the +Page+ model, if
+  # it is defined in +page.rb+, and {Scrivito::ModelLibrary#objs Scrivito.models.objs} will include
+  # the +Obj+ model.
+  #
+  # Scrivito recursively scans for CMS models in all directories from
   # {Scrivito::ModelLibrary#paths Scrivito.models.paths}, which is an array of strings.
   # 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:
+  # for models. It will, for example, find the following page, widget and obj models:
   #
-  # +app/models/my_page.rb+
+  #   app/models/my_page.rb
+  #   app/models/my_widget.rb
+  #   app/models/my_obj.rb
   #
-  # +app/models/my_widget.rb+
+  #   app/models/my_namespace/my_other_page.rb
+  #   app/models/my_namespace/my_other_widget.rb
+  #   app/models/my_namespace/my_other_obj.rb
   #
-  # +app/models/my_namespace/my_other_page.rb+
+  #   app/models/my_namespace/my_other_namespace/my_other_special_page.rb
+  #   app/models/my_namespace/my_other_namespace/my_other_special_widget.rb
+  #   app/models/my_namespace/my_other_namespace/my_other_special_obj.rb
   #
-  # +app/models/my_namespace/my_other_widget.rb+
-  #
-  # +app/models/my_namespace/my_other_namespace/my_other_special_page.rb+
-  #
-  # +app/models/my_namespace/my_other_namespace/my_other_special_widget.rb+
-  #
   # 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:
+  # autoload paths of Rails (which is the default). For example, it will find the following page,
+  # widget and obj models in an engine:
   #
-  # +/../some_engine/app/models/my_page.rb+
+  #   /../some_engine/app/models/my_page.rb
+  #   /../some_engine/app/models/my_widget.rb
+  #   /../some_engine/app/models/my_obj.rb
   #
-  # +/../some_engine/app/models/my_widget.rb+
+  #   /../some_engine/app/models/my_namespace/my_other_page.rb
+  #   /../some_engine/app/models/my_namespace/my_other_widget.rb
+  #   /../some_engine/app/models/my_namespace/my_other_obj.rb
   #
-  # +/../some_engine/app/models/my_namespace/my_other_page.rb+
+  #   /../some_engine/app/models/my_namespace/my_other_namespace/my_other_special_page.rb
+  #   /../some_engine/app/models/my_namespace/my_other_namespace/my_other_special_widget.rb
+  #   /../some_engine/app/models/my_namespace/my_other_namespace/my_other_special_obj.rb
   #
-  # +/../some_engine/app/models/my_namespace/my_other_widget.rb+
-  #
-  # +/../some_engine/app/models/my_namespace/my_other_namespace/my_other_special_page.rb+
-  #
-  # +/../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
   # 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 the available pages.
-  # The loaded widgets can be inspected with {Scrivito::ModelLibrary#widgets Scrivito.models.widgets},
-  # which will return a {Scrivito::ClassCollection} containing the available widgets.
-  #
   # 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:
   #   Scrivito.models.define do
-  #     paths << Rails.root + 'lib/special_models'
+  #     paths << Rails.root + "lib/special_models"
   #   end
   #
   # @example Register pages and widgets with unusual names:
   #   Scrivito.models.define do
-  #     page 'MyCrazyPageModel'
-  #     page 'MyOtherCrazyPageModel1', 'MyOtherCrazyPageModel2'
+  #     page "MyCrazyPageModel"
+  #     page "MyOtherCrazyPageModel1", "MyOtherCrazyPageModel2"
   #
-  #     widget 'MyCrazyWidgetModel'
-  #     widget 'MyOtherCrazyWidgetModel1', 'MyOtherCrazyWidgetModel2'
+  #     widget "MyCrazyWidgetModel"
+  #     widget "MyOtherCrazyWidgetModel1", "MyOtherCrazyWidgetModel2"
   #   end
   #
+  # @example Register CMS model classes, whose files Scrivito would _not_ find in {Scrivito::ModelLibrary#paths paths}:
+  #   class MyPage < Obj; end
+  #   class MyWidget < Widget; end
+  #   class MyObj < Obj; end
+  #
+  #   Scrivito.models.define do
+  #     page "MyPage"
+  #     widget "MyWidget"
+  #     obj "MyObj"
+  #   end
+  #
   # @example Iterate over the available pages:
   #   Scrivito.models.pages.each do |page_class|
   #     puts page_class.name
   #   end
   #   #=> "MyPage"
@@ -104,9 +121,19 @@
   #   Scrivito.models.widgets.each do |widget_class|
   #     puts widget_class.name
   #   end
   #   #=> "MyWidget"
   #   #=> "MyOtherWidget"
+  #   # ...
+  #
+  # @example Iterate over the available CMS object models:
+  #   Scrivito.models.objs.each do |obj_class|
+  #     puts obj_class.name
+  #   end
+  #   #=> "MyPage"
+  #   #=> "MyOtherPage"
+  #   #=> "MyObj"
+  #   #=> "MyOtherObj"
   #   # ...
   #
   def self.models
     @models ||= ModelLibrary.new
   end