lotus-view 0.1.0 → 0.2.0

data/lib/lotus/view/configuration.rb

@@ -0,0 +1,298 @@
+require 'set'
+require 'lotus/utils/class'
+require 'lotus/utils/kernel'
+require 'lotus/utils/string'
+require 'lotus/utils/load_paths'
+require 'lotus/view/rendering/layout_finder'
+
+module Lotus
+  module View
+    # Configuration for the framework, controllers and actions.
+    #
+    # Lotus::Controller has its own global configuration that can be manipulated
+    # via `Lotus::View.configure`.
+    #
+    # Every time that `Lotus::View` and `Lotus::Layout` are included, that
+    # global configuration is being copied to the recipient. The copy will
+    # inherit all the settings from the original, but all the subsequent changes
+    # aren't reflected from the parent to the children, and viceversa.
+    #
+    # This architecture allows to have a global configuration that capture the
+    # most common cases for an application, and let views and layouts
+    # layouts to specify exceptions.
+    #
+    # @since 0.2.0
+    class Configuration
+      # Default root
+      #
+      # @since 0.2.0
+      # @api private
+      DEFAULT_ROOT = '.'.freeze
+
+      attr_reader :load_paths
+      attr_reader :views
+      attr_reader :layouts
+
+      # Return the original configuration of the framework instance associated
+      # with the given class.
+      #
+      # When multiple instances of Lotus::View are used in the same application,
+      # we want to make sure that a controller or an action will  receive the
+      # expected configuration.
+      #
+      # @param base [Class] a view or a layout
+      #
+      # @return [Lotus::Controller::Configuration] the configuration associated
+      #   to the given class.
+      #
+      # @since 0.2.0
+      # @api private
+      #
+      # @example Direct usage of the framework
+      #   require 'lotus/view'
+      #
+      #   class Show
+      #     include Lotus::View
+      #   end
+      #
+      #   Lotus::View::Configuration.for(Show)
+      #     # => will return from Lotus::View
+      #
+      # @example Multiple instances of the framework
+      #   require 'lotus/view'
+      #
+      #   module MyApp
+      #     View = Lotus::View.duplicate(self)
+      #
+      #     module Views::Dashboard
+      #       class Index
+      #         include MyApp::View
+      #       end
+      #     end
+      #   end
+      #
+      #   class Show
+      #     include Lotus::Action
+      #   end
+      #
+      #   Lotus::View::Configuration.for(Show)
+      #     # => will return from Lotus::View
+      #
+      #   Lotus::View::Configuration.for(MyApp::Views::Dashboard::Index)
+      #     # => will return from MyApp::View
+      def self.for(base)
+        # TODO this implementation is similar to Lotus::Controller::Configuration consider to extract it into Lotus::Utils
+        namespace = Utils::String.new(base).namespace
+        framework = Utils::Class.load!("(#{namespace}|Lotus)::View")
+        framework.configuration
+      end
+
+      # Initialize a configuration instance
+      #
+      # @return [Lotus::View::Configuration] a new configuration's instance
+      #
+      # @since 0.2.0
+      def initialize
+        @namespace = Object
+        reset!
+      end
+
+      # Set the Ruby namespace where to lookup for views.
+      #
+      # When multiple instances of the framework are used, we want to make sure
+      # that if a `MyApp` wants a `Dashboard::Index` view, we are loading the
+      # right one.
+      #
+      # If not set, this value defaults to `Object`.
+      #
+      # This is part of a DSL, for this reason when this method is called with
+      # an argument, it will set the corresponding instance variable. When
+      # called without, it will return the already set value, or the default.
+      #
+      # @overload namespace(value)
+      #   Sets the given value
+      #   @param value [Class, Module, String] a valid Ruby namespace identifier
+      #
+      # @overload namespace
+      #   Gets the value
+      #   @return [Class, Module, String]
+      #
+      # @since 0.2.0
+      #
+      # @example Getting the value
+      #   require 'lotus/view'
+      #
+      #   Lotus::View.configuration.namespace # => Object
+      #
+      # @example Setting the value
+      #   require 'lotus/view'
+      #
+      #   Lotus::View.configure do
+      #     namespace 'MyApp::Views'
+      #   end
+      def namespace(value = nil)
+        if value
+          @namespace = value
+        else
+          @namespace
+        end
+      end
+
+      # Set the root path where to search for templates
+      #
+      # If not set, this value defaults to the current directory.
+      #
+      # This is part of a DSL, for this reason when this method is called with
+      # an argument, it will set the corresponding instance variable. When
+      # called without, it will return the already set value, or the default.
+      #
+      # @overload root(value)
+      #   Sets the given value
+      #   @param value [String,Pathname,#to_pathname] an object that can be
+      #     coerced to Pathname
+      #   @raise [Errno::ENOENT] if the given path doesn't exist
+      #
+      # @overload root
+      #   Gets the value
+      #   @return [Pathname]
+      #
+      # @since 0.2.0
+      #
+      # @see Lotus::View::Dsl#root
+      # @see http://www.ruby-doc.org/stdlib-2.1.2/libdoc/pathname/rdoc/Pathname.html
+      # @see http://rdoc.info/gems/lotus-utils/Lotus/Utils/Kernel#Pathname-class_method
+      #
+      # @example Getting the value
+      #   require 'lotus/view'
+      #
+      #   Lotus::View.configuration.root # => #<Pathname:.>
+      #
+      # @example Setting the value
+      #   require 'lotus/view'
+      #
+      #   Lotus::View.configure do
+      #     root '/path/to/templates'
+      #   end
+      #
+      #   Lotus::View.configuration.root # => #<Pathname:/path/to/templates>
+      def root(value = nil)
+        if value
+          @root = Utils::Kernel.Pathname(value).realpath
+        else
+          @root
+        end
+      end
+
+      # Set the global layout
+      #
+      # If not set, this value defaults to `nil`, while at the rendering time
+      # it will use `Lotus::View::Rendering::NullLayout`.
+      #
+      # This is part of a DSL, for this reason when this method is called with
+      # an argument, it will set the corresponding instance variable. When
+      # called without, it will return the already set value, or the default.
+      #
+      # @overload layout(value)
+      #   Sets the given value
+      #   @param value [Symbol] the name of the layout
+      #
+      # @overload layout
+      #   Gets the value
+      #   @return [Class]
+      #
+      # @since 0.2.0
+      #
+      # @see Lotus::View::Dsl#layout
+      #
+      # @example Getting the value
+      #   require 'lotus/view'
+      #
+      #   Lotus::View.configuration.layout # => nil
+      #
+      # @example Setting the value
+      #   require 'lotus/view'
+      #
+      #   Lotus::View.configure do
+      #     layout :application
+      #   end
+      #
+      #   Lotus::View.configuration.layout # => ApplicationLayout
+      #
+      # @example Setting the value in a namespaced app
+      #   require 'lotus/view'
+      #
+      #   module MyApp
+      #     View = Lotus::View.duplicate(self) do
+      #       layout :application
+      #     end
+      #   end
+      #
+      #   MyApp::View.configuration.layout # => MyApp::ApplicationLayout
+      def layout(value = nil)
+        if value
+          @layout = value
+        else
+          Rendering::LayoutFinder.find(@layout, @namespace)
+        end
+      end
+
+      # Add a view to the registry
+      #
+      # @since 0.2.0
+      # @api private
+      def add_view(view)
+        @views.add(view)
+      end
+
+      # Add a layout to the registry
+      #
+      # @since 0.2.0
+      # @api private
+      def add_layout(layout)
+        @layouts.add(layout)
+      end
+
+      # Duplicate by copying the settings in a new instance.
+      #
+      # @return [Lotus::View::Configuration] a copy of the configuration
+      #
+      # @since 0.2.0
+      # @api private
+      def duplicate
+        Configuration.new.tap do |c|
+          c.namespace  = namespace
+          c.root       = root
+          c.layout     = @layout # lazy loading of the class
+          c.load_paths = load_paths.dup
+        end
+      end
+
+      # Load the configuration for the current framework
+      #
+      # @since 0.2.0
+      # @api private
+      def load!
+        views.each   {|v| v.__send__(:load!) }
+        layouts.each {|l| l.__send__(:load!) }
+      end
+
+      # Reset all the values to the defaults
+      #
+      # @since 0.2.0
+      # @api private
+      def reset!
+        root(DEFAULT_ROOT)
+
+        @views      = Set.new
+        @layouts    = Set.new
+        @load_paths = Utils::LoadPaths.new(root)
+        @layout     = nil
+      end
+
+      alias_method :unload!, :reset!
+
+      protected
+      attr_writer :namespace, :root, :load_paths, :layout
+    end
+  end
+end

