Configuration

Global configuration goes into file config/initializers/wallaby.rb, generated by the installer:

rails g wallaby:install

Global Configuration

All the global configuration goes into config/initializers/wallaby.rb:

Wallaby.config do |config|
  # config.model_paths = %w(app/models)
  # config.base_controller = ::ApplicationController
  # config.resources_controller = Admin::ApplicationController
  # config.custom_models = [Array]
end

model_paths

To specify the relative folders where the models reside, so that Wallaby knows where to load them:

# config/initializers/wallaby.rb
Wallaby.config do |config|
  config.model_paths = %w[app/models app/core]
end

Default is %w[app/models].

base_controller

By default, Wallaby::ResourcesController inherits from ::ApplicationController. Therefore, all subclasses of Wallaby::ResourcesController will have access to all ::ApplicationController’s controller and helper methods.

However, it’s possible to change the base controller class that Wallaby::ResourcesController inherits from:

# config/initializers/wallaby.rb
Wallaby.config do |config|
  config.base_controller = MySecurityController
end

Once this is set up, Wallaby will automatically pick up the authentication methods from MySecurityController (e.g. Devise’s authenticate_user! and current_user).

resources_controller

To specify the application controller class that Wallaby::Engine should use:

# config/initializers/wallaby.rb
Wallaby.config do |config|
  config.resources_controller = GlobalController
end

If no configuration is given, Wallaby defaults to use Admin::ApplicationController if it exists, otherwise Wallaby::ResourcesController.

custom_models

To specify the non ActiveModel-like models (e.g. plain Ruby classes) that Wallaby should treat as Custom mode:

# config/initializers/wallaby.rb
Wallaby.config do |config|
  config.custom_models = [Postcode]
end

Once it’s set, a servicer needs to be implemented for the Custom models. See Custom mode.

raise_on_name_error

Whether Wallaby should raise a NameError when a class cannot be found. Default is false.

# config/initializers/wallaby.rb
Wallaby.config do |config|
  config.raise_on_name_error = true
end

logger

To specify the logger instance that Wallaby should use. It defaults to Rails.logger.

# config/initializers/wallaby.rb
Wallaby.config do |config|
  config.logger = Logger.new(STDOUT)
end

Controller Configuration

Everything else is configured per controller class (usually in the base controller Admin::ApplicationController), instead of a global initializer.

For example, all the options below are set in app/controllers/admin/application_controller.rb:

class Admin::ApplicationController < Wallaby::ResourcesController
  base_class!
  self.application_decorator = GlobalDecorator
  self.page_size = 50
  self.sorting_strategy = :single
end

.base_class!

See Controller - base_class!

All controllers will be preloaded and processed by Wallaby in order to build up the mapping between controllers and models. If the controller is considered a base class (e.g. an abstract ApplicationController), it can be flagged using base_class! so that Wallaby won’t try to map a model to it:

class Admin::ApplicationController < Wallaby::ResourcesController
  base_class!
end

.models=

To whitelist the models that Wallaby should handle:

class Admin::ApplicationController < Wallaby::ResourcesController
  self.models = User, 'Product'
end

When models are whitelisted, models exclusion will NOT be applied.

.models_to_exclude=

To blacklist the models that Wallaby shouldn’t handle:

class Admin::ApplicationController < Wallaby::ResourcesController
  self.models_to_exclude User, Order
end

NOTE: when models are whitelisted via models=, models exclusion will NOT be applied. By default, ActiveRecord::SchemaMigration (and similar) is excluded.

resource_decorator

Read more from Decorator to understand what decorator does and how decorator can be customized.

Wallaby resolves the resource decorator for a model by naming convention (see Naming Conventions). To override the resolved decorator for a specific controller:

class Admin::ProductsController < Admin::ApplicationController
  resource_decorator # => Admin::ProductDecorator
  self.resource_decorator = ProductDecorator
end

To nominate a different base decorator class that the controller and its subclasses will use:

class Admin::ApplicationController < Wallaby::ResourcesController
  self.application_decorator = GlobalDecorator
end

model_servicer

Read more from Servicer to understand what servicer does and how servicer can be customized.

To nominate a different base servicer class:

class Admin::ApplicationController < Wallaby::ResourcesController
  self.application_servicer = GlobalServicer
