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

exposures[R]

The view's bound exposures

@return [Exposures] @api private

Public Class Methods

expose(*names, **options, &block) click to toggle source

@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
exposures() click to toggle source

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
inherited(klass) click to toggle source

@api private

Calls superclass method
# File lib/dry/view.rb, line 221
def self.inherited(klass)
  super
  exposures.each do |name, exposure|
    klass.exposures.import(name, exposure)
  end
end
layout_env(**args) click to toggle source

@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
layout_path() click to toggle source

@api private

# File lib/dry/view.rb, line 424
def self.layout_path
  File.join(config.layouts_dir, config.layout)
end
new() click to toggle source

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
private_expose(*names, **options, &block) click to toggle source

@api public

# File lib/dry/view.rb, line 349
def self.private_expose(*names, **options, &block)
  expose(*names, **options, private: true, &block)
end
render_env(format: config.default_format, context: config.default_context) click to toggle source

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
renderer(format) click to toggle source

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
template_env(**args) click to toggle source

@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

call(format: config.default_format, context: config.default_context, **input) click to toggle source

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
config() click to toggle source

The view's configuration

@api private

# File lib/dry/view.rb, line 451
def config
  self.class.config
end

Private Instance Methods

ensure_config() click to toggle source

@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
layout?() click to toggle source

@api private

# File lib/dry/view.rb, line 510
def layout?
  !!config.layout # rubocop:disable Style/DoubleNegation
end
layout_locals(locals) click to toggle source

@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
locals(render_env, input) click to toggle source

@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