data/lib/lotus/view/dsl.rb

@@ -1,4 +1,4 @@
-require 'lotus/utils/string'
+require 'lotus/view/rendering/template_name'
 require 'lotus/view/rendering/layout_finder'
 
 module Lotus
@@ -27,8 +27,8 @@ module Lotus
       #     end
       #   end
       #
-      #   Lotus::View.root    # => 'app/templates'
-      #   Articles::Show.root # => 'app/templates'
+      #   Lotus::View.configuration.root # => 'app/templates'
+      #   Articles::Show.root            # => 'app/templates'
       #
       # @example Custom root
       #   require 'lotus/view'
@@ -40,13 +40,13 @@ module Lotus
       #     end
       #   end
       #
-      #   Lotus::View.root    # => 'app/templates'
-      #   Articles::Show.root # => 'path/to/articles/templates'
+      #   Lotus::View.configuration.root # => 'app/templates'
+      #   Articles::Show.root            # => 'path/to/articles/templates'
       def root(value = nil)
         if value
-          @@root = Pathname.new value
+          configuration.root(value)
         else
-          @@root ||= Lotus::View.root
+          configuration.root
         end
       end
 
@@ -124,11 +124,90 @@ module Lotus
       #
       #   Articles::Show.template     # => 'articles/single_article'
       #   Articles::JsonShow.template # => 'articles/single_article'
