Class: Lotus::Controller::Configuration

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

Overview

Configuration for the framework, controllers and actions.

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

Every time that ‘Lotus::Controller` and `Lotus::Action` 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 controllers and single actions to specify exceptions.

Since:

  • 0.2.0

Constant Summary collapse

DEFAULT_ERROR_CODE =

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 HTTP code for server side errors

Since:

  • 0.2.0

500
DEFAULT_FORMATS =

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 Mime type to format mapping

Since:

  • 0.2.0

{
  'application/octet-stream' => :all,
  '*/*'                      => :all,
  'text/html'                => :html
}.freeze

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize ⇒ Lotus::Controller::Configuration

Initialize a configuration instance

Since:

  • 0.2.0



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

def initialize
  reset!
end

Instance Attribute Details

#action_module(value) ⇒ Object #action_module ⇒ Module

Specify which is the default action module to be included when we use the ‘Lotus::Controller.action` method.

This setting is useful when we use multiple instances of the framework in the same process, so we want to ensure that the actions will include ‘MyApp::Action`, rather than `AnotherApp::Action`.

If not set, the default value is ‘Lotus::Action`

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/controller'

Lotus::Controller.configuration.action_module # => Lotus::Action

Setting the value

require 'lotus/controller'

module MyAction
end

Lotus::Controller.configure do
  action_module MyAction
end

class DashboardController
  include Lotus::Controller

  # It includes MyAction, instead of Lotus::Action
  action 'Index' do
    def call(params)
      # ...
    end
  end
end

Duplicated framework

require 'lotus/controller'

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

  module Controllers::Dashboard
    include MyApp::Controller

    # It includes MyApp::Action, instead of Lotus::Action
    action 'Index' do
      def call(params)
        # ...
      end
    end
  end
end

Overloads:

  • #action_module(value) ⇒ Object

    Sets the given value

    Parameters:

    • value (Module) —

      the module to be included in all the actions

  • #action_module ⇒ Module

    Gets the value

    Returns:

    • (Module)

See Also:

  • Dsl#action
  • Lotus::Controller#duplicate

Since:

  • 0.2.0



268
269
270
271
272
273
274
 
# File 'lib/lotus/controller/configuration.rb', line 268

def action_module(value = nil)
  if value.nil?
    @action_module
  else
    @action_module = value
  end
end

#default_format(format) ⇒ Object #default_format ⇒ Symbol?

Set a format as default fallback for all the requests without a strict requirement for the mime type.

The given format must be coercible to a symbol, and be a valid mime type alias. If it isn’t, at the runtime the framework will raise a ‘Lotus::Controller::UnknownFormatError`.

By default this value is nil.

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/controller'

Lotus::Controller.configuration.default_format # => nil

Setting the value

require 'lotus/controller'

Lotus::Controller.configure do
  default_format :html
end

Overloads:

  • #default_format(format) ⇒ Object

    Sets the given value

    Parameters:

    • format (#to_sym) —

      the symbol format

    Raises:

    • (TypeError) —

      if it cannot be coerced to a symbol

  • #default_format ⇒ Symbol?

    Gets the value

    Returns:

    • (Symbol, nil)

See Also:

Since:

  • 0.2.0



431
432
433
434
435
436
437
 
# File 'lib/lotus/controller/configuration.rb', line 431

def default_format(format = nil)
  if format
    @default_format = Utils::Kernel.Symbol(format)
  else
    @default_format
  end
end

#handle_exceptions(value) ⇒ Object #handle_exceptions ⇒ TrueClass, FalseClass

Decide if handle exceptions with an HTTP status or let them uncaught

If this value is set to ‘true`, the configured exceptions will return the specified HTTP status, the rest of them with `500`.

If this value is set to ‘false`, the exceptions won’t be caught.

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/controller'

Lotus::Controller.configuration.handle_exceptions # => true

Setting the value

require 'lotus/controller'

Lotus::Controller.configure do
  handle_exceptions false
end

Overloads:

  • #handle_exceptions(value) ⇒ Object

    Sets the given value

    Parameters:

    • value (TrueClass, FalseClass) —

      true or false, default to true

  • #handle_exceptions ⇒ TrueClass, FalseClass

    Gets the value

    Returns:

    • (TrueClass, FalseClass)

See Also:

Since:

  • 0.2.0



151
152
153
154
155
156
157
 
# File 'lib/lotus/controller/configuration.rb', line 151

def handle_exceptions(value = nil)
  if value.nil?
    @handle_exceptions
  else
    @handle_exceptions = value
  end
end

#modules(blk) ⇒ Object #modules ⇒ Array

Specify the default modules to be included when ‘Lotus::Action` (or the `action_module`) is included. This also works with `Lotus::Controller.action`.

If not set, this option will be ignored.

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/controller'

Lotus::Controller.configuration.modules # => []

Setting the value

require 'lotus/controller'
require 'lotus/action/cookies'
require 'lotus/action/session'

Lotus::Controller.configure do
  modules do
    include Lotus::Action::Cookies
    include Lotus::Action::Session
  end
end

class DashboardController
  include Lotus::Controller

  # It includes:
  #   * Lotus::Action
  #   * Lotus::Action::Cookies
  #   * Lotus::Action::Session
  action 'Index' do
    def call(params)
      # ...
    end
  end
end

Overloads:

  • #modules(blk) ⇒ Object

    Adds the given block

    Parameters:

    • value (Proc) —

      specify the modules to be included

  • #modules ⇒ Array

    Gets the value

    Returns:

    • (Array) —

      the list of the specified procs

See Also:

  • Dsl#action
  • Lotus::Controller#duplicate

