Class: Merb::Controller

Inherits:
AbstractController show all
Includes:
AuthenticationMixin, ConditionalGetMixin, ControllerMixin, ResponderMixin
Defined in:
lib/merb-core/controller/merb_controller.rb

Constant Summary

Constants included from ResponderMixin

ResponderMixin::ACCEPT_RESULTS, ResponderMixin::MIMES, ResponderMixin::MIME_MUTEX, ResponderMixin::TYPES

Constants inherited from AbstractController

AbstractController::FILTER_OPTIONS

Constants included from ControllerExceptions

Merb::ControllerExceptions::STATUS_CODES

Instance Attribute Summary collapse

Attributes inherited from AbstractController

#_benchmarks, #_thrown_content, #action_name, #body, #content_type

Class Method Summary collapse

Instance Method Summary collapse

Methods included from ConditionalGetMixin

#etag, #etag=, #etag_matches?, #last_modified, #last_modified=, #not_modified?, #request_fresh?

Methods included from AuthenticationMixin

#basic_authentication

Methods included from ControllerMixin

#delete_cookie, #escape_xml, #message, #nginx_send_file, #redirect, #render_chunked, #render_deferred, #render_then_call, #run_later, #send_chunk, #send_data, #send_file, #set_cookie, #stream_file

Methods included from ResponderMixin

#_accept_types, #_perform_content_negotiation, #_provided_formats, #content_type, #content_type=, #does_not_provide, included, #only_provides, #provides

Methods inherited from AbstractController

#_call_action, #_call_filter_for_action?, #_call_filters, #_evaluate_condition, #_filter_condition_met?, _reset_template_roots, _template_root=, _template_roots, _template_roots=, after, before, #capture, #concat, #controller_name, controller_name, skip_after, skip_before

Methods included from RenderMixin

#_get_layout, #_handle_options!, #_template_for, #_template_method_for, #append_content, #catch_content, #clear_content, #display, included, #partial, #render, #throw_content, #thrown_content?

Constructor Details

#initialize(request, status = 200, headers = {'Content-Type' => 'text/html; charset=utf-8'}) ⇒ Controller

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=> value>

A hash of headers to start the controller with. These headers can be overridden later by the #headers method.

:api: plugin



230
231
232
233
 
# File 'lib/merb-core/controller/merb_controller.rb', line 230

def initialize(request, status=200, headers={'Content-Type' => 'text/html; charset=utf-8'})
  super()
  @request, @_status, @headers = request, status, headers
end

Instance Attribute Details

#headers ⇒ Object (readonly)

:api: public



294
295
296
 
# File 'lib/merb-core/controller/merb_controller.rb', line 294

def headers
  @headers
end

#request ⇒ Object (readonly)

:api: public



294
295
296
 
# File 'lib/merb-core/controller/merb_controller.rb', line 294

def request
  @request
end

Class Method Details

._callable_methods ⇒ Object

All methods that are callable as actions.

Returns

Array

A list of method names that are also actions

:api: private



166
167
168
169
170
171
172
173
174
 
# File 'lib/merb-core/controller/merb_controller.rb', line 166

def self._callable_methods
  callables = []
  klass = self
  begin
    callables << (klass.public_instance_methods(false) + klass._shown_actions).map{|m| m.to_s} - klass._hidden_actions
    klass = klass.superclass
  end until klass == Merb::AbstractController || klass == Object
  callables.flatten.reject{|action| action =~ /^_.*/}.map {|x| x.to_s}
end

._filter_params(params) ⇒ Object

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

Parameters

params<Hash=> String>

A list of params

Returns

Hash=> String

A new list of params, filtered as desired

:api: plugin



155
156
157
 
# File 'lib/merb-core/controller/merb_controller.rb', line 155

def self._filter_params(params)
  params
end

.abstract! ⇒ Object

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



453
454
455
 
# File 'lib/merb-core/controller/merb_controller.rb', line 453

def self.abstract!
  @_abstract = true
end

.abstract? ⇒ Boolean

Asks a controller if it is abstract

Returns

Boolean

true if the controller has been set as abstract

:api: public

Returns:

  • (Boolean) 


464
465
466
 
# File 'lib/merb-core/controller/merb_controller.rb', line 464

def self.abstract?
  !!@_abstract 
end

.call(env) ⇒ Object

Call the controller as a Rack endpoint.

Expects:

env["merb.status"]:: the default status code to be returned
env["merb.action_name"]:: the action name to dispatch
env["merb.request_start"]:: a Time object representing the
  start of the request.

Parameters

env<Hash>

A rack environment

Returns

