lotus-view 0.0.0 → 0.1.0

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

@@ -0,0 +1,85 @@
+require 'lotus/view/template'
+
+module Lotus
+  module View
+    module Rendering
+      # Find templates for a view
+      #
+      # @api private
+      # @since 0.1.0
+      #
+      # @see View::Template
+      class TemplatesFinder
+        FORMAT  = '*'.freeze
+        ENGINES = '*'.freeze
+
+        # Initialize a finder
+        #
+        # @param view [Class] the view
+        #
+        # @api private
+        # @since 0.1.0
+        def initialize(view)
+          @view = view
+        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
+        #
+        # @return [Array<Lotus::View::Template>] the templates
+        #
+        # @api private
+        # @since 0.1.0
+        #
+        # @see Lotus::View::Dsl#root
+        # @see Lotus::View::Dsl#template
+        #
+        # @example
+        #   require 'lotus/view'
+        #
+        #   module Articles
+        #     class Show
+        #       include Lotus::View
+        #     end
+        #   end
+        #
+        #   Articles::Show.root     # => "/path/to/templates"
+        #   Articles::Show.template # => "articles/show"
+        #
+        #   # This view has a template:
+        #   #
+        #   #   "/path/to/templates/articles/show.html.erb"
+        #
+        #   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|
+            View::Template.new template
+          end
+        end
+
+        protected
+        def template_name
+          @view.template
+        end
+
+        def root
+          @view.root
+        end
+
+        def separator
+          ::File::SEPARATOR
+        end
+
+        def format
+          FORMAT
+        end
+
+        def engines
+          ENGINES
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,37 @@
+module Lotus
+  module View
+    module Rendering
+      # Find a view
+      #
+      # @api private
+      # @since 0.1.0
+      #
+      # @see Lotus::View::Rendering::Registry
+      class ViewFinder
+        # Initialize a finder
+        #
+        # @param view [Class] the superclass view
+        #
+        # @api private
+        # @since 0.1.0
+        def initialize(view)
+          @view = view
+        end
+
+        # Find a view for the given template.
+        # It looks up for the current view and its subclasses.
+        #
+        # @param template [Lotus::View::Template] a template to be associated
+        #   to a view
+        #
+        # @return [Class] a view associated with the given template
+        #
+        # @api private
+        # @since 0.1.0
+        def find(template)
+          @view.subclasses.find {|v| v.format == template.format } || @view
+        end
+      end
+    end
+  end
+end

data/lib/lotus/view/rendering.rb

