hanami-view 0.0.0 → 0.6.0

data/lib/hanami/view/dsl.rb

@@ -0,0 +1,346 @@
+require 'hanami/view/rendering/template_name'
+require 'hanami/view/rendering/layout_finder'
+
+module Hanami
+  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 `Hanami::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 'hanami/view'
+      #
+      #   module Articles
+      #     class Show
+      #       include Hanami::View
+      #     end
+      #   end
+      #
+      #   Hanami::View.configuration.root # => 'app/templates'
+      #   Articles::Show.root            # => 'app/templates'
+      #
+      # @example Custom root
+      #   require 'hanami/view'
+      #
+      #   module Articles
+      #     class Show
+      #       include Hanami::View
+      #       root 'path/to/articles/templates'
+      #     end
+      #   end
+      #
+      #   Hanami::View.configuration.root # => 'app/templates'
+      #   Articles::Show.root            # => 'path/to/articles/templates'
+      def root(value = nil)
+        if value.nil?
+          configuration.root
+        else
+          configuration.root(value)
+        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 'hanami/view'
+      #
+      #   module Articles
+      #     class Show
+      #       include Hanami::View
+      #     end
+      #
+      #     class JsonShow < Show
+      #       format :json
+      #     end
+      #   end
+      #
+      #   Articles::Show.format     # => nil
+      #   Articles::JsonShow.format # => :json
+      def format(value = nil)
+        if value.nil?
+          @format
+        else
+          @format = value
+        end
+      end
+
+      # When a value is given, specify the relative path to the template.
+      # Otherwise, it returns the name that follows Hanami::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 'hanami/view'
+      #
+      #   module Articles
+      #     class Show
+      #       include Hanami::View
+      #     end
+      #
+      #     class JsonShow < Show
+      #       format :json
+      #     end
+      #   end
+      #
+      #   Articles::Show.template     # => 'articles/show'
+      #   Articles::JsonShow.template # => 'articles/show'
+      #
+      # @example Custom template
+      #   require 'hanami/view'
+      #
+      #   module Articles
+      #     class Show
+      #       include Hanami::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'
+      #
+      # @example With namespace
+      #   require 'hanami/view'
+      #
+      #   module Furnitures
+      #     View = Hanami::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 'hanami/view'
+      #
+      #   module Frontend
+      #     View = Hanami::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 'hanami/view'
+      #
+      #   module Bookshelf
+      #     module Web
+      #       View = Hanami::View.generate(self)
+      #
+      #       module Views
+      #         module Books
+      #           class Show
+      #             include Bookshelf::Web::View
+      #           end
+      #         end
+      #       end
+      #     end
+      #
+      #     module Api
+      #       View = Hanami::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.nil?
+          @template ||= Rendering::TemplateName.new(name, configuration.namespace).to_s
+        else
+          @template = value
+        end
+      end
+
+      # When a value is given, it specifies the layout.
+      # When false is given, Hanami::View::Rendering::NullLayout is returned.
+      # Otherwise, it returns the previously specified layout.
+      #
+      # When the global configuration is set (`Hanami::View.layout=`), after the
+      # loading process, it will return that layout if not otherwise specified.
+      #
+      # @param value [Symbol, FalseClass, nil] the layout name
+      #
+      # @return [Symbol, nil] the specified layout for this view, if set
+      #
+      # @since 0.1.0
+      #
+      # @see Hanami::Layout
+      #
+      # @example Default usage
+      #   require 'hanami/view'
+      #
+      #   module Articles
+      #     class Show
+      #       include Hanami::View
+      #     end
+      #   end
+      #
+      #   Articles::Show.layout # => nil
+      #
+      # @example Custom layout
+      #   require 'hanami/view'
+      #
+      #   class ArticlesLayout
+      #     include Hanami::Layout
+      #   end
+      #
+      #   module Articles
+      #     class Show
+      #       include Hanami::View
+      #       layout :articles
+      #     end
+      #   end
+      #
+      #   Articles::Show.layout # => :articles
+      #
+      # @example Global configuration
+      #   require 'hanami/view'
+      #
+      #   class ApplicationLayout
+      #     include Hanami::Layout
+      #   end
+      #
+      #   module Articles
+      #     class Show
+      #       include Hanami::View
+      #     end
+      #   end
+      #
+      #   Hanami::View.layout = :application
+      #   Articles::Show.layout # => nil
+      #
+      #   Hanami::View.load!
+      #   Articles::Show.layout # => :application
+      #
+      # @example Global configuration with custom layout
+      #   require 'hanami/view'
+      #
+      #   class ApplicationLayout
+      #     include Hanami::Layout
+      #   end
+      #
+      #   class ArticlesLayout
+      #     include Hanami::Layout
+      #   end
+      #
+      #   module Articles
+      #     class Show
+      #       include Hanami::View
+      #       layout :articles
+      #     end
+      #   end
+      #
+      #   Hanami::View.layout = :application
+      #   Articles::Show.layout # => :articles
+      #
+      #   Hanami::View.load!
+      #   Articles::Show.layout # => :articles
+      #
+      # @example Disable layout for the view
+      #   require 'hanami/view'
+      #
+      #   class ApplicationLayout
+      #     include Hanami::Layout
+      #   end
+      #
+      #   module Articles
+      #     class Show
+      #       include Hanami::View
+      #       layout false
+      #     end
+      #   end
+      #
+      #   Hanami::View.load!
+      #   Articles::Show.layout # => Hanami::View::Rendering::NullLayout
+      def layout(value = nil)
+        if value.nil?
+          @_layout ||= Rendering::LayoutFinder.find(@layout || configuration.layout, configuration.namespace)
+        elsif !value
+          @layout = Hanami::View::Rendering::NullLayout
+        else
+          @layout = value
+        end
+      end
+
+      protected
+
+      # Loading mechanism hook.
+      #
+      # @api private
+      # @since 0.1.0
+      #
+      # @see Hanami::View.load!
+      def load!
+        super
+
+        views.each do |v|
+          v.root.freeze
+          v.format.freeze
+          v.template.freeze
+          v.layout#.freeze
+          v.configuration.freeze
+        end
+      end
+    end
+  end
+end

data/lib/hanami/view/errors.rb

@@ -0,0 +1,47 @@
+module Hanami
+  module View
+    # @since 0.5.0
+    class Error < ::StandardError
+    end
+
+    # Missing template error
+    #
+    # This is raised at the runtime when Hanami::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 < Error
+      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 Hanami::View::Rendering#render
+    class MissingFormatError < Error
+    end
+
+    # Missing template layout error
+    #
+    # This is raised at the runtime when Hanami::Layout cannot find it's template.
+    #
+    # @since 0.5.0
+    class MissingTemplateLayoutError < Error
+      def initialize(template)
+        super("Can't find layout template '#{ template }'")
+      end
+    end
+  end
+end

data/lib/hanami/view/escape.rb

@@ -0,0 +1,180 @@
+require 'hanami/utils/escape'
+require 'hanami/presenter'
+
+module Hanami
+  module View
+    # Auto escape logic for views and presenters.
+    #
+    # @since 0.4.0
+    module Escape
+      module InstanceMethods
+        private
+        # Mark the given string as safe to render.
+        #
+        # !!! ATTENTION !!! This may open your application to XSS attacks.
+        #
+        # @param string [String] the input string
+        #
+        # @return [Hanami::Utils::Escape::SafeString] the string marked as safe
+        #
+        # @since 0.4.0
+        # @api public
+        #
+        # @example View usage
+        #   require 'hanami/view'
+        #
+        #   User = Struct.new(:name)
+        #
+        #   module Users
+        #     class Show
+        #       include Hanami::View
+        #
+        #       def user_name
+        #         _raw user.name
+        #       end
+        #     end
+        #   end
+        #
+        #   # ERB template
+        #   # <div id="user_name"><%= user_name %></div>
+        #
+        #   user = User.new("<script>alert('xss')</script>")
+        #   html = Users::Show.render(format: :html, user: user)
+        #
+        #   html # => <div id="user_name"><script>alert('xss')</script></div>
+        #
+        # @example Presenter usage
+        #   require 'hanami/view'
+        #
+        #   User = Struct.new(:name)
+        #
+        #   class UserPresenter
+        #     include Hanami::Presenter
+        #
+        #     def name
+        #       _raw @object.name
+        #     end
+        #   end
+        #
+        #   user      = User.new("<script>alert('xss')</script>")
+        #   presenter = UserPresenter.new(user)
+        #
+        #   presenter.name # => "<script>alert('xss')</script>"
+        def _raw(string)
+          ::Hanami::Utils::Escape::SafeString.new(string)
+        end
+
+        # Force the output escape for the given object
+        #
+        # @param object [Object] the input object
+        #
+        # @return [Hanami::View::Escape::Presenter] a presenter with output
+        #   autoescape
+        #
+        # @since 0.4.0
+        # @api public
+        #
+        # @see Hanami::View::Escape::Presenter
+        #
+        # @example View usage
+        #   require 'hanami/view'
+        #
+        #   User = Struct.new(:first_name, :last_name)
+        #
+        #   module Users
+        #     class Show
+        #       include Hanami::View
+        #
+        #       def user
+        #         _escape locals[:user]
+        #       end
+        #     end
+        #   end
+        #
+        #   # ERB template:
+        #   #
+        #   # <div id="first_name">
+        #   #   <%= user.first_name %>
+        #   # </div>
+        #   # <div id="last_name">
+        #   #   <%= user.last_name %>
+        #   # </div>
+        #
+        #   first_name = "<script>alert('first_name')</script>"
+        #   last_name  = "<script>alert('last_name')</script>"
+        #
+        #   user = User.new(first_name, last_name)
+        #   html = Users::Show.render(format: :html, user: user)
+        #
+        #   html
+        #     # =>
+        #     # <div id="first_name">
+        #     #   &lt;script&gt;alert(&apos;first_name&apos;)&lt;&#x2F;script&gt;
+        #     # </div>
+        #     # <div id="last_name">
+        #     #   &lt;script&gt;alert(&apos;last_name&apos;)&lt;&#x2F;script&gt;
+        #     # </div>
+        def _escape(object)
+          ::Hanami::View::Escape::Presenter.new(object)
+        end
+      end
+
+      # Auto escape presenter
+      #
+      # @since 0.4.0
+      # @api private
+      #
+      # @see Hanami::View::Escape::InstanceMethods#_escape
+      class Presenter
+        include ::Hanami::Presenter
+      end
+
+      # Escape the given input if it's a string, otherwise return the oject as it is.
+      #
+      # @param input [Object] the input
+      #
+      # @return [Object,String] the escaped string or the given object
+      #
+      # @since 0.4.0
+      # @api private
+      def self.html(input)
+        case input
+        when String
+          Utils::Escape.html(input)
+        else
+          input
+        end
+      end
+
+      # Module extended override
+      #
+      # @since 0.4.0
+      # @api private
+      def self.extended(base)
+        base.class_eval do
+          include ::Hanami::Utils::ClassAttribute
+          include ::Hanami::View::Escape::InstanceMethods
+
+          class_attribute :autoescape_methods
+          self.autoescape_methods = {}
+        end
+      end
+
+      # Wraps concrete view methods with escape logic.
+      #
+      # @since 0.4.0
+      # @api private
+      def method_added(method_name)
+        unless autoescape_methods[method_name]
+          prepend Module.new {
+            module_eval %{
+              def #{ method_name }(*args, &blk); ::Hanami::View::Escape.html super; end
+            }
+          }
+
+          autoescape_methods[method_name] = true
+        end
+      end
+    end
+  end
+end