Since:

  • 0.2.0



329
330
331
332
333
334
335
 
# File 'lib/lotus/controller/configuration.rb', line 329

def modules(&blk)
  if block_given?
    @modules.push(blk)
  else
    @modules
  end
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 a copy of the configuration of the framework instance associated with the given class.

When multiple instances of Lotus::Controller 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/controller'

class Show
  include Lotus::Action
end

Lotus::Controller::Configuration.for(Show)
  # => will duplicate from Lotus::Controller

Multiple instances of the framework

require 'lotus/controller'

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

  module Controllers::Dashboard
    include MyApp::Controller

    action 'Index' do
      def call(params)
        # ...
      end
    end
  end
end

class Show
  include Lotus::Action
end

Lotus::Controller::Configuration.for(Show)
  # => will duplicate from Lotus::Controller

Lotus::Controller::Configuration.for(MyApp::Controllers::Dashboard)
  # => will duplicate from MyApp::Controller

Parameters:

  • base (Class, Module) —

    a controller or an action

Returns:

Since:

  • 0.2.0



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

def self.for(base)
  namespace = Utils::String.new(base).namespace
  framework = Utils::Class.load!("(#{namespace}|Lotus)::Controller")
  framework.configuration.duplicate
end

Instance Method Details

#duplicate ⇒ 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.

Duplicate by copying the settings in a new instance.

Returns:

Since:

  • 0.2.0



468
469
470
471
472
473
474
475
476
477
 
# File 'lib/lotus/controller/configuration.rb', line 468

def duplicate
  Configuration.new.tap do |c|
    c.handle_exceptions  = handle_exceptions
    c.handled_exceptions = handled_exceptions.dup
    c.action_module      = action_module
    c.modules            = modules.dup
    c.formats            = formats.dup
    c.default_format     = default_format
  end
end

#exception_code(exception) ⇒ 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.

Return the HTTP status for the given exception

Raised exceptions will return the configured HTTP status, only if

`handled_exceptions` is set on `true`.

Parameters:

  • exception (Hash) —

    the exception class must be the key and the HTTP status the value of the hash

See Also:

Since:

  • 0.2.0



195
196
197
 
# File 'lib/lotus/controller/configuration.rb', line 195

def exception_code(exception)
  @handled_exceptions.fetch(exception) { DEFAULT_ERROR_CODE }
end

#format(hash) ⇒ Object

Register a format

Examples:

require 'lotus/controller'

Lotus::Controller.configure do
  format custom: 'application/custom'
end

class ArticlesController
  include Lotus::Controller

  action 'Index' do
    def call(params)
      # ...
    end
  end

  action 'Show' do
    def call(params)
      # ...
      self.format = :custom
    end
  end
end

action = ArticlesController::Index.new

action.call({ 'HTTP_ACCEPT' => 'text/html' })
  # => Content-Type "text/html"
action.format # => :html

action.call({ 'HTTP_ACCEPT' => 'application/custom' })
  # => Content-Type "application/custom"
action.format # => :custom

action = ArticlesController::Show.new

action.call({ 'HTTP_ACCEPT' => 'text/html' })
  # => Content-Type "application/custom"
action.format # => :custom

Parameters:

  • hash (Hash) —

    the symbol format must be the key and the mime type string must be the value of the hash

See Also:

Since:

  • 0.2.0



387
388
389
390
391
392
 
# File 'lib/lotus/controller/configuration.rb', line 387

def format(hash)
  symbol, mime_type = *Utils::Kernel.Array(hash)

  @formats.merge! Utils::Kernel.String(mime_type) =>
    Utils::Kernel.Symbol(symbol)
end

#format_for(mime_type) ⇒ Symbol?

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.

Returns a format for the given mime type

Parameters:

  • mime_type (#to_s, #to_str) —

    A mime type

Returns:

  • (Symbol, nil) —

    the corresponding format, if present

See Also:

Since:

  • 0.2.0



449
450
451
 
# File 'lib/lotus/controller/configuration.rb', line 449

def format_for(mime_type)
  @formats[mime_type]
end

#handle_exception(exception) ⇒ Object

Specify how to handle an exception with an HTTP status

Raised exceptions will return the configured HTTP status, only if

`handled_exceptions` is set on `true`.

Examples:

require 'lotus/controller'

Lotus::Controller.configure do
  handle_exception ArgumentError => 400
end

Parameters:

  • exception (Hash) —

    the exception class must be the key and the HTTP status the value

See Also:

Since:

  • 0.2.0



179
180
181
 
# File 'lib/lotus/controller/configuration.rb', line 179

def handle_exception(exception)
  @handled_exceptions.merge!(exception)
end

#load!(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.

Load the configuration for the given action

Since:

  • 0.2.0



496
497
498
499
500
 
# File 'lib/lotus/controller/configuration.rb', line 496

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

#mime_type_for(format) ⇒ String?

Returns a mime type for the given format

Parameters:

  • format (#to_sym) —

    a format

Returns:

  • (String, nil) —

    the corresponding mime type, if present

Since:

  • 0.2.0



458
459
460
 
# File 'lib/lotus/controller/configuration.rb', line 458

def mime_type_for(format)
  @formats.key(format)
end

#reset! ⇒ 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.

Reset all the values to the defaults

Since:

  • 0.2.0



483
484
485
486
487
488
489
490
 
# File 'lib/lotus/controller/configuration.rb', line 483

def reset!
  @handle_exceptions  = true
  @handled_exceptions = {}
  @modules            = []
  @formats            = DEFAULT_FORMATS.dup
  @default_format     = nil
  @action_module      = ::Lotus::Action
end