@@ -0,0 +1,265 @@
+require 'lotus/view/rendering/registry'
+require 'lotus/view/rendering/scope'
+
+module Lotus
+  module View
+    # Rendering methods
+    #
+    # @since 0.1.0
+    #
+    # @see Lotus::View::Rendering::InstanceMethods
+    module Rendering
+      def self.extended(base)
+        base.class_eval do
+          include InstanceMethods
+        end
+      end
+
+      module InstanceMethods
+        # Initialize a view
+        #
+        # @param template [Lotus::View::Template] the template to render
+        # @param locals [Hash] a set of objects available during the rendering
+        #   process.
+        #
+        # @since 0.1.0
+        #
+        # @see Lotus::View::Template
+        #
+        # @example
+        #   require 'lotus/view'
+        #
+        #   class IndexView
+        #     include Lotus::View
+        #   end
+        #
+        #   template = Lotus::View::Template.new('index.html.erb')
+        #   view     = IndexView.new(template, {article: article})
+        def initialize(template, locals)
+          @template = template
+          @locals   = locals
+          @scope    = Scope.new(self, @locals)
+        end
+
+        # Render the template by bounding the local scope.
+        # If it uses a layout, it renders the template first and then the
+        # control passes to the layout.
+        #
+        # Override this method for custom rendering policies.
+        # For instance, when a serializer is used and there isn't the need of
+        # a template.
+        #
+        # @return [String] the output of the rendering process
+        #
+        # @raise [Lotus::View::MissingTemplateError] if the template is nil
+        #
+        # @since 0.1.0
+        #
+        # @see Lotus::View::Layout
+        #
+        # @example with template
+        #   require 'lotus/view'
+        #
+        #   class IndexView
+        #     include Lotus::View
+        #   end
+        #
+        #   template = Lotus::View::Template.new('index.html.erb')
+        #   view     = IndexView.new(template, {article: article})
+        #
+        #   view.render # => <h1>Introducing Lotus::view</h1> ...
+        #
+        # @example with template and layout
+        #   require 'lotus/view'
+        #
+        #   class ApplicationLayout
+        #     include Lotus::View::Layout
+        #   end
+        #
+        #   class IndexView
+        #     include Lotus::View
+        #     layout :application
+        #   end
+        #
+        #   template = Lotus::View::Template.new('index.html.erb')
+        #   view     = IndexView.new(template, {article: article})
+        #
+        #   view.render # => <html> ... <h1>Introducing Lotus::view</h1> ...
+        #
+        # @example with custom rendering
+        #   require 'lotus/view'
+        #
+        #   class IndexView
+        #     include Lotus::View
+        #
+        #     def render
+        #       ArticleSerializer.new(article).render
+        #     end
+        #   end
+        #
+        #   view = IndexView.new(nil, {article: article})
+        #
+        #   view.render # => {title: ...}
+        def render
+          layout.render
+        end
+
+        protected
+        # The output of the template rendering process.
+        #
+        # @return [String] the rendering output
+        #
+        # @raise [Lotus::View::MissingTemplateError] if the template is nil
+        #
+        # @api private
+        # @since 0.1.0
+        def rendered
+          template.render @scope
+        end
+
+        # The layout.
+        #
+        # @return [Class, Lotus::View::Rendering::NullLayout]
+        #
+        # @see Lotus::View::Layout
+        # @see Lotus::View.layout
+        # @see Lotus::View::Dsl#layout
+        #
+        # @api private
+        # @since 0.1.0
+        def layout
+          @layout ||= self.class.layout.new(@scope, rendered)
+        end
+
+        # The template.
+        #
+        # @return [Lotus::View::Template] the template
+        #
+        # @raise [Lotus::View::MissingTemplateError] if the template is nil
+        #
+        # @api private
+        # @since 0.1.0
+        def template
+          @template or raise MissingTemplateError.new(self.class.template, @scope.format)
+        end
+
+        # A set of objects available during the rendering process.
+        #
+        # @return [Hash]
+        #
+        # @see Lotus::View#initialize
+        #
+        # @api private
+        # @since 0.1.0
+        def locals
+          @locals
+        end
+
+        # Delegates missing methods to the scope.
+        #
+        # @see Lotus::View::Rendering::Scope
+        #
+        # @api private
+        # @since 0.1.0
+        #
+        # @example
+        #   require 'lotus/view'
+        #
+        #   class IndexView
+        #     include Lotus::View
+        #   end
+        #
+        #   template = Lotus::View::Template.new('index.html.erb')
+        #   view     = IndexView.new(template, {article: article})
+        #
+        #   view.article # => #<Article:0x007fb0bbd3b6e8>
+        def method_missing(m)
+          @scope.__send__ m
+        end
+      end
+
+      # Render the given context and locals with the appropriate template.
+      # If there are registered subclasses, it choose the right class, according
+      #   to the requested format.
+      #
+      # @param context [Hash] the context for the rendering process
+      # @option context [Symbol] :format the requested format
+      #
+      # @return [String] the output of the rendering process
+      #
+      # @raise [Lotus::View::MissingTemplateError] if it can't find a template
+      #   for the given context
+      #
+      # @raise [Lotus::View::MissingFormatError] if the given context doesn't
+      #   have the :format key
+      #
+      # @since 0.1.0
+      #
+      # @see Lotus::View#initialize
+      # @see Lotus::View#render
+      #
+      # @example
+      #   require 'lotus/view'
+      #
+      #   article = OpenStruct.new(title: 'Hello')
+      #
+      #   module Articles
+      #     class Show
+      #       include Lotus::View
+      #
+      #       def title
+      #         @title ||= article.title.upcase
+      #       end
+      #     end
+      #
+      #     class JsonShow < Show
+      #       format :json
+      #
+      #       def title
+      #         super.downcase
+      #       end
+      #     end
+      #   end
+      #
+      #   Lotus::View.root = '/path/to/templates'
+      #   Lotus::View.load!
+      #
+      #   Articles::Show.render(format: :html,  article: article)
+      #     # => renders `articles/show.html.erb`
+      #
+      #   Articles::Show.render(format: :json, article: article)
+      #     # => renders `articles/show.json.erb`
+      #
+      #   Articles::Show.render(format: :xml, article: article)
+      #     # => raises Lotus::View::MissingTemplateError
+      def render(context)
+        registry.resolve(context).render
+      end
+
+      protected
+
+      # Loading mechanism hook.
+      #
+      # @api private
+      # @since 0.1.0
+      #
+      # @see Lotus::View.load!
+      def load!
+        super
+        registry.freeze
+      end
+
+      private
+
+      # The registry that holds all the registered subclasses.
+      #
+      # @api private
+      # @since 0.1.0
+      #
+      # @see Lotus::View::Rendering::Registry
+      def registry
+        @@registry ||= Registry.new(self)
+      end
+    end
+  end
+end