+      #
+      # @example With namespace
+      #   require 'lotus/view'
+      #
+      #   module Furnitures
+      #     View = Lotus::View.generate(self)
+      #
+      #     class Standalone
+      #       include Furnitures::View
+      #     end
+      #
+      #     module Catalog
+      #       class Index
+      #         Furnitures::View
+      #       end
+      #     end
+      #   end
+      #
+      #   Furnitures::Standalone.template     # => 'standalone'
+      #   Furnitures::Catalog::Index.template # => 'catalog/index'
+      #
+      # @example With nested namespace
+      #   require 'lotus/view'
+      #
+      #   module Frontend
+      #     View = Lotus::View.generate(self)
+      #
+      #     class StandaloneView
+      #       include Frontend::View
+      #     end
+      #
+      #     module Views
+      #       class Standalone
+      #         include Frontend::View
+      #       end
+      #
+      #       module Sessions
+      #         class New
+      #           include Frontend::View
+      #         end
+      #       end
+      #     end
+      #   end
+      #
+      #   Frontend::StandaloneView.template       # => 'standalone_view'
+      #   Frontend::Views::Standalone.template    # => 'standalone'
+      #   Frontend::Views::Sessions::New.template # => 'sessions/new'
+      #
+      # @example With deeply nested namespace
+      #   require 'lotus/view'
+      #
+      #   module Bookshelf
+      #     module Web
+      #       View = Lotus::View.generate(self)
+      #
+      #       module Views
+      #         module Books
+      #           class Show
+      #             include Bookshelf::Web::View
+      #           end
+      #         end
+      #       end
+      #     end
+      #
+      #     module Api
+      #       View = Lotus::View.generate(self)
+      #
+      #       module Views
+      #         module Books
+      #           class Show
+      #             include Bookshelf::Api::View
+      #           end
+      #         end
+      #       end
+      #     end
+      #   end
+      #
+      #   Bookshelf::Web::Views::Books::Index.template # => 'books/index'
+      #   Bookshelf::Api::Views::Books::Index.template # => 'books/index'
       def template(value = nil)
         if value
           @@template = value
         else
