hanami-view 2.0.0.alpha7 → 2.1.0.beta1

data/lib/hanami/view/tilt.rb

@@ -1,69 +1,48 @@
 # frozen_string_literal: true
 
-require "dry/core/cache"
 require "tilt"
 
 module Hanami
   class View
     # @api private
     module Tilt
-      extend Dry::Core::Cache
+      Mapping = ::Tilt.default_mapping.dup.tap { |mapping|
+        # If "slim" has been required before "hanami/view", unregister Slim's non-lazy registered
+        # template, so our own template adapter (using register_lazy below) can take precedence.
+        mapping.unregister "slim"
+
+        # Register our own ERB template.
+        mapping.register_lazy "Hanami::View::ERB::Template", "hanami/view/erb/template", "erb", "rhtml"
+
+        # Register ERB templates for Haml and Slim that set the `use_html_safe: true` option.
+        #
+        # Our template namespaces below have the "Adapter" suffix to work around a bug in Tilt's
+        # `Mapping#const_defined?`, which (if slim was already required) would receive
+        # "Hanami::View::Slim::Template" and return `Slim::Template`, which is the opposite of what
+        # we want.
+        mapping.register_lazy "Hanami::View::Tilt::HamlAdapter::Template", "hanami/view/tilt/haml_adapter", "haml"
+        mapping.register_lazy "Hanami::View::Tilt::SlimAdapter::Template", "hanami/view/tilt/slim_adapter", "slim"
+      }
 
       class << self
-        def [](path, mapping, **options)
-          ext = File.extname(path).sub(/^./, "").to_sym
-          activate_adapter ext
-
-          with_mapping(mapping).new(path, **options)
-        end
-
-        def default_mapping
-          ::Tilt.default_mapping
-        end
-
-        def register_adapter(ext, adapter)
-          adapters[ext] = adapter
-        end
-
-        def deregister_adapter(ext)
-          adapters.delete(ext)
+        def [](path, mapping, options)
+          with_mapping(mapping).new(path, options)
         end
 
         private
 
-        def adapters
-          @adapters ||= {}
-        end
-
-        def activate_adapter(ext)
-          fetch_or_store(:adapter, ext) {
-            adapter = adapters[ext]
-            return unless adapter
-
-            *requires, error_message = adapter.requirements
-
-            begin
-              requires.each(&method(:require))
-            rescue LoadError => e
-              raise e, "#{e.message}\n\n#{error_message}"
-            end
-
-            adapter.activate
-          }
-        end
-
         def with_mapping(mapping)
