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

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



96
97
98
99
 
# File 'lib/lotus/view/configuration.rb', line 96

def initialize
  @namespace = Object
  reset!
end

Instance Attribute Details

#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



232
233
234
235
236
237
238
 
# File 'lib/lotus/view/configuration.rb', line 232

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

#layouts ⇒ Object (readonly)

Since:

  • 0.2.0



34
35
36
 
# File 'lib/lotus/view/configuration.rb', line 34

def layouts
  @layouts
end

#load_paths ⇒ Object

Since:

  • 0.2.0



32
33
34
 
# File 'lib/lotus/view/configuration.rb', line 32

def load_paths
  @load_paths
end

#modules ⇒ Object

Since:

  • 0.2.0



35
36
37
 
# File 'lib/lotus/view/configuration.rb', line 35

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



134
135
136
137
138
139
140
 
# File 'lib/lotus/view/configuration.rb', line 134

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



179
180
181
182
183
184
185
 
# File 'lib/lotus/view/configuration.rb', line 179

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

#views ⇒ Object (readonly)

Since:

  • 0.2.0



33
34
35
 
# File 'lib/lotus/view/configuration.rb', line 33

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



84
85
86
87
88
89
 
# File 'lib/lotus/view/configuration.rb', line 84

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



338
339
340
 
# File 'lib/lotus/view/configuration.rb', line 338

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



330
331
332
 
# File 'lib/lotus/view/configuration.rb', line 330

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



390
391
392
393
394
 
# File 'lib/lotus/view/configuration.rb', line 390

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



348
349
350
351
352
353
354
355
356
 
# File 'lib/lotus/view/configuration.rb', line 348

def duplicate
  Configuration.new.tap do |c|
    c.namespace  = namespace
    c.root       = root
    c.layout     = @layout # lazy loading of the class
    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



362
363
364
365
366
 
# File 'lib/lotus/view/configuration.rb', line 362

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



318
319
320
321
322
323
324
 
# File 'lib/lotus/view/configuration.rb', line 318

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



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

def reset!
  root(DEFAULT_ROOT)

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