Class Merb::Controller
In: merb-core/lib/merb-core/controller/merb_controller.rb
merb-param-protection/lib/merb-param-protection.rb
Parent: Merb::AbstractController

Methods

Included Modules

Merb::ResponderMixin Merb::ControllerMixin Merb::AuthenticationMixin Merb::ConditionalGetMixin

Attributes

headers  [R]  :api: public
request  [R]  :api: public

Public Class methods

All methods that are callable as actions.

Returns

Array:A list of method names that are also actions

:api: private

[Source]

     # File merb-core/lib/merb-core/controller/merb_controller.rb, line 166
166:   def self._callable_methods
167:     callables = []
168:     klass = self
169:     begin
170:       callables << (klass.public_instance_methods(false) + klass._shown_actions) - klass._hidden_actions
171:       klass = klass.superclass
172:     end until klass == Merb::AbstractController || klass == Object
173:     callables.flatten.reject{|action| action =~ /^_.*/}.map {|x| x.to_s}
174:   end

[Source]

     # File merb-param-protection/lib/merb-param-protection.rb, line 170
170:     def self._filter_params(params)
171:       return params if self.log_params_args.nil?
172:       result = { }
173:       params.each do |k,v|
174:         result[k] = (self.log_params_args.include?(k.to_sym) ? '[FILTERED]' : v)
175:       end
176:       result
177:     end

This is a stub method so plugins can implement param filtering if they want.

Parameters

params<Hash{Symbol => String}>:A list of params

Returns

Hash{Symbol => String}:A new list of params, filtered as desired

:api: plugin @overridable

[Source]

     # File merb-core/lib/merb-core/controller/merb_controller.rb, line 155
155:   def self._filter_params(params)
156:     params
157:   end

Sets a controller to be "abstract" This controller will not be able to be routed to and is used for super classing only

:api: public

[Source]

     # File merb-core/lib/merb-core/controller/merb_controller.rb, line 420
420:   def self.abstract!
421:     @_abstract = true
422:   end

Asks a controller if it is abstract

Returns

Boolean

 true if the controller has been set as abstract

:api: public

[Source]

     # File merb-core/lib/merb-core/controller/merb_controller.rb, line 431
431:   def self.abstract?
432:     !!@_abstract 
433:   end

The list of actions that are callable, after taking defaults, _hidden_actions and _shown_actions into consideration. It is calculated once, the first time an action is dispatched for this controller.

Returns

SimpleSet[String]:A set of actions that should be callable.

:api: public

[Source]

     # File merb-core/lib/merb-core/controller/merb_controller.rb, line 141
141:   def self.callable_actions
142:     @callable_actions ||= Extlib::SimpleSet.new(_callable_methods)
143:   end

Hide each of the given methods from being callable as actions.

Parameters

*names<~to-s>:Actions that should be added to the list.

Returns

Array[String]:An array of actions that should not be possible to dispatch to.

:api: public

[Source]

     # File merb-core/lib/merb-core/controller/merb_controller.rb, line 98
 98:   def self.hide_action(*names)
 99:     self._hidden_actions = self._hidden_actions | names.map { |n| n.to_s }
100:   end

Parameters

klass<Merb::Controller>:The Merb::Controller inheriting from the base class.

:api: private

[Source]

    # File merb-core/lib/merb-core/controller/merb_controller.rb, line 27
27:   def self.inherited(klass)
28:     _subclasses << klass.to_s
29:     super
30:     klass._template_root = Merb.dir_for(:view) unless self._template_root
31:   end

Build a new controller.

Sets the variables that came in through the dispatch as available to the controller.

Parameters

request<Merb::Request>:The Merb::Request that came in from Rack.
status<Integer>:An integer code for the status. Defaults to 200.
headers<Hash{header => value}>:A hash of headers to start the controller with. These headers can be overridden later by the headers method.

:api: plugin @overridable

[Source]

     # File merb-core/lib/merb-core/controller/merb_controller.rb, line 230
230:   def initialize(request, status=200, headers={'Content-Type' => 'text/html; charset=utf-8'})
231:     super()
232:     @request, @_status, @headers = request, status, headers
233:   end

Parameters

*names<Array[Symbol]>:an Array of method names that should be overridable in application controllers.

Returns

Array:The list of methods that are overridable

:api: plugin

[Source]

    # File merb-core/lib/merb-core/controller/merb_controller.rb, line 42
42:   def self.overridable(*names)
43:     self._overridable.push(*names)
44:   end

In an application controller, call override! before a method to indicate that you want to override a method in Merb::Controller that is not normally overridable.

Doing this may potentially break your app in a future release of Merb, and this is provided for users who are willing to take that risk. Without using override!, Merb will raise an error if you attempt to override a method defined on Merb::Controller.