-          @@template ||= Utils::String.new(name).underscore
+          @@template ||= Rendering::TemplateName.new(name, configuration.namespace).to_s
         end
       end
 
@@ -219,7 +298,7 @@ module Lotus
         if value
           @layout = value
         else
-          @layout
+          @layout ||= configuration.layout
         end
       end
 
@@ -239,7 +318,7 @@ module Lotus
           v.format.freeze
           v.template.freeze
           v.layout(Rendering::LayoutFinder.new(v).find)
-          v.layout.freeze
+          v.layout#.freeze
         end
       end
     end

data/lib/lotus/view/inheritable.rb

@@ -42,6 +42,10 @@ module Lotus
         views.freeze
       end
 
+      # Registered views
+      #
+      # @api private
+      # @since 0.1.0
       def views
         @@views ||= [ self ] + subclasses.to_a
       end

data/lib/lotus/view/rendering/layout_finder.rb

@@ -1,4 +1,6 @@
 require 'lotus/utils/string'
+require 'lotus/utils/class'
+require 'lotus/view/rendering/null_layout'
 
 module Lotus
   module View
@@ -21,6 +23,8 @@ module Lotus
         # @param layout [Symbol,String,NilClass] layout name or nil if you want
         #   to fallback to the framework defaults (see `Lotus::View.layout`).
         #
+        # @param namespace [Class,Module] a Ruby namespace where to lookup
+        #
         # @return [Lotus::Layout] the layout for the given name or
         #   `Lotus::View.layout`
         #
@@ -33,20 +37,40 @@ module Lotus
         #   Lotus::View::Rendering::LayoutFinder.find(:article) # =>
         #     ArticleLayout
         #
+        # @example With a class
+        #   require 'lotus/view'
+        #
+        #   Lotus::View::Rendering::LayoutFinder.find(ArticleLayout) # =>
+        #     ArticleLayout
+        #
+        # @example With namespace
+        #   require 'lotus/view'
+        #
+        #   Lotus::View::Rendering::LayoutFinder.find(:application, CardDeck) # =>
+        #     CardDeck::ApplicationLayout
+        #
         # @example With nil
         #   require 'lotus/view'
         #
-        #   Lotus::View.layout # => :application
         #   Lotus::View::Rendering::LayoutFinder.find(nil) # =>
-        #     ApplicationLayout
-        def self.find(layout)
+        #     Lotus::View::Rendering::NullLayout
+        #
+        # @example With unknown layout
+        #   require 'lotus/view'
+        #
+        #   Lotus::View::Rendering::LayoutFinder.find(:unknown) # =>
+        #     Lotus::View::Rendering::NullLayout
+        #
+        def self.find(layout, namespace = Object)
           case layout
           when Symbol, String
+            # TODO Move this low level logic into a Lotus::Utils solution
             class_name = "#{ Utils::String.new(layout).classify }#{ SUFFIX }"
-            Object.const_get(class_name)
-          when nil
-            Lotus::View.layout
-          end
+            namespace  = Utils::Class.load!(namespace)
+            namespace.const_get(class_name)
+          when Class
+            layout
+          end || NullLayout
         end
 
         # Initialize the finder

data/lib/lotus/view/rendering/layout_scope.rb

@@ -128,8 +128,8 @@ module Lotus
         def _options(options)
           options.dup.tap do |opts|
             opts.merge!(format: format)
-            opts[:locals] ||= {}
-            opts[:locals].merge!(locals)
+            opts[:locals] = locals
+            opts[:locals].merge!(options.fetch(:locals){ Hash[] })
           end
         end
       end

data/lib/lotus/view/rendering/registry.rb

