Class: Hanami::View::Configuration

Inherits:
Object
  • Object
show all
Defined in:
lib/hanami/view/configuration.rb

Overview

Configuration for the framework, controllers and actions.

Hanami::Controller has its own global configuration that can be manipulated via ‘Hanami::View.configure`.

Every time that ‘Hanami::View` and `Hanami::Layout` are included, that global configuration is being copied to the recipient. The copy will inherit all the settings from the original, but all the subsequent changes aren’t reflected from the parent to the children, and viceversa.

This architecture allows to have a global configuration that capture the most common cases for an application, and let views and layouts layouts to specify exceptions.

Since:

  • 0.2.0

Constant Summary collapse

DEFAULT_ROOT =

This constant is part of a private API. You should avoid using this constant if possible, as it may be removed or be changed in the future.

Default root

Since:

  • 0.2.0

'.'.freeze
DEFAULT_ENCODING =

This constant is part of a private API. You should avoid using this constant if possible, as it may be removed or be changed in the future.

Default encoding

Since:

  • 0.5.0

Encoding::UTF_8

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize ⇒ Hanami::View::Configuration

Initialize a configuration instance

Since:

  • 0.2.0



104
105
106
107
 
# File 'lib/hanami/view/configuration.rb', line 104

def initialize
  @namespace = Object
  reset!
end

Instance Attribute Details

#default_encoding(value) ⇒ Object #default_encoding ⇒ Encoding

Default encoding for templates

This is part of a DSL, for this reason when this method is called with an argument, it will set the corresponding instance variable. When called without, it will return the already set value, or the default.

Examples:

Set UTF-8 As A String

require 'hanami/view'

Hanami::View.configure do
  default_encoding 'utf-8'
end

Set UTF-8 As An Encoding Constant

require 'hanami/view'

Hanami::View.configure do
  default_encoding Encoding::UTF_8
end

Raise An Error For Unknown Encoding

require 'hanami/view'

Hanami::View.configure do
  default_encoding 'foo'
end

  # => ArgumentError

Overloads:

  • #default_encoding(value) ⇒ Object

    Sets the given value

    Parameters:

    • value (String, Encoding) —

      a string representation of the encoding, or an Encoding constant

    Raises:

    • (ArgumentError) —

      if the given value isn’t a supported encoding

  • #default_encoding ⇒ Encoding

    Gets the value

    Returns:

    • (Encoding)

Since:

  • 0.5.0



289
290
291
292
293
294
295
 
# File 'lib/hanami/view/configuration.rb', line 289

def default_encoding(value = nil)
  if value.nil?
    @default_encoding
  else
    @default_encoding = Encoding.find(value)
  end
end

#layout(value) ⇒ Object #layout ⇒ Class

Set the global layout

If not set, this value defaults to ‘nil`, while at the rendering time it will use `Hanami::View::Rendering::NullLayout`.

This is part of a DSL, for this reason when this method is called with an argument, it will set the corresponding instance variable. When called without, it will return the already set value, or the default.

Examples:

Getting the value

require 'hanami/view'

Hanami::View.configuration.layout # => nil

Setting the value

require 'hanami/view'

Hanami::View.configure do
  layout :application
end

Hanami::View.configuration.layout # => ApplicationLayout

Setting the value in a namespaced app

require 'hanami/view'

module MyApp
  View = Hanami::View.duplicate(self) do
    layout :application
  end
end

MyApp::View.configuration.layout # => MyApp::ApplicationLayout

Overloads:

  • #layout(value) ⇒ Object

    Sets the given value

    Parameters:

    • value (Symbol) —

      the name of the layout

  • #layout ⇒ Class

    Gets the value

    Returns:

    • (Class)

See Also:

Since:

  • 0.2.0



240
241
242
243
244
245
246
 
# File 'lib/hanami/view/configuration.rb', line 240

def layout(value = nil)
  if value.nil?
    Rendering::LayoutFinder.find(@layout, @namespace)
  else
    @layout = value
  end
end

#layouts ⇒ Object (readonly)

Since:

  • 0.2.0



41
42
43
 
# File 'lib/hanami/view/configuration.rb', line 41

def layouts
  @layouts
end

#load_paths ⇒ Object

Since:

  • 0.2.0



39
40
41
 
# File 'lib/hanami/view/configuration.rb', line 39

def load_paths
  @load_paths
end

#modules ⇒ Object

Since:

  • 0.2.0



42
43
44
 
# File 'lib/hanami/view/configuration.rb', line 42

def modules
  @modules
end

#namespace(value) ⇒ Object #namespace ⇒ Class, ...

Set the Ruby namespace where to lookup for views.

When multiple instances of the framework are used, we want to make sure that if a ‘MyApp` wants a `Dashboard::Index` view, we are loading the right one.