data/lib/lotus/view/template.rb

@@ -0,0 +1,45 @@
+require 'tilt'
+
+module Lotus
+  module View
+    # A logic-less template.
+    #
+    # @since 0.1.0
+    class Template
+      def initialize(template)
+        @_template = Tilt.new(template)
+      end
+
+      # Returns the format that the template handles.
+      #
+      # @return [String] the format name
+      #
+      # @since 0.1.0
+      #
+      # @example
+      #   require 'lotus/view'
+      #
+      #   template = Lotus::View::Template.new('index.html.erb')
+      #   template.format # => 'html'
+      def format
+        @_template.basename.match(/(\.[^.]+)/).to_s.
+          gsub('.', ''). # TODO shame on me, this should be part of the regex above
+          to_sym
+      end
+
+      # Render the template within the context of the given scope.
+      #
+      # @param scope [Lotus::View::Scope] the rendering scope
+      #
+      # @return [String] the output of the rendering process
+      #
+      # @api private
+      # @since 0.1.0
+      #
+      # @see Lotus::View::Scope
+      def render(scope, &blk)
+        @_template.render(scope, {}, &blk)
+      end
+    end
+  end
+end

data/lib/lotus/view/version.rb

@@ -1,5 +1,8 @@
 module Lotus
   module View
-    VERSION = "0.0.0"
+    # Defines the version
+    #
+    # @since 0.1.0
+    VERSION = '0.1.0'.freeze
   end
 end

data/lib/lotus/view.rb

@@ -1,7 +1,185 @@
-require "lotus/view/version"
+require 'set'
+require 'pathname'
+require 'lotus/view/version'
+require 'lotus/view/inheritable'
+require 'lotus/view/rendering'
+require 'lotus/view/dsl'
+require 'lotus/layout'
+require 'lotus/presenter'
 
 module Lotus
+  # View
+  #
+  # @since 0.1.0
   module View
-    # Your code goes here...
+    # Missing template error
+    #
+    # This is raised at the runtime when Lotus::View cannot find a template for
+    # the requested format.
+    #
+    # We can't raise this error during the loading phase, because at that time
+    # we don't know if a view implements its own rendering policy.
+    # A view is allowed to override `#render`, and this scenario can make the
+    # presence of a template useless. One typical example is the usage of a
+    # serializer that returns the output string, without rendering a template.
+    #
+    # @since 0.1.0
+    class MissingTemplateError < ::StandardError
+      def initialize(template, format)
+        super("Can't find template '#{ template }' for '#{ format }' format.")
+      end
+    end
+
+    # Missing format error
+    #
+    # This is raised at the runtime when rendering context lacks of the :format
+    # key.
+    #
+    # @since 0.1.0
+    #
+    # @see Lotus::View::Rendering#render
+    class MissingFormatError < ::StandardError
+    end
+
+    # Register a view
+    #
+    # @api private
+    # @since 0.1.0
+    #
+    # @example
+    #   require 'lotus/view'
+    #
+    #   class IndexView
+    #     include Lotus::View
+    #   end
+    def self.included(base)
+      base.class_eval do
+        extend Inheritable.dup
+        extend Dsl.dup
+        extend Rendering.dup
+      end
+
+      views.add(base)
+    end
+
+    # Set the directory root where templates are located
+    #
+    # @param root [String] the root path
+    #
+    # @see Lotus::View.root
+    #
+    # @since 0.1.0
+    #
+    # @example
+    #   require 'lotus/view'
+    #
+    #   Lotus::View.root = '/path/to/templates'
+    def self.root=(root)
+      @root = Pathname.new(root) rescue nil
+    end
+
+    # Returns the directory root where templates are located.
+    # If not already set, it returns the current directory.
+    #
+    # @return [Pathname] the root path for templates
+    #
+    # @see Lotus::View.root=
+    #
+    # @since 0.1.0
+    #
+    # @example with already set value
+    #   require 'lotus/view'
+    #
+    #   Lotus::View.root = '/path/to/templates'
+    #   Lotus::View.root # => #<Pathname:/path/to/templates>
+    #
+    # @example with missing set value
+    #   require 'lotus/view'
+    #
+    #   Lotus::View.root # => #<Pathname:.>
+    def self.root
+      @root ||= begin
+        self.root = '.'
+        @root
+      end
+    end
+
+    # Sets the default layout for all the registered views.
+    #
+    # @param layout [Symbol] the layout name
+    #
+    # @since 0.1.0
+    #
+    # @see Lotus::View::Dsl#layout
+    # @see Lotus::View.load!
+    #
+    # @example
+    #   require 'lotus/view'
+    #
+    #   Lotus::View.layout = :application
+    #
+    #   class IndexView
+    #     include Lotus::View
+    #   end
+    #
+    #   Lotus::View.load!
+    #   IndexView.layout # => ApplicationLayout
+    def self.layout=(layout)
+      @layout = Rendering::LayoutFinder.find(layout)
+    end
+
+    # Returns the default layout to assign to the registered views.
+    # If not already set, it returns a <tt>Rendering::NullLayout</tt>.
+    #
+    # @return [Class,Rendering::NullLayout] depends if already set or not.
+    #
+    # @since 0.1.0
+    #
+    # @see Lotus::View.layout=
+    def self.layout
+      @layout ||= Rendering::NullLayout
+    end
+
+    # A set of registered views.
+    #
+    # @return [Set] all the registered views.
+    #
+    # @api private
+    # @since 0.1.0
+    def self.views
+      @views ||= Set.new
+    end
+
+    # A set of registered layouts.
+    #
+    # @return [Set] all the registered layout.
+    #
+    # @api private
+    # @since 0.1.0
+    def self.layouts
+      @layouts ||= Set.new
+    end
+
+    #FIXME extract a Loader class
+    def self.load!
+      root.freeze
+      layout.freeze
+      views.freeze
+
+      views.each do |view|
+        view.send(:load!)
+      end
+
+      layouts.each do |layout|
+        layout.send(:load!)
+      end
+    end
+
+    def self.unload!
+      instance_variable_set(:@root, nil)
+      instance_variable_set(:@layout, nil)
+      instance_variable_set(:@views, Set.new)
+      instance_variable_set(:@layouts, Set.new)
+    end
   end
 end