-          fetch_or_store(:mapping, mapping) {
+          View.cache.fetch_or_store(:tilt_mapping, mapping) {
             if mapping.any?
               build_mapping(mapping)
             else
-              default_mapping
+              Mapping
             end
           }
         end
 
         def build_mapping(mapping)
-          default_mapping.dup.tap do |new_mapping|
+          Mapping.dup.tap do |new_mapping|
             mapping.each do |extension, template_class|
               new_mapping.register template_class, extension
             end
@@ -73,6 +52,3 @@ module Hanami
     end
   end
 end
-
-require_relative "tilt/erb"
-require_relative "tilt/haml"

data/lib/hanami/view/version.rb

@@ -3,6 +3,6 @@
 module Hanami
   class View
     # @api private
-    VERSION = "2.0.0.alpha7"
+    VERSION = "2.1.0.beta1"
   end
 end

data/lib/hanami/view.rb

@@ -1,21 +1,12 @@
 # frozen_string_literal: true
 
 require "dry/configurable"
-require "dry/core/cache"
 require "dry/core/equalizer"
 require "dry/inflector"
+require "zeitwerk"
 
-require_relative "view/application_view"
-require_relative "view/context"
-require_relative "view/exposures"
 require_relative "view/errors"
-require_relative "view/part_builder"
-require_relative "view/path"
-require_relative "view/render_environment"
-require_relative "view/rendered"
-require_relative "view/renderer"
-require_relative "view/scope_builder"
-require_relative "view/standalone_view"
+require_relative "view/html"
 
 module Hanami
   # A standalone, template-based view rendering system that offers everything
@@ -32,13 +23,34 @@ module Hanami
   #
   # @api public
   class View
+    # @since 2.1.0
+    # @api private
+    def self.gem_loader
+      @gem_loader ||= Zeitwerk::Loader.new.tap do |loader|
+        root = File.expand_path("..", __dir__)
+        loader.tag = "hanami-view"
+        loader.push_dir(root)
+        loader.ignore(
+          "#{root}/hanami-view.rb",
+          "#{root}/hanami/view/version.rb",
+          "#{root}/hanami/view/errors.rb",
+        )
+        loader.inflector = Zeitwerk::GemInflector.new("#{root}/hanami-view.rb")
+        loader.inflector.inflect(
+          "erb" => "ERB",
+          "html" => "HTML",
+          "html_safe_string_buffer" => "HTMLSafeStringBuffer",
+        )
+      end
+    end
+
+    gem_loader.setup
+
     # @api private
     DEFAULT_RENDERER_OPTIONS = {default_encoding: "utf-8"}.freeze
 
     include Dry::Equalizer(:config, :exposures)
 
-    extend Dry::Core::Cache
-
     extend Dry::Configurable
 
     # @!group Configuration
@@ -143,6 +155,8 @@ module Hanami
     # @!scope class
     setting :default_format, default: :html
 
+    setting :part_class, default: Part
+
     # @overload config.scope_namespace=(namespace)
     #   Set a namespace that will be searched when building scope classes.
     #
@@ -164,6 +178,8 @@ module Hanami
     # @!scope class
     setting :part_builder, default: PartBuilder
 
+    setting :scope_class, default: Scope
+
     # @overload config.scope_namespace=(namespace)
     #   Set a namespace that will be searched when building scope classes.
     #
@@ -226,28 +242,337 @@ module Hanami
     #   @param mapping [Hash<Symbol, Class>] engine mapping
     #   @api public
     # @!scope class
-    setting :renderer_engine_mapping
+    setting :renderer_engine_mapping, default: {}
 
     # @!endgroup
 
-    include StandaloneView
-
-    def self.inherited(subclass)
+    # @api private
+    def self.inherited(klass)
       super
 
-      # When inheriting within an Hanami app, and the application provider has
-      # changed from the superclass, (re-)configure the action for the provider,
-      # i.e. for the slice and/or the application itself
-      if (provider = application_provider(subclass)) && provider != application_provider(subclass.superclass)
-        subclass.include ApplicationView.new(provider)
+      exposures.each do |name, exposure|
+        klass.exposures.import(name, exposure)
+      end
+    end
+
+    # @!group Exposures
+
+    # @!macro [new] exposure_options
+    #   @param options [Hash] the exposure's options
+    #   @option options [Boolean] :layout expose this value to the layout (defaults to false)
+    #   @option options [Boolean] :decorate decorate this value in a matching Part (defaults to
+    #     true)
+    #   @option options [Symbol, Class] :as an alternative name or class to use when finding a
+    #     matching Part
+
+    # @overload expose(name, **options, &block)
+    #   Define a value to be passed to the template. The return value of the
+    #   block will be decorated by a matching Part and passed to the template.
+    #
+    #   The block will be evaluated with the view instance as its `self`. The
+    #   block's parameters will determine what it is given:
+    #
+    #   - To receive other exposure values, provide positional parameters
+    #     matching the exposure names. These exposures will already by decorated
+    #     by their Parts.
+    #   - To receive the view's input arguments (whatever is passed to
+    #     `View#call`), provide matching keyword parameters. You can provide
+    #     default values for these parameters to make the corresponding input
+    #     keys optional
+    #   - To receive the Context object, provide a `context:` keyword parameter
+    #   - To receive the view's input arguments in their entirety, provide a
+    #     keywords splat parameter (i.e. `**input`)
+    #
+    #   @example Accessing input arguments
+    #     expose :article do |slug:|
+    #       article_repo.find_by_slug(slug)
+    #     end
+    #
+    #   @example Accessing other exposures
+    #     expose :articles do
+    #       article_repo.listing
+    #     end
+    #
+    #     expose :featured_articles do |articles|
+    #       articles.select(&:featured?)
+    #     end
+    #
+    #   @param name [Symbol] name for the exposure
+    #   @macro exposure_options
+    #
+    # @overload expose(name, **options)
+    #   Define a value to be passed to the template, provided by an instance
+    #   method matching the name. The method's return value will be decorated by
+    #   a matching Part and passed to the template.
+    #
+    #   The method's parameters will determine what it is given:
+    #
+    #   - To receive other exposure values, provide positional parameters
+    #     matching the exposure names. These exposures will already by decorated
+    #     by their Parts.
+    #   - To receive the view's input arguments (whatever is passed to
+    #     `View#call`), provide matching keyword parameters. You can provide
+    #     default values for these parameters to make the corresponding input
+    #     keys optional
+    #   - To receive the Context object, provide a `context:` keyword parameter
+    #   - To receive the view's input arguments in their entirey, provide a
+    #     keywords splat parameter (i.e. `**input`)
+    #
+    #   @example Accessing input arguments
+    #     expose :article
+    #
+    #     def article(slug:)
+    #       article_repo.find_by_slug(slug)
+    #     end
+    #
+    #   @example Accessing other exposures
+    #     expose :articles
+    #     expose :featured_articles
+    #
+    #     def articles
+    #       article_repo.listing
+    #     end
+    #
+    #     def featured_articles
+    #       articles.select(&:featured?)
+    #     end
+    #
+    #   @param name [Symbol] name for the exposure
+    #   @macro exposure_options
+    #
+    # @overload expose(name, **options)
+    #   Define a single value to pass through from the input data (when there is
+    #   no instance method matching the `name`). This value will be decorated by
+    #   a matching Part and passed to the template.
+    #
+    #   @param name [Symbol] name for the exposure
+    #   @macro exposure_options
+    #   @option options [Boolean] :default a default value to provide if there is no matching
+    #     input data
+    #
+    # @overload expose(*names, **options)
+    #   Define multiple values to pass through from the input data (when there
+    #   is no instance methods matching their names). These values will be
+    #   decorated by matching Parts and passed through to the template.
+    #
+    #   The provided options will be applied to all the exposures.
+    #
+    #   @param names [Symbol] names for the exposures
+    #   @macro exposure_options
+    #   @option options [Boolean] :default a default value to provide if there is no matching
+    #     input data
+    #
+    # @see https://dry-rb.org/gems/dry-view/exposures/
+    #
+    # @api public
+    def self.expose(*names, **options, &block)
+      if names.length == 1
+        exposures.add(names.first, block, **options)
+      else
+        names.each do |name|
+          exposures.add(name, **options)
+        end
+      end
+    end
+
+    # @api public
+    def self.private_expose(*names, **options, &block)
+      expose(*names, **options, private: true, &block)
+    end
+
+    # Returns the defined exposures. These are unbound, since bound exposures
+    # are only created when initializing a View instance.
+    #
+    # @return [Exposures]
+    # @api private
+    def self.exposures
+      @exposures ||= Exposures.new
+    end
+
+    # @!endgroup
+
+    # @!group Scope
+
+    # Creates and assigns a scope for the current view.
+    #
+    # The newly created scope is useful to add custom logic that is specific
+    # to the view.
+    #
+    # The scope has access to locals, exposures, and inherited scope (if any)
+    #
+    # If the view already has an explicit scope the newly created scope will
+    # inherit from the explicit scope.
+    #
+    # There are two cases when this may happen:
+    #   1. The scope was explicitly assigned (e.g. `config.scope = MyScope`)
+    #   2. The scope has been inherited by the view superclass
+    #
+    # If the view doesn't have an already existing scope, the newly scope
+    # will inherit from `Hanami::View::Scope` by default.
+    #
+    # However, you can specify any base class for it. This is not
+    # recommended, unless you know what you're doing.
+    #
+    # @param scope [Hanami::View::Scope] the current scope (if any), or the
+    #   default base class will be `Hanami::View::Scope`
+    # @param block [Proc] the scope logic definition
+    #
+    # @api public
+    #
+    # @example Basic usage
+    #   class MyView < Hanami::View
+    #     config.scope = MyScope
+    #
+    #     scope do
+    #       def greeting
+    #         _locals[:message].upcase + "!"
+    #       end
+    #
+    #       def copyright(time)
+    #         "Copy #{time.year}"
+    #       end
+    #     end
+    #   end
+    #
+    #   # my_view.html.erb
+    #   # <%= greeting %>
+    #   # <%= copyright(Time.now.utc) %>
+    #
+    #   MyView.new.(message: "Hello") # => "HELLO!"
+    #
+    # @example Inherited scope
+    #   class MyScope < Hanami::View::Scope
+    #     private
+    #
+    #     def shout(string)
+    #       string.upcase + "!"
+    #     end
+    #   end
+    #
+    #   class MyView < Hanami::View
+    #     config.scope = MyScope
+    #
+    #     scope do
+    #       def greeting
+    #         shout(_locals[:message])
+    #       end
+    #
+    #       def copyright(time)
+    #         "Copy #{time.year}"
+    #       end
+    #     end
+    #   end
+    #
+    #   # my_view.html.erb
+    #   # <%= greeting %>
+    #   # <%= copyright(Time.now.utc) %>
+    #
+    #   MyView.new.(message: "Hello") # => "HELLO!"
+    def self.scope(scope_class = nil, &block)
+      scope_class ||= config.scope || config.scope_class
+
+      config.scope = Class.new(scope_class, &block)
+    end
+
+    # @!endgroup
+
+    # @api private
+    def self.layout_path
+      File.join(*[config.layouts_dir, config.layout].compact)
+    end
+
+    # @api private
+    def self.cache
+      Cache
+    end
+
+    # Returns an instance of the view. This binds the defined exposures to the
+    # view instance.
+    #
+    # Subclasses can define their own `#initialize` to accept injected
+    # dependencies, but must call `super()` to ensure the standard view
+    # initialization can proceed.
+    #
+    # @api public
+    def initialize
+      self.class.config.finalize!
+      ensure_config
+
+      @exposures = self.class.exposures.bind(self)
+    end
+
+    # The view's configuration
+    #
+    # @api private
+    def config
+      self.class.config
+    end
+
+    # The view's bound exposures
+    #
+    # @return [Exposures]
+    # @api private
+    def exposures
+      @exposures
+    end
+
+    # Render the view
+    #
+    # @param format [Symbol] template format to use
+    # @param context [Context] context object to use
+    # @param input input data for preparing exposure values
+    #
+    # @return [Rendered] rendered view object
+    # @api public
+    def call(format: config.default_format, context: config.default_context, **input)
+      rendering = self.rendering(format: format, context: context)
+
+      locals = locals(rendering, input)
+      output = rendering.template(config.template, rendering.scope(config.scope, locals))
+
+      if layout?
+        begin
+          output = rendering.template(
+            self.class.layout_path,
+            rendering.scope(config.scope, layout_locals(locals))
+          ) { output }
+        rescue TemplateNotFoundError
+          raise LayoutNotFoundError.new(config.layout, config.paths)
+        end
       end
+
+      Rendered.new(output: output, locals: locals)
     end
 
-    def self.application_provider(subclass)
-      if Hanami.respond_to?(:application?) && Hanami.application?
-        Hanami.application.component_provider(subclass)
+    def rendering(format: config.default_format, context: config.default_context)
+      Rendering.new(config: config, format: format, context: context)
+    end
+
+    private
+
+    def ensure_config
+      raise UndefinedConfigError, :paths unless Array(config.paths).any?
+      raise UndefinedConfigError, :template unless config.template
+    end
+
+    def locals(rendering, input)
+      exposures.(context: rendering.context, **input) do |value, exposure|
+        if exposure.decorate? && value
+          rendering.part(exposure.name, value, as: exposure.options[:as])
+        else
+          value
+        end
       end
     end
-    private_class_method :application_provider
+
+    def layout_locals(locals)
+      locals.each_with_object({}) do |(key, value), layout_locals|
+        layout_locals[key] = value if exposures[key].for_layout?
+      end
+    end
+
+    def layout?
+      !!config.layout # rubocop:disable Style/DoubleNegation
+    end
   end
 end