Class Merb::AbstractController
In: lib/merb-core/controller/abstract_controller.rb
Parent: Object

Note that the over-use of "_" in Controller methods is to avoid collisions with helpers, which will be pulled directly into controllers from now on.

Filters

before is a class method that allows you to specify before filters in your controllers. Filters can either be a symbol or string that corresponds to a method name to call, or a proc object. if it is a method name that method will be called and if it is a proc it will be called with an argument of self where self is the current controller object. When you use a proc as a filter it needs to take one parameter.

after is identical, but the filters are run after the action is invoked.

Examples

  before :some_filter
  before :authenticate, :exclude => [:login, :signup]
  before :has_role, :with => ["Admin"], :exclude => [:index,:show]
  before Proc.new {|c| c.some_method }, :only => :foo
  before :authorize, :unless => logged_in?

You can use either :only => :actionname or :exclude => [:this, :that] but not both at once. :only will only run before the listed actions and :exclude will run for every action that is not listed.

Merb‘s before filter chain is very flexible. To halt the filter chain you use throw :halt. If throw is called with only one argument of :halt the return of the method filters_halted will be what is rendered to the view. You can overide filters_halted in your own controllers to control what it outputs. But the throw construct is much more powerful then just that. throw :halt can also take a second argument. Here is what that second arg can be and the behavior each type can have:

  • String: when the second arg is a string then that string will be what is rendered to the browser. Since merb‘s render method returns a string you can render a template or just use a plain string:
      throw :halt, "You don't have permissions to do that!"
      throw :halt, render(:action => :access_denied)
    
  • Symbol: If the second arg is a symbol then the method named after that symbol will be called

    throw :halt, :must_click_disclaimer

  • Proc:

    If the second arg is a Proc, it will be called and its return value will be what is rendered to the browser:

      throw :halt, proc {|c| c.access_denied }
      throw :halt, proc {|c| Tidy.new(c.index) }
    

Filter Options (.before, .after, .add_filter, .if, .unless)

:only<Symbol, Array[Symbol]>:A list of actions that this filter should apply to
:exclude<Symbol, Array[Symbol]:A list of actions that this filter should not apply to
:if<Symbol, Proc>:Only apply the filter if the method named after the symbol or calling the proc evaluates to true
:unless<Symbol, Proc>:Only apply the filter if the method named after the symbol or calling the proc evaluates to false

Types (shortcuts for use in this file)

Filter:<Array[Symbol, (Symbol, String, Proc)]>

Methods

Included Modules

Merb::RenderMixin Merb::InlineTemplates

Attributes

_benchmarks  [RW] 
_thrown_content  [RW] 
action_name  [RW] 
body  [RW] 
content_type  [RW]  Stub so content-type support in RenderMixin doesn‘t throw errors

Public Class methods

Returns

roots<Array[Array]>:Template roots as pairs of template root path and template location method.

Parameters

roots<Array[Array]>:Template roots as pairs of template root path and template location method.

Handles the template cache (which is used by BootLoader to cache the list of all templates).

Parameters

template<String>:The full path to a template to add to the list of available templates

Parameters

filter<Symbol, Proc>:The filter to add. Defaults to nil.
opts<Hash>:Filter options (see class documentation under Filter Options).
&block:Currently ignored.

Notes

If the filter already exists, its options will be replaced with opts.

Parameters

filter<Symbol, Proc>:The filter to add. Defaults to nil.
opts<Hash>:Filter options (see class documentation under Filter Options).
&block:A block to use as a filter if filter is nil.

Notes

If the filter already exists, its options will be replaced with opts.

Returns

String:The controller name in path form, e.g. "admin/items".

Parameters

klass<Merb::AbstractController>:The controller that is being inherited from Merb::AbstractController

Parameters

*args:The args are ignored.

Resets the template_path_cache to an empty hash

Skip an after filter that has been previously defined (perhaps in a superclass)

Parameters

filter<Symbol>:A filter name to skip.

Skip a before filter that has been previously defined (perhaps in a superclass).

Parameters

filter<Symbol>:A filter name to skip.

Returns

Set:The subclasses.

Public Instance methods

This method exists to provide an overridable hook for ActionArgs

Parameters

action<~to_s>:the action method to dispatch to

Parameters

rule<Hash>:Rules for the filter (see below).
action_name<~to_s>:The name of the action to be called.

Options (rule)

:only<Array>:Optional list of actions to fire. If given, action_name must be a part of it for this function to return true.
:exclude<Array>:Optional list of actions not to fire. If given, action_name must not be a part of it for this function to return true.

Returns

Boolean:True if the action should be called.

Parameters

filter_set<Array[Filter]>:A set of filters in the form [[:filter, rule], [:filter, rule]]

Returns

Symbol::filter_chain_completed.

Notes

Filter rules can be Symbols, Strings, or Procs.

Symbols or Strings:Call the method represented by the Symbol or String.
Procs:Execute the Proc, in the context of the controller (self will be the controller)

This will dispatch the request, calling setup_session and finalize_session

Parameters

action<~to_s>:The action to dispatch to. This will be send‘ed in _call_action. Defaults to :to_s.

Raises

MerbControllerError:Invalid body content caught.

Parameters

condition<Symbol, Proc>:The condition to evaluate.

Raises

ArgumentError:condition not a Symbol or Proc.

Returns

Boolean:True if the condition is met.

Alternatives

If condition is a symbol, it will be send‘ed. If it is a Proc it will be called directly with self as an argument.

Parameters

rule<Hash>:Rules for the filter (see below).

Options (rule)

:if<Array>:Optional conditions that must be met for the filter to fire.
:unless<Array>:Optional conditions that must not be met for the filter to fire.

Returns

Boolean:True if the conditions are met.

This is called after the controller is instantiated to figure out where to for templates under the _template_root. Override this to define a new structure for your app.

Parameters

context<~to_s>:The controller context (the action or template name).
type<~to_s>:The content type. Defaults to nil.
controller<~to_s>:The name of the controller. Defaults to controller_name.

Returns

String:Indicating where to look for the template for the current controller, context, and content-type.

Notes

The type is irrelevant for controller-types that don‘t support content-type negotiation, so we default to not include it in the superclass.

Examples

  def _template_location
    "#{params[:controller]}.#{params[:action]}.#{content_type}"
  end

This would look for templates at controller.action.mime.type instead of controller/action.mime.type

Parameters

name<~to_sym, Hash>:The name of the URL to generate.
rparams<Hash>:Parameters for the route generation.

Returns

String:The generated url with protocol + hostname + URL.

Alternatives

If a hash is used as the first argument, a default route will be generated based on it and rparams.

Returns

String:The controller name in path form, e.g. "admin/items".

Method stub for finalizing up the session. This will be overriden by session modules.

relative_url(name, rparams={})

Alias for url

Method stub for setting up the session. This will be overriden by session modules.

Parameters

name<~to_sym, Hash>:The name of the URL to generate.
rparams<Hash>:Parameters for the route generation.

Returns

String:The generated URL.

Alternatives

If a hash is used as the first argument, a default route will be generated based on it and rparams.

[Validate]