Class: Merb::Router::Behavior

Inherits:
Object
  • Object
show all
Includes:
Resources
Defined in:
lib/merb-core/dispatch/router/resources.rb,
lib/merb-core/dispatch/router/behavior.rb

Overview

Resources

Direct Known Subclasses

ResourceBehavior

Defined Under Namespace

Classes: Error, Proxy

Instance Method Summary collapse

Methods included from Resources

#resource, #resources

Constructor Details

#initialize(proxy = nil, conditions = {}, params = {}, defaults = {}, identifiers = {}, options = {}, blocks = []) ⇒ Behavior

Behavior objects are used for the Route building DSL. Each object keeps track of the current definitions for the level at which it is defined. Each time a method is called on a Behavior object that accepts a block, a new instance of the Behavior class is created.

Parameters

proxy<Proxy>

This is the object initialized by Merb::Router.prepare that tracks the current Behavior object stack so that Behavior methods can be called without explicitly calling them on an instance of Behavior.

conditions<Hash>

The initial route conditions. See #match.

params<Hash>

The initial route parameters. See #to.

defaults<Hash>

The initial route default parameters. See #defaults.

options<Hash>

The initial route options. See #options.

blocks<Array>

The stack of deferred routing blocks for the route

Returns

Behavior

The initialized Behavior object

:api: private



189
190
191
192
193
194
195
196
197
198
199
 
# File 'lib/merb-core/dispatch/router/behavior.rb', line 189

def initialize(proxy = nil, conditions = {}, params = {}, defaults = {}, identifiers = {}, options = {}, blocks = []) #:nodoc:
  @proxy       = proxy
  @conditions  = conditions
  @params      = params
  @defaults    = defaults
  @identifiers = identifiers
  @options     = options
  @blocks      = blocks
  
  stringify_condition_values
end

Instance Method Details

#_with_proxy(&block) ⇒ Object

Proxy routes with the default behaviors.

Parameters

&block

defines routes within the provided context.

:api: private



672
673
674
675
676
677
 
# File 'lib/merb-core/dispatch/router/behavior.rb', line 672

def _with_proxy(&block)
  proxy = Proxy.new
  proxy.push Behavior.new(proxy, @conditions, @params, @defaults, @identifiers, @options, @blocks)
  proxy.instance_eval(&block)
  proxy
end

#capture(&block) ⇒ Object

Capture any new routes that have been added within the block.

This utility method lets you track routes that have been added; it doesn’t affect how/which routes are added.

&block

A context in which routes are generated.

:api: public



650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
 
# File 'lib/merb-core/dispatch/router/behavior.rb', line 650

