Parent

Included Modules

Class/Module Index [+]

Quicksearch

Merb::Router::Behavior

Public Instance Methods

_with_proxy(&block) click to toggle source

Proxy routes with the default behaviors.

Parameters

&block

defines routes within the provided context.

:api: private

# 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) click to toggle source

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

# 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) click to toggle source

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

# 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
Also aliased as: defaults
default_routes(params = {}, &block) click to toggle source

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

# 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
defaults(defaults = {}, &block) click to toggle source
Alias for: default
defer(deferred_block, &block) click to toggle source

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

# 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) click to toggle source

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

# File lib/merb-core/dispatch/router/behavior.rb, line 547
def defer_to(params = {}, &block)
  defer(block).to(params)
end
fixatable(enable = true) click to toggle source

Specifies that a route can be fixatable.

Parameters

enabled<Boolean>

True enables fixation on the route.

:api: public

# File lib/merb-core/dispatch/router/behavior.rb, line 614
def fixatable(enable = true)
  @route.fixation = enable
  self
end
full_name(name) click to toggle source

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

# 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) click to toggle source

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

# 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) click to toggle source

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

# 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) click to toggle source

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

# 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) click to toggle source

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

# 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
options(opts = {}, &block) click to toggle source

Allows the fine tuning of certain router options.

Parameters

options<Hash>

The options to set for all routes defined in the scope. The currently supported options are:

  • :controller_prefix - The module that the controller is included in.

  • :name_prefix - The prefix added to all routes named with name

&block

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

Block parameters

r<Behavior>

The options behavior object. This is optional

Examples

# If :group is not matched in the path, it will be "registered" instead
# of nil.
match("/users(/:group)").default(:group => "registered")

:api: public

# File lib/merb-core/dispatch/router/behavior.rb, line 394
def options(opts = {}, &block)
  options = @options.dup
  
  opts.each_pair do |key, value|
    options[key] = (options[key] || []) + [value.freeze] if value
  end
  
  behavior = Behavior.new(@proxy, @conditions, @params, @defaults, @identifiers, options, @blocks)
  with_behavior_context(behavior, &block)
end
Also aliased as: options
redirect(url, opts = {}) click to toggle source

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

# 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
register(params = {}, &block) click to toggle source

Equivalent of to. Allows for nicer syntax when registering routes with no params

Examples

Merb::Router.prepare do

match("/:controller(/:action(/:id))(.:format)").register

end

Alias for: to
to(params = {}, &block) click to toggle source

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

# 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
Also aliased as: with, register
with(params = {}, &block) click to toggle source

Equivalent of to. Allows for some nicer syntax when scoping blocks

Examples

Merb::Router.prepare do

with(:controller => "users") do
  match("/signup").to(:action => "signup")
  match("/login").to(:action => "login")
  match("/logout").to(:action => "logout")
end

end

Alias for: to

Protected Instance Methods

_route() click to toggle source

Returns the current route.

Returns

Route

the route.

:api: private

# File lib/merb-core/dispatch/router/behavior.rb, line 687
def _route
  @route
end
before(route, &block) click to toggle source

Allows to insert the route at a certain spot in the list of routes instead of appending to the list.

Params

route<Route>

the route to insert before.

&block

the route definition to insert.

:api: plugin

# File lib/merb-core/dispatch/router/behavior.rb, line 739
def before(route, &block)
  options(:before => route, &block)
end
to_route() click to toggle source

Turns a route definition into a Route object.

Returns

Route

the route generated.

:api: private

# File lib/merb-core/dispatch/router/behavior.rb, line 697
def to_route
  raise Error, "The route has already been committed." if @route
  
  controller = @params[:controller]
  
  if prefixes = @options[:controller_prefix]
    controller ||= ":controller"
    
    prefixes.reverse_each do |prefix|
      break if controller =~ %{^/(.*)} && controller = $1
      controller = "#{prefix}/#{controller}"
    end
  end
  
  @params.merge!(:controller => controller.to_s.gsub(%{^/}, '')) if controller

  # Normalise action into a string
  @params[:action] = @params[:action].to_s if @params.has_key?(:action)
  
  # Sorts the identifiers so that modules that are at the bottom of the
  # inheritance chain come first (more specific modules first). Object
  # should always be last.
  identifiers = @identifiers.sort { |(first,_),(sec,_)| first <=> sec || 1 }
  
  @route = Route.new(@conditions.dup,@params, @blocks, :defaults => @defaults.dup, :identifiers => identifiers)
  
  if before = @options[:before] && @options[:before].last
    @route.register_at(Router.routes.index(before))
  else
    @route.register
  end
  self
end

[Validate]

Generated with the Darkfish Rdoc Generator 2.