lotus-view 0.0.0 → 0.1.0

data/lib/lotus/layout.rb

@@ -0,0 +1,132 @@
+require 'lotus/view/rendering/layout_registry'
+require 'lotus/view/rendering/layout_scope'
+require 'lotus/view/rendering/null_layout'
+
+module Lotus
+  # Layout
+  #
+  # @since 0.1.0
+  #
+  # @see Lotus::Layout::ClassMethods
+  module Layout
+    # Register a layout
+    #
+    # @api private
+    # @since 0.1.0
+    #
+    # @example
+    #   require 'lotus/view'
+    #
+    #   class ApplicationLayout
+    #     include Lotus::Layout
+    #   end
+    def self.included(base)
+      base.class_eval do
+        extend Lotus::View::Dsl.dup
+        extend ClassMethods
+      end
+
+      Lotus::View.layouts.add(base)
+    end
+
+    # Class level API
+    #
+    # @since 0.1.0
+    module ClassMethods
+      # Template name suffix
+      #
+      # @api private
+      # @since 0.1.0
+      #
+      # @see Lotus::Layout::ClassMethods#suffix
+      # @see Lotus::Layout::ClassMethods#template
+      SUFFIX = '_layout'.freeze
+
+      # A registry that holds all the registered layouts.
+      #
+      # @api private
+      # @since 0.1.0
+      #
+      # @see Lotus::View::Rendering::LayoutRegistry
+      def registry
+        @@registry ||= View::Rendering::LayoutRegistry.new(self)
+      end
+
+      # Template name
+      #
+      # @api private
+      # @since 0.1.0
+      #
+      # @see Lotus::Layout::ClassMethods#SUFFIX
+      # @see Lotus::Layout::ClassMethods#suffix
+      #
+      # @example
+      #   # Given a template 'templates/application.html.erb'
+      #
+      #   class ApplicationLayout
+      #     include Lotus::Layout
+      #   end
+      #
+      # ApplicationLayout.template # => 'application'
+      def template
+        super.gsub(suffix, '')
+      end
+
+      # Template name suffix
+      #
+      # @api private
+      # @since 0.1.0
+      #
+      # @see Lotus::Layout::ClassMethods#SUFFIX
+      # @see Lotus::Layout::ClassMethods#template
+      def suffix
+        SUFFIX
+      end
+
+      protected
+      # Loading mechanism hook.
+      #
+      # @api private
+      # @since 0.1.0
+      #
+      # @see Lotus::View.load!
+      def load!
+        registry.freeze
+      end
+    end
+
+    # 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::View::Rendering#render
+    def initialize(scope, rendered)
+      @scope, @rendered = View::Rendering::LayoutScope.new(self, scope), rendered
+    end
+
+    # Render the layout
+    #
+    # @return [String] the output of the rendering process
+    #
+    # @api private
+    # @since 0.1.0
+    #
+    # @see Lotus::View::Rendering#render
+    def render
+      template.render(@scope, &Proc.new{@rendered})
+    end
+
+    protected
+    # The template for the current format
+    #
+    # @api private
+    # @since 0.1.0
+    def template
+      self.class.registry.resolve({format: @scope.format})
+    end
+  end
+end

data/lib/lotus/presenter.rb

@@ -0,0 +1,70 @@
+module Lotus
+  # Presenter pattern implementation
+  #
+  # @since 0.1.0
+  #
+  # @example
+  #   require 'lotus/view'
+  #
+  #   class Map
+  #     attr_reader :locations
+  #
+  #     def initialize(locations)
+  #       @locations = locations
+  #     end
+  #
+  #     def location_names
+  #       @locations.join(', ')
+  #     end
+  #   end
+  #
+  #   class MapPresenter
+  #     include Lotus::Presenter
+  #
+  #     def count
+  #       locations.count
+  #     end
+  #
+  #     def location_names
+  #       super.upcase
+  #     end
+  #
+  #     def inspect_object
+  #       @object.inspect
+  #     end
+  #   end
+  #
+  #   map = Map.new(['Rome', 'Boston'])
+  #   presenter = MapPresenter.new(map)
+  #
+  #   # access a map method
+  #   puts presenter.locations # => ['Rome', 'Boston']
+  #
+  #   # access presenter concrete methods
+  #   puts presenter.count # => 1
+  #
+  #   # uses super to access original object implementation
+  #   puts presenter.location_names # => 'ROME, BOSTON'
+  #
+  #   # it has private access to the original object
+  #   puts presenter.inspect_object # => #<Map:0x007fdeada0b2f0 @locations=["Rome", "Boston"]>
+  module Presenter
+    # Initialize the presenter
+    #
+    # @param object [Object] the object to present
+    #
+    # @since 0.1.0
+    def initialize(object)
+      @object = object
+    end
+
+    protected
+    def method_missing(m, *args, &blk)
+      if @object.respond_to?(m)
+        @object.__send__ m, *args, &blk
+      else
+        super
+      end
+    end
+  end
+end