Array[Integer, Hash, #each]

A standard Rack response

:api: public



251
252
253
 
# File 'lib/merb-core/controller/merb_controller.rb', line 251

def self.call(env)
  new(Merb::Request.new(env), env["merb.status"])._call
end

.callable_actions ⇒ Object

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

A set of actions that should be callable.

:api: public



141
142
143
 
# File 'lib/merb-core/controller/merb_controller.rb', line 141

def self.callable_actions
  @callable_actions ||= Extlib::SimpleSet.new(_callable_methods)
end

.hide_action(*names) ⇒ Object

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

An array of actions that should not be possible to dispatch to.

:api: public



98
99
100
 
# File 'lib/merb-core/controller/merb_controller.rb', line 98

def self.hide_action(*names)
  self._hidden_actions = self._hidden_actions | names.map { |n| n.to_s }
end

.inherited(klass) ⇒ Object

Parameters

klass<Merb::Controller>

The Merb::Controller inheriting from the base class.

:api: private



27
28
29
30
31
 
# File 'lib/merb-core/controller/merb_controller.rb', line 27

def self.inherited(klass)
  _subclasses << klass.to_s
  super
  klass._template_root = Merb.dir_for(:view) unless self._template_root
end

.overridable(*names) ⇒ Object

Parameters

*names<Array>

an Array of method names that should be overridable in application controllers.

Returns

Array

The list of methods that are overridable

:api: plugin



42
43
44
 
# File 'lib/merb-core/controller/merb_controller.rb', line 42

def self.overridable(*names)
  self._overridable.push(*names)
end

.override!(*names) ⇒ Object

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>

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



84
85
86
 
# File 'lib/merb-core/controller/merb_controller.rb', line 84

def self.override!(*names)
  self._override_bang.push(*names)
end

.show_action(*names) ⇒ Object

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

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



129
130
131
 
# File 'lib/merb-core/controller/merb_controller.rb', line 129

def self.show_action(*names)
  self._shown_actions = self._shown_actions | names.map {|n| n.to_s}
end

.subclasses_list ⇒ Object

:api: private



15
 
# File 'lib/merb-core/controller/merb_controller.rb', line 15

def self.subclasses_list() _subclasses end

Instance Method Details

#_absolute_template_location(template, type) ⇒ Object

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



212
213
214
 
# File 'lib/merb-core/controller/merb_controller.rb', line 212

def _absolute_template_location(template, type)
  _conditionally_append_extension(template, type)
end

#_call ⇒ Object

Dispatches the action and records benchmarks

Returns

Array[Integer, Hash, #each]

A standard Rack response

:api: private



261
262
263
264
265
266
267
 
# File 'lib/merb-core/controller/merb_controller.rb', line 261

def _call
  _dispatch(request.env["merb.action_name"])
  _benchmarks[:dispatch_time] = Time.now - request.env["merb.request_start"]
  Merb.logger.info { _benchmarks.inspect }
  Merb.logger.flush
  rack_response        
end

#_dispatch(action = :index) ⇒ Object

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



281
282
283
284
285
286
287
288
289
290
291
 
# File 'lib/merb-core/controller/merb_controller.rb', line 281

def _dispatch(action=:index)
  Merb.logger.info { "Params: #{self.class._filter_params(request.params).inspect}" }
  start = Time.now
  if self.class.callable_actions.include?(action.to_s)
    super(action)
  else
    raise ActionNotFound, "Action '#{action}' was not found in #{self.class}"
  end
  @_benchmarks[:action_time] = Time.now - start
  self
end

#_template_location(context, type, controller) ⇒ Object

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



194
195
196
 
# File 'lib/merb-core/controller/merb_controller.rb', line 194

def _template_location(context, type, controller)
  _conditionally_append_extension(controller ? "#{controller}/#{context}" : "#{context}", type)
end

#absolute_url(*args) ⇒ Object

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



429
430
431
432
433
434
435
 
# File 'lib/merb-core/controller/merb_controller.rb', line 429

def absolute_url(*args)
  options  = extract_options_from_args!(args) || {}
  options[:protocol] ||= request.protocol
  options[:host] ||= request.host
  args << options
  super(*args)
end

#params ⇒ Object

Returns

Hash

The parameters from the request object

:api: public



324
 
# File 'lib/merb-core/controller/merb_controller.rb', line 324

def params()  request.params  end

#rack_response ⇒ Object

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



444
445
446
 
# File 'lib/merb-core/controller/merb_controller.rb', line 444

def rack_response
  [status, headers, Merb::Rack::StreamWrapper.new(body)]
end

#resource(*args) ⇒ Object

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



415
416
417
418
 
# File 'lib/merb-core/controller/merb_controller.rb', line 415

def resource(*args)
  args << params
  Merb::Router.resource(*args)
end

#status ⇒ Object

Returns

Fixnum

The response status code

:api: public



300
301
302
 
# File 'lib/merb-core/controller/merb_controller.rb', line 300

def status
  @_status
end

#status=(s) ⇒ Object

Set the response status code.

Parameters

s<Fixnum, Symbol>

A status-code or named http-status

:api: public



310
311
312
313
314
315
316
317
318
 
# File 'lib/merb-core/controller/merb_controller.rb', line 310

def status=(s)
  if s.is_a?(Symbol) && STATUS_CODES.key?(s)
    @_status = STATUS_CODES[s]
  elsif s.is_a?(Fixnum)
    @_status = s
  else
    raise ArgumentError, "Status should be of type Fixnum or Symbol, was #{s.class}"
  end
end

#url(name, *args) ⇒ Object Also known as: relative_url

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



380
381
382
383
384
 
# File 'lib/merb-core/controller/merb_controller.rb', line 380

def url(name, *args)
  args << params
  name = request.route if name == :this
  Merb::Router.url(name, *args)
end