class Dry::View
A standalone, template-based view rendering system that offers everything you need to write well-factored view code.
This represents a single view, holding the configuration and exposures necessary for rendering its template.
@abstract Subclass this and provide your own configuration and exposures to
define your own view (along with a custom `#initialize` if you wish to inject dependencies into your subclass)
@see dry-rb.org/gems/dry-view/
@api public
Constants
- DEFAULT_RENDERER_OPTIONS
@api private
- VERSION
@api private
Attributes
The view's bound exposures
@return [Exposures] @api private
Public Class Methods
@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 dry-rb.org/gems/dry-view/exposures/
@api public
# File lib/dry/view.rb, line 338 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
Returns the defined exposures. These are unbound, since bound exposures are only created when initializing a View
instance.
@return [Exposures] @api private
# File lib/dry/view.rb, line 358 def self.exposures @exposures ||= Exposures.new end
@api private
# File lib/dry/view.rb, line 221 def self.inherited(klass) super exposures.each do |name, exposure| klass.exposures.import(name, exposure) end end
@overload layout_env
(format: config.default_format, context: config.default_context)
Returns a render environment for the view and the given options, chdir'ed into the view's layout directory. This is the environment used when rendering the view's layout. @param format [Symbol] template format to use (defaults to the `default_format` setting) @param context [Context] context object to use (defaults to the `default_context` setting) @return [RenderEnvironment] @api public
# File lib/dry/view.rb, line 405 def self.layout_env(**args) render_env(**args).chdir(layout_path) end
@api private
# File lib/dry/view.rb, line 424 def self.layout_path File.join(config.layouts_dir, config.layout) 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
# File lib/dry/view.rb, line 444 def initialize @exposures = self.class.exposures.bind(self) end
@api public
# File lib/dry/view.rb, line 349 def self.private_expose(*names, **options, &block) expose(*names, **options, private: true, &block) end
Returns a render environment for the view and the given options. This environment isn't chdir'ed into any particular directory.
@param format [Symbol] template format to use (defaults to the `default_format` setting) @param context [Context] context object to use (defaults to the `default_context` setting)
@see View.template_env
render environment for the view's template @see View.layout_env
render environment for the view's layout
@return [RenderEnvironment] @api public
# File lib/dry/view.rb, line 377 def self.render_env(format: config.default_format, context: config.default_context) RenderEnvironment.prepare(renderer(format), config, context) end
Returns renderer for the view and provided format
@api private
# File lib/dry/view.rb, line 412 def self.renderer(format) fetch_or_store(:renderer, config, format) { Renderer.new( config.paths, format: format, engine_mapping: config.renderer_engine_mapping, **config.renderer_options ) } end
@overload template_env
(format: config.default_format, context: config.default_context)
Returns a render environment for the view and the given options, chdir'ed into the view's template directory. This is the environment used when rendering the template, and is useful to to fetch independently when unit testing Parts and Scopes. @param format [Symbol] template format to use (defaults to the `default_format` setting) @param context [Context] context object to use (defaults to the `default_context` setting) @return [RenderEnvironment] @api public
# File lib/dry/view.rb, line 392 def self.template_env(**args) render_env(**args).chdir(config.template) end
Public Instance Methods
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
# File lib/dry/view.rb, line 463 def call(format: config.default_format, context: config.default_context, **input) ensure_config env = self.class.render_env(format: format, context: context) template_env = self.class.template_env(format: format, context: context) locals = locals(template_env, input) output = env.template(config.template, template_env.scope(config.scope, locals)) if layout? layout_env = self.class.layout_env(format: format, context: context) output = env.template( self.class.layout_path, layout_env.scope(config.scope, layout_locals(locals)) ) { output } end Rendered.new(output: output, locals: locals) end
The view's configuration
@api private
# File lib/dry/view.rb, line 451 def config self.class.config end
Private Instance Methods
@api private
# File lib/dry/view.rb, line 486 def ensure_config raise UndefinedConfigError, :paths unless Array(config.paths).any? raise UndefinedConfigError, :template unless config.template end
@api private
# File lib/dry/view.rb, line 510 def layout? !!config.layout # rubocop:disable Style/DoubleNegation end
@api private
# File lib/dry/view.rb, line 503 def layout_locals(locals) locals.each_with_object({}) do |(key, value), layout_locals| layout_locals[key] = value if exposures[key].for_layout? end end
@api private
# File lib/dry/view.rb, line 492 def locals(render_env, input) exposures.(context: render_env.context, **input) do |value, exposure| if exposure.decorate? && value render_env.part(exposure.name, value, **exposure.options) else value end end end