If not set, this value defaults to ‘Object`.

This is part of a DSL, for this reason when this method is called with an argument, it will set the corresponding instance variable. When called without, it will return the already set value, or the default.

Examples:

Getting the value

require 'hanami/view'

Hanami::View.configuration.namespace # => Object

Setting the value

require 'hanami/view'

Hanami::View.configure do
  namespace 'MyApp::Views'
end

Overloads:

  • #namespace(value) ⇒ Object

    Sets the given value

    Parameters:

    • value (Class, Module, String) —

      a valid Ruby namespace identifier

  • #namespace ⇒ Class, ...

    Gets the value

    Returns:

    • (Class, Module, String)

Since:

  • 0.2.0



142
143
144
145
146
147
148
 
# File 'lib/hanami/view/configuration.rb', line 142

def namespace(value = nil)
  if value
    @namespace = value
  else
    @namespace
  end
end

#partials ⇒ Object (readonly)

Since:

  • 0.2.0



43
44
45
 
# File 'lib/hanami/view/configuration.rb', line 43

def partials
  @partials
end

#root(value) ⇒ Object #root ⇒ Pathname

Set the root path where to search for templates

If not set, this value defaults to the current directory.

This is part of a DSL, for this reason when this method is called with an argument, it will set the corresponding instance variable. When called without, it will return the already set value, or the default.

Examples:

Getting the value

require 'hanami/view'

Hanami::View.configuration.root # => #<Pathname:.>

Setting the value

require 'hanami/view'

Hanami::View.configure do
  root '/path/to/templates'
end

Hanami::View.configuration.root # => #<Pathname:/path/to/templates>

Overloads:

  • #root(value) ⇒ Object

    Sets the given value

    Parameters:

    • value (String, Pathname, #to_pathname) —

      an object that can be coerced to Pathname

    Raises:

    • (Errno::ENOENT) —

      if the given path doesn’t exist

  • #root ⇒ Pathname

    Gets the value

    Returns:

    • (Pathname)

See Also:

Since:

  • 0.2.0



187
188
189
190
191
192
193
 
# File 'lib/hanami/view/configuration.rb', line 187

def root(value = nil)
  if value
    @root = Utils::Kernel.Pathname(value).realpath
  else
    @root
  end
end

#views ⇒ Object (readonly)

Since:

  • 0.2.0



40
41
42
 
# File 'lib/hanami/view/configuration.rb', line 40

def views
  @views
end

Class Method Details

.for(base) ⇒ Hanami::Controller::Configuration

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Return the original configuration of the framework instance associated with the given class.

When multiple instances of Hanami::View are used in the same application, we want to make sure that a controller or an action will receive the expected configuration.

Examples:

Direct usage of the framework

require 'hanami/view'

class Show
  include Hanami::View
end

Hanami::View::Configuration.for(Show)
  # => will return from Hanami::View

Multiple instances of the framework

require 'hanami/view'

module MyApp
  View = Hanami::View.duplicate(self)

  module Views::Dashboard
    class Index
      include MyApp::View
    end
  end
end

class Show
  include Hanami::Action
end

Hanami::View::Configuration.for(Show)
  # => will return from Hanami::View

Hanami::View::Configuration.for(MyApp::Views::Dashboard::Index)
  # => will return from MyApp::View

Parameters:

  • base (Class) —

    a view or a layout

Returns:

  • (Hanami::Controller::Configuration) —

    the configuration associated to the given class.

Since:

  • 0.2.0



92
93
94
95
96
97
 
# File 'lib/hanami/view/configuration.rb', line 92

def self.for(base)
  # TODO this implementation is similar to Hanami::Controller::Configuration consider to extract it into Hanami::Utils
  namespace = Utils::String.namespace(base)
  framework = Utils::Class.load("#{namespace}::View") || Utils::Class.load!('Hanami::View')
  framework.configuration
end

Instance Method Details

#add_layout(layout) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Add a layout to the registry

Since:

  • 0.2.0



395
396
397
 
# File 'lib/hanami/view/configuration.rb', line 395

def add_layout(layout)
  @layouts.add(layout)
end

#add_partial(partial) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Add a partial to the registry

Since:

  • 0.7.0



452
453
454
 
# File 'lib/hanami/view/configuration.rb', line 452

def add_partial(partial)
  @partials[partial.key][partial.format.to_sym] = partial.template
end

#add_view(view) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Add a view to the registry

Since:

  • 0.2.0



387
388
389
 
# File 'lib/hanami/view/configuration.rb', line 387

def add_view(view)
  @views.add(view)
end

#copy!(base) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Copy the configuration for the given action

Parameters:

  • base (Class) —

    the target action

Returns:

  • void

Since:

  • 0.3.0



480
481
482
483
484
 
# File 'lib/hanami/view/configuration.rb', line 480

def copy!(base)
  modules.each do |mod|
    base.class_eval(&mod)
  end
end

#duplicate ⇒ Hanami::View::Configuration

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Duplicate by copying the settings in a new instance.

Returns:

Since:

  • 0.2.0



405
406
407
408
409
410
411
412
413
414
 
# File 'lib/hanami/view/configuration.rb', line 405

def duplicate
  Configuration.new.tap do |c|
    c.namespace        = namespace
    c.root             = root
    c.layout           = @layout # lazy loading of the class
    c.default_encoding = default_encoding
    c.load_paths       = load_paths.dup
    c.modules          = modules.dup
  end
end

#find_partial(relative_partial_path, template_name, format) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Load partials for each partial template file found under the given load paths

Since:

  • 0.7.0



443
444
445
446
 
# File 'lib/hanami/view/configuration.rb', line 443

def find_partial(relative_partial_path, template_name, format)
  partials_for_view = partials.has_key?(relative_partial_path) ?  partials[relative_partial_path] : partials[template_name]
  partials_for_view ? partials_for_view[format.to_sym] : nil
end

#load! ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Load the configuration for the current framework

Since:

  • 0.2.0



420
421
422
423
424
425
 
# File 'lib/hanami/view/configuration.rb', line 420

def load!
  views.each   { |v| v.__send__(:load!) }
  layouts.each { |l| l.__send__(:load!) }
  load_partials!
  freeze
end

#load_partials! ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Load partials for each partial template file found under the given load paths

Since:

  • 0.7.0



432
433
434
435
436
 
# File 'lib/hanami/view/configuration.rb', line 432

def load_partials!
  Hanami::View::Rendering::PartialTemplatesFinder.new(self).find.each do |partial|
    add_partial(partial)
  end
end

#prepare(&blk) ⇒ void

This method returns an undefined value.

Prepare the views.

The given block will be yielded when ‘Hanami::View` will be included by a view.