This is to help users avoid a common mistake of defining an action that overrides a core method on Merb::Controller.

Parameters

*names<Array[Symbol]>:An Array of methods that will override Merb core classes on purpose

Example

    class Kontroller < Application
      def status
        render
      end
    end

will raise a Merb::ReservedError, because status is a method on Merb::Controller.

    class Kontroller < Application
      override! :status
      def status
        some_code || super
      end
    end

will not raise a Merb::ReservedError, because the user specifically decided to override the status method.

:api: public

[Source]

    # File merb-core/lib/merb-core/controller/merb_controller.rb, line 84
84:   def self.override!(*names)
85:     self._override_bang.push(*names)
86:   end

Makes each of the given methods being callable as actions. You can use this to make methods included from modules callable as actions.

Parameters

*names<~to-s>:Actions that should be added to the list.

Returns

Array[String]:An array of actions that should be dispatched to even if they would not otherwise be.

Example

  module Foo
    def self.included(base)
      base.show_action(:foo)
    end

    def foo
      # some actiony stuff
    end

    def foo_helper
      # this should not be an action
    end
  end

:api: public

[Source]

     # File merb-core/lib/merb-core/controller/merb_controller.rb, line 129
129:   def self.show_action(*names)
130:     self._shown_actions = self._shown_actions | names.map {|n| n.to_s}
131:   end

:api: private

[Source]

    # File merb-core/lib/merb-core/controller/merb_controller.rb, line 15
15:   def self.subclasses_list() _subclasses end

Private Class methods

When a method is added to a subclass of Merb::Controller (i.e. an app controller) that is defined on Merb::Controller, raise a Merb::ReservedError. An error will not be raised if the method is defined as overridable in the Merb API.

This behavior can be overridden by using override! method_name before attempting to override the method.

Parameters

meth<~to_sym> The method that is being added

Raises

Merb::ReservedError:If the method being added is in a subclass of Merb::Controller, the method is defined on Merb::Controller, it is not defined as overridable in the Merb API, and the user has not specified that it can be overridden.

Returns

nil

:api: private

[Source]

     # File merb-core/lib/merb-core/controller/merb_controller.rb, line 475
475:   def self.method_added(meth)
476:     if self < Merb::Controller && Merb::Controller.method_defined?(meth) && 
477:       !self._overridable.include?(meth.to_sym) && !self._override_bang.include?(meth.to_sym)
478: 
479:       raise Merb::ReservedError, "You tried to define #{meth} on " \
480:         "#{self.name} but it was already defined on Merb::Controller. " \
481:         "If you meant to override a core method, use override!"
482:     end
483:   end

Public Instance methods

The location to look for a template and mime-type. This is overridden from AbstractController, which defines a version of this that does not involve mime-types.

Parameters

template<String>:The absolute path to a template - without mime and template extension. The mime-type extension is optional - it will be appended from the current content type if it hasn‘t been added already.
type<~to_s>:The mime-type of the template that will be rendered. Defaults to nil.

:api: public

[Source]

     # File merb-core/lib/merb-core/controller/merb_controller.rb, line 212
212:   def _absolute_template_location(template, type)
213:     _conditionally_append_extension(template, type)
214:   end

Dispatch the action.

Parameters

action<~to_s>:An action to dispatch to. Defaults to :index.

Returns

String:The string sent to the logger for time spent.

Raises

ActionNotFound:The requested action was not found in class.

:api: plugin

[Source]

     # File merb-core/lib/merb-core/controller/merb_controller.rb, line 248
248:   def _dispatch(action=:index)
249:     Merb.logger.info { "Params: #{self.class._filter_params(request.params).inspect}" }
250:     start = Time.now
251:     if self.class.callable_actions.include?(action.to_s)
252:       super(action)
253:     else
254:       raise ActionNotFound, "Action '#{action}' was not found in #{self.class}"
255:     end
256:     @_benchmarks[:action_time] = Time.now - start
257:     self
258:   end

The location to look for a template for a particular controller, context, and mime-type. This is overridden from AbstractController, which defines a version of this that does not involve mime-types.

Parameters

context<~to_s>:The name of the action or template basename that will be rendered.
type<~to_s>:The mime-type of the template that will be rendered. Defaults to nil.
controller<~to_s>:The name of the controller that will be rendered. Defaults to controller_name. This will be "layout" for rendering a layout.

Notes

By default, this renders ":controller/:action.:type". To change this, override it in your application class or in individual controllers.

:api: public @overridable

[Source]

     # File merb-core/lib/merb-core/controller/merb_controller.rb, line 194