data/lib/lotus/view/dsl.rb

@@ -0,0 +1,247 @@
+require 'lotus/utils/string'
+require 'lotus/view/rendering/layout_finder'
+
+module Lotus
+  module View
+    # Class level DSL
+    #
+    # @since 0.1.0
+    module Dsl
+      # When a value is given, specify a templates root path for the view.
+      # Otherwise, it returns templates root path.
+      #
+      # When not initialized, it will return the global value from `Lotus::View.root`.
+      #
+      # @param value [String] the templates root for this view
+      #
+      # @return [Pathname] the specified root for this view or the global value
+      #
+      # @since 0.1.0
+      #
+      # @example Default usage
+      #   require 'lotus/view'
+      #
+      #   module Articles
+      #     class Show
+      #       include Lotus::View
+      #     end
+      #   end
+      #
+      #   Lotus::View.root    # => 'app/templates'
+      #   Articles::Show.root # => 'app/templates'
+      #
+      # @example Custom root
+      #   require 'lotus/view'
+      #
+      #   module Articles
+      #     class Show
+      #       include Lotus::View
+      #       root 'path/to/articles/templates'
+      #     end
+      #   end
+      #
+      #   Lotus::View.root    # => 'app/templates'
+      #   Articles::Show.root # => 'path/to/articles/templates'
+      def root(value = nil)
+        if value
+          @@root = Pathname.new value
+        else
+          @@root ||= Lotus::View.root
+        end
+      end
+
+      # When a value is given, specify the handled format.
+      # Otherwise, it returns the previously specified format.
+      #
+      # @param value [Symbol] the format
+      #
+      # @return [Symbol, nil] the specified format for this view, if set
+      #
+      # @since 0.1.0
+      #
+      # @example
+      #   require 'lotus/view'
+      #
+      #   module Articles
+      #     class Show
+      #       include Lotus::View
+      #     end
+      #
+      #     class JsonShow < Show
+      #       format :json
+      #     end
+      #   end
+      #
+      #   Articles::Show.format     # => nil
+      #   Articles::JsonShow.format # => :json
+      def format(value = nil)
+        if value
+          @format = value
+        else
+          @format
+        end
+      end
+
+      # When a value is given, specify the relative path to the template.
+      # Otherwise, it returns the name that follows Lotus::View conventions.
+      #
+      # @param value [String] relative template path
+      #
+      # @return [String] the specified template for this view or the name
+      #   that follows the convention
+      #
+      # @since 0.1.0
+      #
+      # @example Default usage
+      #   require 'lotus/view'
+      #
+      #   module Articles
+      #     class Show
+      #       include Lotus::View
+      #     end
+      #
+      #     class JsonShow < Show
+      #       format :json
+      #     end
+      #   end
+      #
+      #   Articles::Show.template     # => 'articles/show'
+      #   Articles::JsonShow.template # => 'articles/show'
+      #
+      # @example Custom template
+      #   require 'lotus/view'
+      #
+      #   module Articles
+      #     class Show
+      #       include Lotus::View
+      #       template 'articles/single_article'
+      #     end
+      #
+      #     class JsonShow < Show
+      #       format :json
+      #     end
+      #   end
+      #
+      #   Articles::Show.template     # => 'articles/single_article'
+      #   Articles::JsonShow.template # => 'articles/single_article'
+      def template(value = nil)
+        if value
+          @@template = value
+        else
+          @@template ||= Utils::String.new(name).underscore
+        end
+      end
+
+      # When a value is given, it specifies the layout.
+      # Otherwise, it returns the previously specified layout.
+      #
+      # When the global configuration is set (`Lotus::View.layout=`), after the
+      # loading process, it will return that layout if not otherwise specified.
+      #
+      # @param value [Symbol,nil] the layout name
+      #
+      # @return [Symbol, nil] the specified layout for this view, if set
+      #
+      # @since 0.1.0
+      #
+      # @see Lotus::Layout
+      #
+      # @example Default usage
+      #   require 'lotus/view'
+      #
+      #   module Articles
+      #     class Show
+      #       include Lotus::View
+      #     end
+      #   end
+      #
+      #   Articles::Show.layout # => nil
+      #
+      # @example Custom layout
+      #   require 'lotus/view'
+      #
+      #   class ArticlesLayout
+      #     include Lotus::Layout
+      #   end
+      #
+      #   module Articles
+      #     class Show
+      #       include Lotus::View
+      #       layout :articles
+      #     end
+      #   end
+      #
+      #   Articles::Show.layout # => :articles
+      #
+      # @example Global configuration
+      #   require 'lotus/view'
+      #
+      #   class ApplicationLayout
+      #     include Lotus::Layout
+      #   end
+      #
+      #   module Articles
+      #     class Show
+      #       include Lotus::View
+      #     end
+      #   end
+      #
+      #   Lotus::View.layout = :application
+      #   Articles::Show.layout # => nil
+      #
+      #   Lotus::View.load!
+      #   Articles::Show.layout # => :application
+      #
+      # @example Global configuration with custom layout
+      #   require 'lotus/view'
+      #
+      #   class ApplicationLayout
+      #     include Lotus::Layout
+      #   end
+      #
+      #   class ArticlesLayout
+      #     include Lotus::Layout
+      #   end
+      #
+      #   module Articles
+      #     class Show
+      #       include Lotus::View
+      #       layout :articles
+      #     end
+      #   end
+      #
+      #   Lotus::View.layout = :application
+      #   Articles::Show.layout # => :articles
+      #
+      #   Lotus::View.load!
+      #   Articles::Show.layout # => :articles
+      def layout(value = nil)
+        if value
+          @layout = value
+        else
+          @layout
+        end
+      end
+
+      protected
+
+      # Loading mechanism hook.
+      #
+      # @api private
+      # @since 0.1.0
+      #
+      # @see Lotus::View.load!
+      def load!
+        super
+
+        views.each do |v|
+          v.root.freeze
+          v.format.freeze
+          v.template.freeze
+          v.layout(Rendering::LayoutFinder.new(v).find)
+          v.layout.freeze
+        end
+      end
+    end
+  end
+end

