Module: Hanami::Controller

Includes:

Utils::ClassAttribute

Defined in:

lib/hanami/controller.rb,
lib/hanami/controller/error.rb,
lib/hanami/controller/version.rb,
lib/hanami/action/exposable/guard.rb,
lib/hanami/controller/configuration.rb

Overview

A set of logically grouped actions

Examples:

require 'hanami/controller'

module Articles
  class Index
    include Hanami::Action

    # ...
  end

  class Show
    include Hanami::Action

    # ...
  end
end

See Also:

• Action

Since:

• 0.1.0

Defined Under Namespace

Classes: Configuration, Error, IllegalExposureError, UnknownFormatError

Constant Summary

VERSION =

Defines the version

Since:

• 0.1.0

'1.0.0'.freeze

Class Method Summary

• .configure(&blk) ⇒ Object

  Configure the framework.

• .dupe ⇒ Module private

  Duplicate Hanami::Controller in order to create a new separated instance of the framework.

• .duplicate(mod, controllers = 'Controllers', &blk) ⇒ Module

  Duplicate the framework and generate modules for the target application.

• .load! ⇒ void

  Framework loading entry point.

Class Method Details

.configure(&blk) ⇒ Object

Configure the framework. It yields the given block in the context of the configuration

Examples:

require 'hanami/controller'

Hanami::Controller.configure do
  handle_exceptions false
end

Parameters:

• blk (Proc) —

  the configuration block

See Also:

• Configuration

Since:

• 0.2.0

# File 'lib/hanami/controller.rb', line 74

def self.configure(&blk)
  configuration.instance_eval(&blk)
end

.dupe ⇒ Module

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 Hanami::Controller in order to create a new separated instance of the framework.

The new instance of the framework will be completely decoupled from the original. It will inherit the configuration, but all the changes that happen after the duplication, won’t be reflected on the other copies.

Examples:

Basic usage

require 'hanami/controller'

module MyApp
  Controller = Hanami::Controller.dupe
end

MyApp::Controller == Hanami::Controller # => false

MyApp::Controller.configuration ==
  Hanami::Controller.configuration # => false

Inheriting configuration

require 'hanami/controller'

Hanami::Controller.configure do
  handle_exceptions false
end

module MyApp
  Controller = Hanami::Controller.dupe
end

module MyApi
  Controller = Hanami::Controller.dupe
  Controller.configure do
    handle_exceptions true
  end
end

Hanami::Controller.configuration.handle_exceptions # => false
MyApp::Controller.configuration.handle_exceptions # => false
MyApi::Controller.configuration.handle_exceptions # => true

Returns:

• (Module) —

  a copy of Hanami::Controller

Since:

• 0.2.0

# File 'lib/hanami/controller.rb', line 123

def self.dupe
  dup.tap do |duplicated|
    duplicated.configuration = configuration.duplicate
  end
end

.duplicate(mod, controllers = 'Controllers', &blk) ⇒ Module

Duplicate the framework and generate modules for the target application

module MyApp::Controllers::Dashboard
  include MyApp::Controller

  action 'Index' do # this will inject MyApp::Action
    def call(params)
      # ...
    end
  end
end

Examples:

Basic usage

require 'hanami/controller'

module MyApp
  Controller = Hanami::Controller.duplicate(self)
end

# It will:
#
# 1. Generate MyApp::Controller
# 2. Generate MyApp::Action
# 3. Generate MyApp::Controllers
# 4. Configure MyApp::Action as the default module for actions

Compare code

require 'hanami/controller'

module MyApp
  Controller = Hanami::Controller.duplicate(self) do
    # ...
  end
end

# it's equivalent to:

module MyApp
  Controller = Hanami::Controller.dupe
  Action     = Hanami::Action.dup

  module Controllers
  end

  Controller.configure do
    action_module MyApp::Action
  end

  Controller.configure do
    # ...
  end
end

Custom controllers module

require 'hanami/controller'

module MyApp
  Controller = Hanami::Controller.duplicate(self, 'Ctrls')
end

defined?(MyApp::Controllers) # => nil
defined?(MyApp::Ctrls)       # => "constant"

# Developers can namespace controllers under Ctrls
module MyApp::Ctrls::Dashboard
  # ...
end

Nil controllers module

require 'hanami/controller'

module MyApp
  Controller = Hanami::Controller.duplicate(self, nil)
end

defined?(MyApp::Controllers) # => nil

# Developers can namespace controllers under MyApp
module MyApp::DashboardController
  # ...
end

Block usage

require 'hanami/controller'

module MyApp
  Controller = Hanami::Controller.duplicate(self) do
    handle_exceptions false
  end
end

Hanami::Controller.configuration.handle_exceptions # => true
MyApp::Controller.configuration.handle_exceptions # => false

Parameters:

• mod (Module) —

  the Ruby namespace of the application

• controllers (String) (defaults to: 'Controllers') —

  the optional namespace where the application’s controllers will live

• blk (Proc) —

  an optional block to configure the framework

Returns:

• (Module) —

  a copy of Hanami::Controller

See Also:

• #dupe
• Configuration
• Hanami::Controller::Configuration#action_module

Since:

• 0.2.0

# File 'lib/hanami/controller.rb', line 235

def self.duplicate(mod, controllers = 'Controllers', &blk)
  dupe.tap do |duplicated|
    mod.module_eval %{ module #{ controllers }; end } if controllers
    mod.module_eval %{ Action = Hanami::Action.dup }

    duplicated.module_eval %{
      configure do
        action_module #{ mod }::Action
      end
    }

    duplicated.configure(&blk) if block_given?
  end
end

.load! ⇒ void

This method returns an undefined value.

Framework loading entry point

Since:

• 0.3.0

# File 'lib/hanami/controller.rb', line 255

def self.load!
  configuration.load!
end