194:   def _template_location(context, type, controller)
195:     _conditionally_append_extension(controller ? "#{controller}/#{context}" : "#{context}", type)
196:   end

Returns the absolute url including the passed protocol and host.

This uses the same arguments as the url method, with added requirements of protocol and host options.

:api: public

[Source]

     # File merb-core/lib/merb-core/controller/merb_controller.rb, line 396
396:   def absolute_url(*args)
397:     options  = extract_options_from_args!(args) || {}
398:     options[:protocol] ||= request.protocol
399:     options[:host] ||= request.host
400:     args << options
401:     super(*args)
402:   end

Returns

Hash:The parameters from the request object

:api: public

[Source]

     # File merb-core/lib/merb-core/controller/merb_controller.rb, line 291
291:   def params()  request.params  end

The results of the controller‘s render, to be returned to Rack.

Returns

Array[Integer, Hash, String]:The controller‘s status code, headers, and body

:api: private

[Source]

     # File merb-core/lib/merb-core/controller/merb_controller.rb, line 411
411:   def rack_response
412:     [status, headers, Merb::Rack::StreamWrapper.new(body)]
413:   end
relative_url(name, *args)

Alias for url

Generates a URL for a single or nested resource.

Parameters

resources<Symbol,Object>:The resources for which the URL
  should be generated. These resources should be specified
  in the router.rb file using #resources and #resource.
options<Hash>:Any extra parameters that are needed to
  generate the URL.

Returns

String:The generated URL.

Examples

Merb::Router.prepare do

  resources :users do
    resources :comments
  end

end

resource(:users) # => /users resource(@user) # => /users/10 resource(@user, :comments) # => /users/10/comments resource(@user, @comment) # => /users/10/comments/15 resource(:users, :new) # => /users/new resource(:@user, :edit) # => /users/10/edit

:api: public

[Source]

     # File merb-core/lib/merb-core/controller/merb_controller.rb, line 382
382:   def resource(*args)
383:     args << params
384:     Merb::Router.resource(*args)
385:   end

Returns

Fixnum:The response status code

:api: public

[Source]

     # File merb-core/lib/merb-core/controller/merb_controller.rb, line 267
267:   def status
268:     @_status
269:   end

Set the response status code.

Parameters

s<Fixnum, Symbol>:A status-code or named http-status

:api: public

[Source]

     # File merb-core/lib/merb-core/controller/merb_controller.rb, line 277
277:   def status=(s)
278:     if s.is_a?(Symbol) && STATUS_CODES.key?(s)
279:       @_status = STATUS_CODES[s]
280:     elsif s.is_a?(Fixnum)
281:       @_status = s
282:     else
283:       raise ArgumentError, "Status should be of type Fixnum or Symbol, was #{s.class}"
284:     end
285:   end

There are three possible ways to use this method. First, if you have a named route, you can specify the route as the first parameter as a symbol and any paramters in a hash. Second, you can generate the default route by just passing the params hash, just passing the params hash. Finally, you can use the anonymous parameters. This allows you to specify the parameters to a named route in the order they appear in the router.

Parameters(Named Route)

name<Symbol>:The name of the route.
args<Hash>:Parameters for the route generation.

Parameters(Default Route)

args<Hash>:Parameters for the route generation. This route will use the default route.

Parameters(Anonymous Parameters)

name<Symbol>:The name of the route.
args<Array>:An array of anonymous parameters to generate the route with. These parameters are assigned to the route parameters in the order that they are passed.

Returns

String:The generated URL.

Examples

Named Route

Merb::Router.prepare do

  match("/articles/:title").to(:controller => :articles, :action => :show).name("articles")

end

url(:articles, :title => "new_article")

Default Route

Merb::Router.prepare do

  default_routes

end

url(:controller => "articles", :action => "new")

Anonymous Paramters

Merb::Router.prepare do

  match("/articles/:year/:month/:title").to(:controller => :articles, :action => :show).name("articles")

end

url(:articles, 2008, 10, "test_article")

:api: public

[Source]

     # File merb-core/lib/merb-core/controller/merb_controller.rb, line 347
347:   def url(name, *args)
348:     args << params
349:     name = request.route if name == :this
350:     Merb::Router.url(name, *args)
351:   end

Private Instance methods

If not already added, add the proper mime extension to the template path.

Parameters

template<~to_s> :The template path to append the mime type to.
type<~to_s> :The extension to append to the template path conditionally

:api: private

[Source]

     # File merb-core/lib/merb-core/controller/merb_controller.rb, line 450
450:   def _conditionally_append_extension(template, type)
451:     type && !template.match(/\.#{type.to_s.escape_regexp}$/) ? "#{template}.#{type}" : template
452:   end

[Validate]