Class: Lotus::View::Configuration

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

Overview

Configuration for the framework, controllers and actions.

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

Every time that ‘Lotus::View` and `Lotus::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 ⇒ Lotus::View::Configuration

Initialize a configuration instance

Since:

  • 0.2.0



102
103
104
105
 
# File 'lib/lotus/view/configuration.rb', line 102

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 'lotus/view'

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

Set UTF-8 As An Encoding Constant

require 'lotus/view'

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

Raise An Error For Unknown Encoding

require 'lotus/view'

Lotus::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



287
288
289
290
291
292
293
 
# File 'lib/lotus/view/configuration.rb', line 287

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 `Lotus::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 'lotus/view'

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

Setting the value

require 'lotus/view'

Lotus::View.configure do
  layout :application
end

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

Setting the value in a namespaced app

require 'lotus/view'

module MyApp
  View = Lotus::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



238
239
240
241
242
243
244
 
# File 'lib/lotus/view/configuration.rb', line 238

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

#layouts ⇒ Object (readonly)

Since:

  • 0.2.0



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

def layouts
  @layouts
end

#load_paths ⇒ Object

Since:

  • 0.2.0



38
39
40
 
# File 'lib/lotus/view/configuration.rb', line 38

def load_paths
  @load_paths
end

#modules ⇒ Object

Since:

  • 0.2.0



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

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 'lotus/view'

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

Setting the value

require 'lotus/view'

Lotus::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



140
141
142
143
144
145
146
 
# File 'lib/lotus/view/configuration.rb', line 140

def namespace(value = nil)
  if value
    @namespace = value
  else
    @namespace
  end
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 'lotus/view'

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

Setting the value

require 'lotus/view'

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

Lotus::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



185
186
187
188
189
190
191
 
# File 'lib/lotus/view/configuration.rb', line 185

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

#views ⇒ Object (readonly)

Since:

  • 0.2.0



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

def views
  @views
end

Class Method Details

.for(base) ⇒ Lotus::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 Lotus::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 'lotus/view'

class Show
  include Lotus::View
end

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

Multiple instances of the framework

require 'lotus/view'

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

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

class Show
  include Lotus::Action
end

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

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

Parameters:

  • base (Class) —

    a view or a layout

Returns:

  • (Lotus::Controller::Configuration) —

    the configuration associated to the given class.

Since:

  • 0.2.0



90
91
92
93
94
95
 
# File 'lib/lotus/view/configuration.rb', line 90

def self.for(base)
  # TODO this implementation is similar to Lotus::Controller::Configuration consider to extract it into Lotus::Utils
  namespace = Utils::String.new(base).namespace
  framework = Utils::Class.load_from_pattern!("(#{namespace}|Lotus)::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



393
394
395
 
# File 'lib/lotus/view/configuration.rb', line 393

def add_layout(layout)
  @layouts.add(layout)
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



385
386
387
 
# File 'lib/lotus/view/configuration.rb', line 385

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



447
448
449
450
451
 
# File 'lib/lotus/view/configuration.rb', line 447

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

#duplicate ⇒ Lotus::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



403
404
405
406
407
408
409
410
411
412
 
# File 'lib/lotus/view/configuration.rb', line 403

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

#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



418
419
420
421
422
 
# File 'lib/lotus/view/configuration.rb', line 418

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

#prepare(&blk) ⇒ void

This method returns an undefined value.

Prepare the views.

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

This method can be called multiple times.

Examples:

Including shared utilities

require 'lotus/view'

module UrlHelpers
  def comments_path
    '/'
  end
end

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

Lotus::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 Lotus::View

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

Preparing multiple times

require 'lotus/view'

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

  prepare do
    format :json
  end
end

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

Lotus::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 Lotus::View
  end
end

Parameters:

  • blk (Proc) —

    the code block

Raises:

  • (ArgumentError) —

    if called without passing a block

See Also:

Since:

  • 0.3.0



373
374
375
376
377
378
379
 
# File 'lib/lotus/view/configuration.rb', line 373

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



428
429
430
431
432
433
434
435
436
437
 
# File 'lib/lotus/view/configuration.rb', line 428

def reset!
  root             DEFAULT_ROOT
  default_encoding DEFAULT_ENCODING

  @views      = Set.new
  @layouts    = Set.new
  @load_paths = Utils::LoadPaths.new(root)
  @layout     = nil
  @modules    = []
end