lotus-view 0.0.0 → 0.1.0

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

@@ -0,0 +1,138 @@
+module Lotus
+  module View
+    module Rendering
+      # Scope for layout rendering
+      #
+      # @since 0.1.0
+      class LayoutScope
+        # Initialize the scope
+        #
+        # @param layout [Lotus::Layout] the layout to render
+        # @param scope [Lotus::View::Rendering::Scope] the scope of the current
+        #   view
+        #
+        # @api private
+        # @since 0.1.0
+        def initialize(layout, scope)
+          @layout, @scope = layout, scope
+        end
+
+        # Render a partial or a template within a layout template.
+        #
+        # @param options [Hash]
+        # @option options [String] :partial the partial template to render
+        # @option options [String] :template the template to render
+        #
+        # @return [String] the output of the rendering process
+        #
+        # @since 0.1.0
+        #
+        # @example Rendering partial
+        #   # Given a partial under:
+        #   #   templates/shared/_sidebar.html.erb
+        #   #
+        #   # In the layout template:
+        #   #   templates/application.html.erb
+        #   #
+        #   # Use like this:
+        #   <%= render partial: 'shared/sidebar' %>
+        #
+        # @example Rendering template
+        #   # Given a template under:
+        #   #   templates/articles/index.html.erb
+        #   #
+        #   # In the layout template:
+        #   #   templates/application.html.erb
+        #   #
+        #   # Use like this:
+        #   <%= render template: 'articles/index' %>
+        #
+        # @example Rendering partial, using optional :locals
+        #   # Given a partial under:
+        #   #   templates/shared/_sidebar.html.erb
+        #   #
+        #   # In the layout template:
+        #   #   templates/application.html.erb
+        #   #
+        #   # Use like this:
+        #   <%= render partial: 'shared/sidebar', { user: current_user } %>
+        #
+        #   #
+        #   # `user` will be available in the scope of the sidebar rendering
+        def render(options)
+          renderer(options).render
+        end
+
+        # Returns the requested format.
+        #
+        # @return [Symbol] the requested format (eg. :html, :json, :xml, etc..)
+        #
+        # @since 0.1.0
+        def format
+          @scope.format
+        end
+
+        # The current view.
+        #
+        # @return [Lotus::View] the current view
+        #
+        # @since 0.1.0
+        def view
+          @view || @scope.view
+        end
+
+        # The current locals.
+        #
+        # @return [Hash] the current locals
+        #
+        # @since 0.1.0
+        def locals
+          @locals || @scope.locals
+        end
+
+        protected
+        # Forward all the missing methods to the view scope or to the layout.
+        #
+        # @api private
+        # @since 0.1.0
+        #
+        # @see Lotus::View::Rendering::Scope
+        # @see Lotus::Layout
+        #
+        # @example
+        #   # In the layout template:
+        #   #   templates/application.html.erb
+        #   #
+        #   # Use like this:
+        #   <title><%= article.title %></title>
+        #
+        #   # `article` will be looked up in the view scope first.
+        #   # If not found, it will be searched within the layout.
+        def method_missing(m)
+          begin
+            @scope.__send__ m
+          rescue
+            @layout.__send__ m
+          end
+        end
+
+        def renderer(options)
+          if options[:partial]
+            Rendering::Partial
+          elsif options[:template]
+            Rendering::Template
+          end.new(view, _options(options))
+        end
+
+        private
+        def _options(options)
+          options.dup.tap do |opts|
+            opts.merge!(format: format)
+            opts[:locals] ||= {}
+            opts[:locals].merge!(locals)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,52 @@
+module Lotus
+  module View
+    module Rendering
+      # Null Object pattern for Layout.
+      # It's used when a view doesn't require a layout.
+      #
+      # @api private
+      # @since 0.1.0
+      #
+      # @example
+      #   require 'lotus/view'
+      #
+      #   module Articles
+      #     class Show
+      #       include Lotus::View
+      #       layout nil
+      #     end
+      #   end
+      #
+      #   # In this scenario we will use a `NullLayout`.
+      class NullLayout
+
+        # Initialize a layout
+        #
+        # @param scope [Lotus::View::Rendering::Scope] view rendering scope
+        # @param rendered [String] the output of the view rendering process
+        #
+        # @api private
+        # @since 0.1.0
+        #
+        # @see Lotus::Layout#initialize
+        # @see Lotus::View::Rendering#render
+        def initialize(scope, rendered)
+          @rendered = rendered
+        end
+
+        # Render the layout
+        #
+        # @return [String] the output of the rendering process
+        #
+        # @api private
+        # @since 0.1.0
+        #
+        # @see Lotus::Layout#render
+        # @see Lotus::View::Rendering#render
+        def render
+          @rendered
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,79 @@
+module Lotus
+  module View
+    module Rendering
+      # Null Object pattern for layout template
+      #
+      # It's used when a layout doesn't have an associated template.
+      #
+      # A common scenario is for non-html requests.
+      # Usually we have a template for the application layout
+      # (eg `templates/application.html.erb`), but we don't use to have the a
+      # template for JSON requests (eg `templates/application.json.erb`).
+      # Because most of the times, we only return the output of the view.
+      #
+      # @api private
+      # @since 0.1.0
+      #
+      # @example
+      #   require 'lotus/view'
+      #
+      #   # We have an ApplicationLayout (views/application_layout.rb):
+      #   class ApplicationLayout
+      #     include Lotus::Layout
+      #   end
+      #
+      #   # Our layout has a template for HTML requests, located at:
+      #   # templates/application.html.erb
+      #
+      #   # We set it as global layout
+      #   Lotus::View.layout = :application
+      #
+      #   # We have two views for HTML and JSON articles.
+      #   # They have a template each:
+      #   #
+      #   #   * templates/articles/show.html.erb
+      #   #   * templates/articles/show.json.erb
+      #   module Articles
+      #     class Show
+      #       include Lotus::View
+      #       format :html
+      #     end
+      #
+      #     class JsonShow < Show
+      #       format :json
+      #     end
+      #   end
+      #
+      #   # We initialize the framework
+      #   Lotus::View.load!
+      #
+      #
+      #
+      #   # When we ask for a HTML rendering, it will use `Articles::Show` and
+      #   # ApplicationLayout. The output will be a composition of:
+      #   #
+      #   #   * templates/articles/show.html.erb
+      #   #   * templates/application.html.erb
+      #
+      #   # When we ask for a JSON rendering, it will use `Articles::JsonShow`
+      #   # and ApplicationLayout. Since, the layout doesn't have any associated
+      #   # template for JSON, the output will be a composition of:
+      #   #
+      #   #   * templates/articles/show.json.erb
+      class NullTemplate
+        # Render the layout template
+        #
+        # @return [String] the output of the rendering process
+        #
+        # @api private
+        # @since 0.1.0
+        #
+        # @see Lotus::Layout#render
+        # @see Lotus::View::Rendering#render
+        def render(scope, locals = {}, &blk)
+          blk.call
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,29 @@
+require 'lotus/view/rendering/partial_finder'
+
+module Lotus
+  module View
+    module Rendering
+      # Rendering partial
+      #
+      # It's used when a template wants to render a partial.
+      #
+      # @api private
+      # @since 0.1.0
+      #
+      # @see Lotus::View::Rendering::Template
+      # @see Lotus::View::Rendering::LayoutScope#render
+      #
+      # @example
+      #   # We have an application template (templates/application.html.erb)
+      #   # that uses the following line:
+      #
+      #   <%= render partial: 'shared/sidebar' %>
+      class Partial < Template
+        protected
+        def template
+          PartialFinder.new(@view.class, @options).find
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,41 @@
+require 'lotus/view/rendering/template_finder'
+
+module Lotus
+  module View
+    module Rendering
+      # Find a partial for the current view context.
+      # It's used when a template wants to render a partial.
+      #
+      # @see Lotus::View::Rendering::Partial
+      # @see Lotus::View::Rendering::TemplateFinder
+      #
+      # @api private
+      # @since 0.1.0
+      class PartialFinder < TemplateFinder
+        # Template file name prefix.
+        # By convention a partial file name starts with this prefix.
+        #
+        # @api private
+        # @since 0.1.0
+        #
+        # @example
+        #   "_sidebar.html.erb"
+        PREFIX = '_'.freeze
+
+        protected
+        def template_name
+          *all, last = partial_name.split(separator)
+          all.push( last.prepend(prefix) ).join(separator)
+        end
+
+        def partial_name
+          @options[:partial]
+        end
+
+        def prefix
+          PREFIX
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,129 @@
+require 'lotus/view/rendering/layout_registry'
+require 'lotus/view/rendering/view_finder'
+
+module Lotus
+  module View
+    module Rendering
+      # Holds all the references of all the registered subclasses of a view.
+      # We have one registry for each superclass view.
+      #
+      # @api private
+      # @since 0.1.0
+      #
+      # @see Lotus::View::Rendering::LayoutRegistry
+      # @see Lotus::View::Rendering#registry
+      #
+      # @example
+      #   require 'lotus/view'
+      #
+      #   module Articles
+      #     class Index
+      #       include Lotus::View
+      #     end
+      #
+      #     class Show
+      #       include Lotus::View
+      #     end
+      #
+      #     class JsonShow < Show
+      #       format :json
+      #     end
+      #
+      #     class XmlShow < Show
+      #       format :xml
+      #
+      #       def render
+      #         ArticleSerializer.new(article).to_xml
+      #       end
+      #     end
+      #   end
+      #
+      #   # We have the following templates:
+      #   #
+      #   #  * articles/index.html.erb
+      #   #  * articles/index.atom.erb
+      #   #  * articles/show.html.erb
+      #   #  * articles/show.json.erb
+      #
+      #   # One registry per superclass view
+      #   Articles::Index.send(:registry).object_id     # => 70135342862240
+      #
+      #   Articles::Show.send(:registry).object_id      # => 70135342110540
+      #   Articles::XmlShow.send(:registry).object_id   # => 70135342110540
+      #   Articles::JsonShow.send(:registry).object_id  # => 70135342110540
+      #
+      #
+      #
+      #   # It holds the references for all the templates and the views
+      #   Articles::Index.send(:registry).inspect
+      #     # => { :all  => [Articles::Index, nil],
+      #     #      :atom => [Articles::Index, #<Lotus::View::Template ... @file="/path/to/templates/articles/index.atom.erb"],
+      #     #      :html => [Articles::Index, #<Lotus::View::Template ... @file="/path/to/templates/articles/index.html.erb"] }
+      #
+      #   Articles::Show.send(:registry).inspect
+      #     # => { :all  => [Articles::Show, nil],
+      #     #      :html => [Articles::Show,     #<Lotus::View::Template ... @file="/path/to/templates/articles/show.html.erb"],
+      #     #      :json => [Articles::JsonShow, #<Lotus::View::Template ... @file="/path/to/templates/articles/show.json.erb"],
+      #     #      :xml  => [Articles::XmlShow, nil] }
+      class Registry < LayoutRegistry
+        # Default format for views without an explicit format.
+        #
+        # @api private
+        # @since 0.1.0
+        #
+        # @see Lotus::View::Dsl#format
+        DEFAULT_FORMAT = :all
+
+        # Returns the view for the given context.
+        #
+        # @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
+        #
+        # @raise [Lotus::View::MissingFormatError] if the given context doesn't
+        #   have the :format key
+        #
+        # @api private
+        # @since 0.1.0
+        #
+        # @see Lotus::View::Rendering#render
+        def resolve(context)
+          view, template = fetch(format(context)) { self[DEFAULT_FORMAT] }
+          view.new(template, context)
+        end
+
+        private
+        def prepare!
+          prepare_views!
+          prepare_templates!
+        end
+
+        def prepare_views!
+          views.each do |view|
+            merge! view.format || DEFAULT_FORMAT => [ view, template_for(view) ]
+          end
+        end
+
+        def prepare_templates!
+          templates.each do |template|
+            merge! template.format => [ view_for(template), template ]
+          end
+        end
+
+        def views
+          @view.subclasses + [ @view ]
+        end
+
+        def view_for(template)
+          ViewFinder.new(@view).find(template)
+        end
+
+        def template_for(view)
+          templates.find {|template| template.format == view.format }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,48 @@
+require 'lotus/view/rendering/layout_scope'
+require 'lotus/view/rendering/template'
+require 'lotus/view/rendering/partial'
+
+module Lotus
+  module View
+    module Rendering
+      # Rendering scope
+      #
+      # @since 0.1.0
+      #
+      # @see Lotus::View::Rendering::LayoutScope
+      class Scope < LayoutScope
+        # Initialize the scope
+        #
+        # @param view [Class] the view
+        # @param locals [Hash] a set of objects available during the rendering
+        # @option locals [Symbol] :format the requested format
+        #
+        # @api private
+        # @since 0.1.0
+        def initialize(view, locals = {})
+          @view, @locals = view, locals
+        end
+
+        # Returns the requested format.
+        #
+        # @return [Symbol] the requested format (eg. :html, :json, :xml, etc..)
+        #
+        # @since 0.1.0
+        def format
+          locals[:format]
+        end
+
+        protected
+        def method_missing(m)
+          if @view.respond_to?(m)
+            @view.__send__ m
+          elsif @locals.key?(m)
+            @locals[m]
+          else
+            super
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,56 @@
+require 'lotus/view/rendering/template_finder'
+
+module Lotus
+  module View
+    module Rendering
+      # Rendering template
+      #
+      # It's used when a template wants to render another template.
+      #
+      # @api private
+      # @since 0.1.0
+      #
+      # @see Lotus::View::Rendering::LayoutScope#render
+      #
+      # @example
+      #   # We have an application template (templates/application.html.erb)
+      #   # that uses the following line:
+      #
+      #   <%= render template: 'articles/show' %>
+      class Template
+        # Initialize a template
+        #
+        # @param view [Lotus::View] the current view
+        # @param options [Hash] the rendering informations
+        # @option options [Symbol] :format the current format
+        # @option options [Hash] :locals the set of objects available within
+        #   the rendering context
+        #
+        # @api private
+        # @since 0.1.0
+        def initialize(view, options)
+          @view, @options = view, options
+        end
+
+        # Render the template.
+        #
+        # @return [String] the output of the rendering process.
+        #
+        # @api private
+        # @since 0.1.0
+        def render
+          template.render(scope)
+        end
+
+        protected
+        def template
+          TemplateFinder.new(@view.class, @options).find
+        end
+
+        def scope
+          Scope.new(@view, @options[:locals])
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,53 @@
+require 'lotus/view/rendering/templates_finder'
+
+module Lotus
+  module View
+    module Rendering
+      # Find a template for the current view context.
+      # It's used when a template wants to render another template.
+      #
+      # @see Lotus::View::Rendering::Template
+      # @see Lotus::View::Rendering::TemplatesFinder
+      #
+      # @api private
+      # @since 0.1.0
+      class TemplateFinder < TemplatesFinder
+        # Initialize a finder
+        #
+        # @param view [Class] a view
+        # @param options [Hash] the informations about the context
+        # @option options [String] :template the template file name
+        # @option options [Symbol] :format the requested format
+        #
+        # @api private
+        # @since 0.1.0
+        def initialize(view, options)
+          super(view)
+          @options = options
+        end
+
+        # Find a template for the current view context
+        #
+        # @return [Lotus::View::Template] the requested template
+        #
+        # @api private
+        # @since 0.1.0
+        #
+        # @see Lotus::View::Rendering::TemplatesFinder#find
+        # @see Lotus::View::Rendering::Template#render
+        def find
+          super.first
+        end
+
+        protected
+        def template_name
+          @options[:template]
+        end
+
+        def format
+          @options[:format]
+        end
+      end
+    end
+  end
+end