data/lib/lotus/view/inheritable.rb

@@ -0,0 +1,50 @@
+module Lotus
+  module View
+    # Inheriting mechanisms
+    #
+    # @since 0.1.0
+    module Inheritable
+      # Register a view subclass
+      #
+      # @api private
+      # @since 0.1.0
+      #
+      # @example
+      #   require 'lotus/view'
+      #
+      #   class IndexView
+      #     include Lotus::View
+      #   end
+      #
+      #   class JsonIndexView < IndexView
+      #   end
+      def inherited(base)
+        subclasses.add base
+      end
+
+      # Set of registered subclasses
+      #
+      # @api private
+      # @since 0.1.0
+      def subclasses
+        @@subclasses ||= Set.new
+      end
+
+      protected
+      # Loading mechanism hook.
+      #
+      # @api private
+      # @since 0.1.0
+      #
+      # @see Lotus::View.load!
+      def load!
+        subclasses.freeze
+        views.freeze
+      end
+
+      def views
+        @@views ||= [ self ] + subclasses.to_a
+      end
+    end
+  end
+end

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

@@ -0,0 +1,104 @@
+require 'lotus/utils/string'
+
+module Lotus
+  module View
+    module Rendering
+      # Defines the logic to find a layout
+      #
+      # @api private
+      # @since 0.1.0
+      #
+      # @see Lotus::Layout
+      class LayoutFinder
+        # Layout class name suffix
+        #
+        # @api private
+        # @since 0.1.0
+        SUFFIX = 'Layout'.freeze
+
+        # Find a layout from the given name.
+        #
+        # @param layout [Symbol,String,NilClass] layout name or nil if you want
+        #   to fallback to the framework defaults (see `Lotus::View.layout`).
+        #
+        # @return [Lotus::Layout] the layout for the given name or
+        #   `Lotus::View.layout`
+        #
+        # @api private
+        # @since 0.1.0
+        #
+        # @example With given name
+        #   require 'lotus/view'
+        #
+        #   Lotus::View::Rendering::LayoutFinder.find(:article) # =>
+        #     ArticleLayout
+        #
+        # @example With nil
+        #   require 'lotus/view'
+        #
+        #   Lotus::View.layout # => :application
+        #   Lotus::View::Rendering::LayoutFinder.find(nil) # =>
+        #     ApplicationLayout
+        def self.find(layout)
+          case layout
+          when Symbol, String
+            class_name = "#{ Utils::String.new(layout).classify }#{ SUFFIX }"
+            Object.const_get(class_name)
+          when nil
+            Lotus::View.layout
+          end
+        end
+
+        # Initialize the finder
+        #
+        # @param view [Class, #layout]
+        #
+        # @api private
+        # @since 0.1.0
+        def initialize(view)
+          @view = view
+        end
+
+        # Find the layout for the view
+        #
+        # @return [Lotus::Layout] the layout associated to the view
+        #
+        # @see Lotus::View::Rendering::LayoutFinder.find
+        # @see Lotus::View::Rendering::LayoutFinder#initialize
+        #
+        # @api private
+        # @since 0.1.0
+        #
+        # @example With layout
+        #   require 'lotus/view'
+        #
+        #   module Articles
+        #     class Show
+        #       include Lotus::View
+        #       layout :article
+        #     end
+        #   end
+        #
+        #   Lotus::View::Rendering::LayoutFinder.new(Articles::Show) # =>
+        #     ArticleLayout
+        #
+        # @example Without layout
+        #   require 'lotus/view'
+        #
+        #   module Dashboard
+        #     class Index
+        #       include Lotus::View
+        #     end
+        #   end
+        #
+        #   Lotus::View.layout # => :application
+        #
+        #   Lotus::View::Rendering::LayoutFinder.new(Dashboard::Index) # =>
+        #     ApplicationLayout
+        def find
+          self.class.find(@view.layout)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,63 @@
+require 'lotus/view/rendering/null_template'
+require 'lotus/view/rendering/templates_finder'
+
+module Lotus
+  module View
+    module Rendering
+      # Holds the references of all the registered layouts.
+      # As now the registry is unique at the level of the framework.
+      #
+      # @api private
+      # @since 0.1.0
+      #
+      # @see Lotus::Layout::ClassMethods#registry
+      class LayoutRegistry < ::Hash
+        # Initialize the registry
+        #
+        # @param view [Class] the view
+        #
+        # @api private
+        # @since 0.1.0
+        def initialize(view)
+          super()
+
+          @view = view
+          prepare!
+        end
+
+        # Returns the layout for the given context.
+        #
+        # @param context [Hash] the rendering context
+        # @option context [Symbol] :format the requested format
+        #
+        # @return [Lotus::Layout, Lotus::View::Rendering::NullTemplate]
+        #   the layout associated with the given context or a `NullTemplate` if
+        #   it can't be found.
+        #
+        # @raise [Lotus::View::MissingFormatError] if the given context doesn't
+        #   have the :format key
+        #
+        # @api private
+        # @since 0.1.0
+        def resolve(context)
+          fetch(format(context)) { NullTemplate.new }
+        end
+
+        protected
+        def prepare!
+          templates.each do |template|
+            merge! template.format => template
+          end
+        end
+
+        def templates
+          TemplatesFinder.new(@view).find
+        end
+
+        def format(context)
+          context.fetch(:format) { raise MissingFormatError }
+        end
+      end
+    end
+  end
+end