@@ -78,7 +78,6 @@ module Lotus
         #
         # @param context [Hash] the rendering context
         # @option context [Symbol] :format the requested format
-        # @param locals [Hash] the set of available objects
         #
         # @return [Lotus::View] the view associated with the given context
         #

data/lib/lotus/view/rendering/scope.rb

@@ -33,9 +33,9 @@ module Lotus
         end
 
         protected
-        def method_missing(m)
+        def method_missing(m, *args)
           if @view.respond_to?(m)
-            @view.__send__ m
+            @view.__send__ m, *args
           elsif @locals.key?(m)
             @locals[m]
           else

data/lib/lotus/view/rendering/template_name.rb

@@ -0,0 +1,37 @@
+require 'lotus/utils/string'
+
+module Lotus
+  module View
+    module Rendering
+      # @since 0.2.0
+      class TemplateName
+        NAMESPACE_SEPARATOR = '::'.freeze
+
+        def initialize(name, namespace)
+          @name = name
+          compile!(namespace)
+        end
+
+        def to_s
+          @name
+        end
+
+        private
+        def compile!(namespace)
+          tokens(namespace) {|token| replace!(token) }
+          @name = Utils::String.new(@name).underscore
+        end
+
+        def tokens(namespace)
+          namespace.to_s.split(NAMESPACE_SEPARATOR).each do |token|
+            yield token
+          end
+        end
+
+        def replace!(token)
+          @name.gsub!(%r{\A#{ token }#{ NAMESPACE_SEPARATOR }}, '')
+        end
+      end
+    end
+  end
+end

data/lib/lotus/view/rendering/templates_finder.rb

@@ -10,8 +10,23 @@ module Lotus
       #
       # @see View::Template
       class TemplatesFinder
-        FORMAT  = '*'.freeze
-        ENGINES = '*'.freeze
+        # Default format
+        #
+        # @api private
+        # @since 0.1.0
+        FORMAT    = '*'.freeze
+
+        # Default template engines
+        #
+        # @api private
+        # @since 0.1.0
+        ENGINES   = '*'.freeze
+
+        # Recursive pattern
+        #
+        # @api private
+        # @since 0.2.0
+        RECURSIVE = '**'.freeze
 
         # Initialize a finder
         #
@@ -24,8 +39,8 @@ module Lotus
         end
 
         # Find all the associated templates to the view.
-        # It looks for templates under the root path of the view, that are
-        # matching the template name
+        # It recursively looks for templates under the root path of the view,
+        # that are matching the template name
         #
         # @return [Array<Lotus::View::Template>] the templates
         #
@@ -54,28 +69,44 @@ module Lotus
         #   Lotus::View::Rendering::TemplatesFinder.new(Articles::Show).find
         #     # => [#<Lotus::View::Template:0x007f8a0a86a970 ... @file="/path/to/templates/articles/show.html.erb">]
         def find
-          Dir.glob( "#{ [root, template_name].join(separator) }.#{ format }.#{ engines }" ).map do |template|
+          Dir.glob( "#{ [root, recursive, template_name].join(separator) }.#{ format }.#{ engines }" ).map do |template|
             View::Template.new template
           end
         end
 
         protected
+        # @api private
+        # @since 0.1.0
         def template_name
           @view.template
         end
 
+        # @api private
+        # @since 0.1.0
         def root
           @view.root
         end
 
+        # @api private
+        # @since 0.2.0
+        def recursive
+          RECURSIVE
+        end
+
+        # @api private
+        # @since 0.1.0
         def separator
           ::File::SEPARATOR
         end
 
+        # @api private
+        # @since 0.1.0
         def format
           FORMAT
         end
 
+        # @api private
+        # @since 0.1.0
         def engines
           ENGINES
         end

data/lib/lotus/view/version.rb

@@ -3,6 +3,6 @@ module Lotus
     # Defines the version
     #
     # @since 0.1.0
-    VERSION = '0.1.0'.freeze
+    VERSION = '0.2.0'.freeze
   end
 end