end

To override the resolved servicer for a specific controller:

class Admin::ProductsController < Admin::ApplicationController
  model_servicer # => Admin::ProductServicer
  self.model_servicer = ProductServicer
end

model_authorizer

Read more from Authorizer to understand what authorizer does and how authorizer can be customized.

To nominate a different base authorizer class:

class Admin::ApplicationController < Wallaby::ResourcesController
  self.application_authorizer = GlobalAuthorizer
end

To override the resolved authorizer for a specific controller:

class Admin::ProductsController < Admin::ApplicationController
  model_authorizer # => Admin::ProductAuthorizer
  self.model_authorizer = ProductAuthorizer
end

model_paginator

Read more from Paginator to understand what paginator does and how paginator can be customized.

To nominate a different base paginator class:

class Admin::ApplicationController < Wallaby::ResourcesController
  self.application_paginator = GlobalPaginator
end

To override the resolved paginator for a specific controller:

class Admin::ProductsController < Admin::ApplicationController
  model_paginator # => Admin::ProductPaginator
  self.model_paginator = ProductPaginator
end

.engine_name=

To specify the name of the engine helper for the current controller class and its subclasses, in case Wallaby cannot detect the engine name (see Route - Engine Helper):

class Admin::ApplicationController < Wallaby::ResourcesController
  self.engine_name = :manager_engine
end

NOTE: All subclasses of Admin::ApplicationController will inherit the same engine name when it is set.

.theme_name=

To specify the theme (a set of view layout and templates) and layout for the current controller class and its subclasses. See Theme:

class Admin::ApplicationController < Wallaby::ResourcesController
  self.theme_name = 'bootstrap4'
end

.logout_path=

To specify the name of the logout path/url helper. By default, it uses Devise’s destroy_#{user_scope}_session_path when Devise is detected:

class Admin::ApplicationController < Wallaby::ResourcesController
  self.logout_path = 'sign_out_now_path'
end

.logout_method=

To specify the HTTP request verb for the logout route. By default, it uses Devise’s sign_out_via when Devise is detected:

class Admin::ApplicationController < Wallaby::ResourcesController
  self.logout_method = 'post'
end

.email_method=

To specify the method name which returns the user’s email address for avatar display. Default is :email:

class Admin::ApplicationController < Wallaby::ResourcesController
  self.email_method = :user_email
end

.max_text_length=

To configure the max length that Wallaby should truncate to when given text is longer than defined. Default is 20:

class Admin::ApplicationController < Wallaby::ResourcesController
  self.max_text_length = 300
end

.page_size=

To configure the default page size that Wallaby should use as default for pagination. Default is 20:

class Admin::ApplicationController < Wallaby::ResourcesController
  self.page_size = 100
end

.sorting_strategy=

Wallaby supports :multiple/:single column sorting, and the default option is :multiple. To change to single column sorting, it goes:

class Admin::ApplicationController < Wallaby::ResourcesController
  self.sorting_strategy = :single
end

Authentication

NOTE: Wallaby DOES NOT handle signing in or out. It only checks if user is signed in or not.

#authenticate_wallaby_user!

This is the method that Wallaby uses as a before_action to authenticate a user. By default, it tries to call authenticate_user! from the base controller (e.g. Devise).

To customize the authentication, override it in the base controller. For example, to use HTTP BASIC authentication:

# app/controllers/admin/application_controller.rb
class Admin::ApplicationController < Wallaby::ResourcesController
  private

  def authenticate_wallaby_user!
    authenticate_or_request_with_http_basic do |username, password|
      username == 'too_simple' && password == 'too_naive'
    end
  end
end

#wallaby_user

This is the method that Wallaby uses to return the signed-in user instance. By default, it tries to call current_user from the base controller (e.g. Devise), which returns nil if not signed in.

NOTE: it is also a helper method available in the view.

To customize, override it in the base controller:

# app/controllers/admin/application_controller.rb
class Admin::ApplicationController < Wallaby::ResourcesController
  private

  def wallaby_user
    # user example
    @wallaby_user ||= Class.new do
      def email
        'user@example.com'
      end
    end.new
  end
end

NOTE: Wallaby uses the method email (configurable via email_method=) to display user avatar image from https://en.gravatar.com at top-right corner on every page.