This method can be called multiple times.

Examples:

Including shared utilities

require 'hanami/view'

module UrlHelpers
  def comments_path
    '/'
  end
end

Hanami::View.configure do
  prepare do
    include UrlHelpers
  end
end

Hanami::View.load!

module Comments
  class New
    # The following include will cause UrlHelpers to be included too.
    # This makes `comments_path` available in the view context
    include Hanami::View

    def form
      %(<form action="#{ comments_path }" method="POST"></form>)
    end
  end
end

Preparing multiple times

require 'hanami/view'

Hanami::View.configure do
  prepare do
    include UrlHelpers
  end

  prepare do
    format :json
  end
end

Hanami::View.configure do
  prepare do
    include FormattingHelpers
  end
end

Hanami::View.load!

module Articles
  class Index
    # The following include will cause the inclusion of:
    #   * UrlHelpers
    #   * FormattingHelpers
    #
    # It also sets the view to render only JSON
    include Hanami::View
  end
end

Parameters:

  • blk (Proc) —

    the code block

Raises:

  • (ArgumentError) —

    if called without passing a block

See Also:

Since:

  • 0.3.0



375
376
377
378
379
380
381
 
# File 'lib/hanami/view/configuration.rb', line 375

def prepare(&blk)
  if block_given?
    @modules.push(blk)
  else
    raise ArgumentError.new('Please provide a block')
  end
end

#reset! ⇒ Object Also known as: unload!

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Reset all the values to the defaults

Since:

  • 0.2.0



460
461
462
463
464
465
466
467
468
469
470
 
# File 'lib/hanami/view/configuration.rb', line 460

def reset!
  root             DEFAULT_ROOT
  default_encoding DEFAULT_ENCODING

  @partials   = Hash.new { |h, k| h[k] = Hash.new }
  @views      = Set.new
  @layouts    = Set.new
  @load_paths = Utils::LoadPaths.new(root)
  @layout     = nil
  @modules    = []
end