def capture(&block)
  captured_routes = {}
  name_prefix     = [@options[:name_prefix]].flatten.compact.map { |p| "#{p}_"}
  current_names   = Merb::Router.named_routes.keys
  
  behavior = Behavior.new(@proxy, @conditions, @params, @defaults, @identifiers, @options, @blocks)
  with_behavior_context(behavior, &block)
  
  Merb::Router.named_routes.reject { |k,v| current_names.include?(k) }.each do |name, route|
    name = route.name.to_s.sub(/^#{name_prefix.join('|')}/, '').to_sym unless name_prefix.empty?
    captured_routes[name] = route
  end
  
  captured_routes
end

#default(defaults = {}, &block) ⇒ Object Also known as: defaults

Sets default values for route parameters. If no value for the key can be extracted from the request, then the value provided here will be used.

Parameters

defaults<Hash>

The default values for named segments.

&block

All routes defined in the block will be scoped to the defaults defined by the #default method.

Block parameters

r<Behavior>

optional - The defaults behavior object.

:api: public



365
366
367
368
 
# File 'lib/merb-core/dispatch/router/behavior.rb', line 365

def default(defaults = {}, &block)
  behavior = Behavior.new(@proxy, @conditions, @params, @defaults.merge(defaults), @identifiers, @options, @blocks)
  with_behavior_context(behavior, &block)
end

#default_routes(params = {}, &block) ⇒ Object

Creates the most common routes /:controller/:action/:id.format when called with no arguments. You can pass a hash or a block to add parameters or override the default behavior.

Parameters

params<Hash>

This optional hash can be used to augment the default settings

&block

When passing a block a new behavior is yielded and more refinement is possible.

Returns

Route

the default route

Examples

# Passing an extra parameter "mode" to all matches
r.default_routes :mode => "default"

# specifying exceptions within a block
r.default_routes do |nr|
  nr.defer_to do |request, params|
    nr.match(:protocol => "http://").to(:controller => "login",
      :action => "new") if request.env["REQUEST_URI"] =~ /\/private\//
  end
end

:api: public



515
516
517
 
# File 'lib/merb-core/dispatch/router/behavior.rb', line 515

def default_routes(params = {}, &block)
  match("/:controller(/:action(/:id))(.:format)").to(params, &block).name(:default)
end

#defer(deferred_block, &block) ⇒ Object

Takes a Proc as a parameter and applies it as a deferred proc for all the routes defined in the block. This is mostly interesting for plugin developers.

Examples

defered_block = proc do |r, p|
  p.merge :controller => 'api/comments' if request.xhr?
end
defer(defered_block) do
  resources :comments
end

:api: public



564
565
566
567
568
 
# File 'lib/merb-core/dispatch/router/behavior.rb', line 564

def defer(deferred_block, &block)
  blocks = @blocks + [CachedProc.new(deferred_block)]
  behavior = Behavior.new(@proxy, @conditions, @params, @defaults, @identifiers, @options, blocks)
  with_behavior_context(behavior, &block)
end

#defer_to(params = {}, &block) ⇒ Object

Takes a block and stores it for deferred conditional routes. The block takes the request object and the params hash as parameters.

Parameters

params<Hash>

Parameters and conditions associated with this behavior.

&conditional_block

A block with the conditions to be met for the behavior to take effect.

Returns

Route

The default route.

Note

The block takes two parameters, request and params. The params that are passed into the block are just the placeholder params from the route. If you want the full parsed params, use request.params.

The rationale for this is that request.params is a fairly slow operation, and if the full params parsing is not required, we would rather not do the full parsing.

Examples

defer_to do |request, params|
  params.merge :controller => 'here',
    :action => 'there' if request.xhr?
end

:api: public



547
548
549
 
# File 'lib/merb-core/dispatch/router/behavior.rb', line 547

def defer_to(params = {}, &block)
  defer(block).to(params)
end

#fixatable(enable = true) ⇒ Object

Specifies that a route can be fixatable.

Parameters

enabled<Boolean>

True enables fixation on the route.

:api: public



614
615
616
617
 
# File 'lib/merb-core/dispatch/router/behavior.rb', line 614

def fixatable(enable = true)
  @route.fixation = enable
  self
end

#full_name(name) ⇒ Object

Names this route in Router. Name must be a Symbol. The current name_prefix is ignored.

Parameters

symbol<Symbol>

The name of the route.

Raises

ArgumentError

symbol is not a Symbol.

:api: private

Raises:



597
598
599
600
601
602
603
604
605
606
 
# File 'lib/merb-core/dispatch/router/behavior.rb', line 597

def full_name(name)
  raise Error, ":this is reserved. Please pick another name." if name == :this
  
  if @route
    @route.name = name
    self
  else
    register.full_name(name)
  end
end

#identify(identifiers = {}, &block) ⇒ Object

Sets a method for instances of specified Classes to be called before insertion into a route. This is useful when using models and want a specific method to be called on it (For example, for ActiveRecord::Base it would be #to_param).

The default method called on objects is #to_s.

Paramters

identifiers<Hash>

The keys are Classes and the values are the method that instances of the specified class should have called on.

&block

All routes defined in the block will be call the specified methods during generation.

Block parameters

r<Behavior>

The identify behavior object. This is optional

:api: public



475
476
477
478
479
480
481
482
483
484
 
# File 'lib/merb-core/dispatch/router/behavior.rb', line 475

def identify(identifiers = {}, &block)
  identifiers = if Hash === identifiers
    @identifiers.merge(identifiers)
  else
    { Object => identifiers }
  end
  
  behavior = Behavior.new(@proxy, @conditions, @params, @defaults, identifiers.freeze, @options, @blocks)
  with_behavior_context(behavior, &block)
end

#match(path = {}, conditions = {}, &block) ⇒ Object

Defines the conditions that are required to match a Request. Each condition is applied to a method of the Request object. Conditions can also be applied to segments of the path.

If #match is passed a block, it will create a new route scope with the conditions passed to it and yield to the block such that all routes that are defined in the block have the conditions applied to them.

Parameters

path<String, Regexp>

The pattern against which Merb::Request path is matched.

When path is a String, any substring that is wrapped in parenthesis is considered optional and any segment that begins with a colon, ex.: “:login”, defines both a capture and a named param. Extra conditions can then be applied each named param individually.

When path is a Regexp, the pattern is left untouched and the Merb::Request path is matched against it as is.

path is optional.

conditions<Hash>

Additional conditions that the request must meet in order to match. The keys must be the names of previously defined path segments or be methods that the Merb::Request instance will respond to. The value is the string or regexp that matched the returned value. Conditions are inherited by child routes.

&block

All routes defined in the block will be scoped to the conditions defined by the #match method.

Block parameters

r<Behavior>

optional - The match behavior object.

Returns

Behavior

A new instance of Behavior with the specified path and conditions.

Tip: When nesting always make sure the most inner sub-match registers a Route and doesn’t just return new Behaviors.

Examples

# registers /foo/bar to controller => "foo", :action => "bar"
# and /foo/baz to controller => "foo", :action => "baz"
match("/foo") do
  match("/bar").to(:controller => "foo", :action => "bar")
  match("/baz").to(:controller => "foo", :action => "caz")
end

# Checks the format of the segments against the specified Regexp
match("/:string/:number", :string => /[a-z]+/, :number => /\d+/).
  to(:controller => "string_or_numbers")

# Equivalent to the default_route
match("/:controller(/:action(:id))(.:format)").register

#match only if the browser string contains MSIE or Gecko
match("/foo", :user_agent => /(MSIE|Gecko)/ )
     .to(:controller => 'foo', :action => 'popular')

# Route GET and POST requests to different actions (see also #resources)
r.match('/foo', :method => :get).to(:action => 'show')
r.match('/foo', :method => :post).to(:action => 'create')

# match also takes regular expressions

r.match(%r[/account/([a-z]{4,6})]).to(:controller => "account",
   :action => "show", :id => "[1]")

r.match(%r{/?(en|es|fr|be|nl)?}).to(:language => "[1]") do
  match("/guides/:action/:id").to(:controller => "tour_guides")
end

:api: public

Raises:



280
281
282
283
284
285
286
287
288
289
290
 
# File 'lib/merb-core/dispatch/router/behavior.rb', line 280

def match(path = {}, conditions = {}, &block)
  path, conditions = path[:path], path if path.is_a?(Hash)
  
  raise Error, "The route has already been committed. Further conditions cannot be specified" if @route
  
  conditions.delete_if { |k, v| v.nil? }
  conditions[:path] = merge_paths(path)
  
  behavior = Behavior.new(@proxy, @conditions.merge(conditions), @params, @defaults, @identifiers, @options, @blocks)
  with_behavior_context(behavior, &block)
end

#name(prefix, name = nil) ⇒ Object

Registers the route as a named route with the name given.

Parameters

symbol<Symbol>

the name of the route.

Raises

ArgumentError

symbol is not a Symbol.

:api: public



579
580
581
582
583
584
585
 
# File 'lib/merb-core/dispatch/router/behavior.rb', line 579

def name(prefix, name = nil)
  unless name
    name, prefix = prefix, nil
  end
  
  full_name([prefix, @options[:name_prefix], name].flatten.compact.join('_'))
end

#namespace(name_or_path, opts = {}, &block) ⇒ Object

Creates a namespace for a route. This way you can have logical separation to your routes.

Parameters

name_or_path<String, Symbol>

The name or path of the namespace.

options<Hash>

Optional hash (see below)

&block

All routes defined in the block will be scoped to the namespace defined by the #namespace method.

Options (opts)

:path<String>

match against this url

Block parameters

r<Behavior>

The namespace behavior object. This is optional

Examples

namespace :admin do
  resources :accounts
  resource :email
end

# /super_admin/accounts
namespace(:admin, :path=>"super_admin") do
  resources :accounts
end

:api: public

Raises:



439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
 
# File 'lib/merb-core/dispatch/router/behavior.rb', line 439

def namespace(name_or_path, opts = {}, &block)
  name = name_or_path.to_s # We don't want this modified ever
  path = opts.has_key?(:path) ? opts[:path] : name
  
  raise Error, "The route has already been committed. Further options cannot be specified" if @route
  
  # option keys could be nil
  opts[:controller_prefix] = name unless opts.has_key?(:controller_prefix)
  opts[:name_prefix]       = name unless opts.has_key?(:name_prefix)
  opts[:resource_prefix]   = opts[:name_prefix] unless opts.has_key?(:resource_prefix)
  
  behavior = self
  behavior = behavior.match("/#{path}") unless path.nil? || path.empty?
  behavior.options(opts, &block)
end

#redirect(url, opts = {}) ⇒ Object

Redirects the current route.

Parameters

path<String>

The path to redirect to.

options<Hash>

Options (see below)

Options (opts)

:permanent<Boolean>

Whether or not the redirect should be permanent. The default value is false.

:api: public

Raises:



633
634
635
636
637
638
639
640
 
# File 'lib/merb-core/dispatch/router/behavior.rb', line 633

def redirect(url, opts = {})
  raise Error, "The route has already been committed." if @route
  
  status = opts[:permanent] ? 301 : 302
  @route = Route.new(@conditions, {:url => url.freeze, :status => status.freeze}, @blocks, :redirects => true)
  @route.register
  self
end

#to(params = {}, &block) ⇒ Object Also known as: with, register

Creates a Route from one or more Behavior objects, unless a block is passed in.

Parameters

params<Hash>

The parameters the route maps to.

&block

All routes defined in the block will be scoped to the params defined by the #to method.

Block parameters

r<Behavior>

optional - The to behavior object.

Returns

Behavior

The route definition behavior defining the created route

Examples

match('/:controller/:id).to(:action => 'show')

to(:controller => 'simple') do
  match('/test').to(:action => 'index')
  match('/other').to(:action => 'other')
end

:api: public

Raises:



317
318
319
320
321
322
323
324
325
326
327
 
# File 'lib/merb-core/dispatch/router/behavior.rb', line 317

def to(params = {}, &block)
  raise Error, "The route has already been committed. Further params cannot be specified" if @route
  
  behavior = Behavior.new(@proxy, @conditions, @params.merge(params), @defaults, @identifiers, @options, @blocks)
  
  if block_given?
    with_behavior_context(behavior, &block)
  else
    behavior.to_route
  end
end