require "scrivito/errors"

# @api public
module Scrivito
  #
  # Configures the Scrivito SDK.
  # The +tenant+ and +api_key+ configuration keys _must_ be provided.
  #
  # @example
  #   Scrivito.configure do |config|
  #     config.tenant  = 'my-tenant-name'
  #     config.api_key = 'secret'
  #   end
  #
  # @api public
  #
  def self.configure
    yield Configuration
  end

  #
  # Configures which classes Scrivito regards as CMS models.
  #
  # @api public
  #
  # 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.) 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.).
  #
  # 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, widget and obj models:
  #
  #   app/models/my_page.rb
  #   app/models/my_widget.rb
  #   app/models/my_obj.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_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
  #
  # 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,
  # widget and obj models in an engine:
  #
  #   /../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_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_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
  #
  # 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 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"
  #   end
  #
  # @example Register pages and widgets with unusual names:
  #   Scrivito.models.define do
  #     page "MyCrazyPageModel"
  #     page "MyOtherCrazyPageModel1", "MyOtherCrazyPageModel2"
  #
  #     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"
  #   #=> "MyOtherPage"
  #   # ...
  #
  # @example Iterate over the available widgets:
  #   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
end

require 'scrivito/sdk_engine' if defined?(Rails)