data/lib/lotus-view.rb

@@ -0,0 +1 @@
+require 'lotus/view'

data/lotus-view.gemspec

@@ -4,20 +4,24 @@ $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 require 'lotus/view/version'
 
 Gem::Specification.new do |spec|
-  spec.name          = "lotus-view"
+  spec.name          = 'lotus-view'
   spec.version       = Lotus::View::VERSION
-  spec.authors       = ["Luca Guidi"]
-  spec.email         = ["me@lucaguidi.com"]
-  spec.summary       = %q{View layer for Lotus}
+  spec.authors       = ['Luca Guidi']
+  spec.email         = ['me@lucaguidi.com']
   spec.description   = %q{View layer for Lotus}
-  spec.homepage      = ""
-  spec.license       = "MIT"
+  spec.summary       = %q{View layer for Lotus, with a separation between views and templates}
+  spec.homepage      = 'http://lotusrb.org'
+  spec.license       = 'MIT'
 
   spec.files         = `git ls-files`.split($/)
-  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
-  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
-  spec.require_paths = ["lib"]
+  spec.executables   = []
+  spec.test_files    = spec.files.grep(%r{^(test)/})
+  spec.require_paths = ['lib']
 
-  spec.add_development_dependency "bundler", "~> 1.5"
-  spec.add_development_dependency "rake"
+  spec.add_runtime_dependency 'tilt',        '~> 2.0', '>= 2.0.1'
+  spec.add_runtime_dependency 'lotus-utils', '~> 0.1'
+
+  spec.add_development_dependency 'bundler',  '~> 1.5'
+  spec.add_development_dependency 'minitest', '~> 5'
+  spec.add_development_dependency 'rake',     '~> 10'
 end

data/test/fixtures/templates/application.html.erb

@@ -0,0 +1,10 @@
+<html>
+  <head>
+    <title><%= title %></title>
+  </head>
+
+  <body>
+    <%= render partial: 'shared/sidebar' %>
+    <%= yield %>
+  </body>
+</html>

data/test/fixtures/templates/articles/_form.html.erb

@@ -0,0 +1,4 @@
+<form>
+  <input type="hidden" name="secret" value="<%= secret %>" />
+  <input type="text" name="article[title]" value="<%= article.title %>" />
+</form>

data/test/fixtures/templates/articles/alternative_new.html.erb

@@ -0,0 +1 @@
+<%= render template: 'articles/new', locals: { errors: {} } %>

data/test/fixtures/templates/articles/index.atom.erb

@@ -0,0 +1,5 @@
+<entry>
+  <% articles.each do |article| %>
+  <title><%= article.title %></title>
+  <% end %>
+<entry>