Parent

Included Modules

Class 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
672:       def _with_proxy(&block)
673:         proxy = Proxy.new
674:         proxy.push Behavior.new(proxy, @conditions, @params, @defaults, @identifiers, @options, @blocks)
675:         proxy.instance_eval(&block)
676:         proxy
677:       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
650:       def capture(&block)
651:         captured_routes = {}
652:         name_prefix     = [@options[:name_prefix]].flatten.compact.map { |p| "#{p}_"}
653:         current_names   = Merb::Router.named_routes.keys
654:         
655:         behavior = Behavior.new(@proxy, @conditions, @params, @defaults, @identifiers, @options, @blocks)
656:         with_behavior_context(behavior, &block)
657:         
658:         Merb::Router.named_routes.reject { |k,v| current_names.include?(k) }.each do |name, route|
659:           name = route.name.to_s.sub(/^#{name_prefix.join('|')}/, '').to_sym unless name_prefix.empty?
660:           captured_routes[name] = route
661:         end
662:         
663:         captured_routes
664:       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

The default values for named segments.

&block

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

Block parameters

r

optional - The defaults behavior object.

:api: public

     # File lib/merb-core/dispatch/router/behavior.rb, line 365
365:       def default(defaults = {}, &block)
366:         behavior = Behavior.new(@proxy, @conditions, @params, @defaults.merge(defaults), @identifiers, @options, @blocks)
367:         with_behavior_context(behavior, &block)
368:       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

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
515:       def default_routes(params = {}, &block)
516:         match("/:controller(/:action(/:id))(.:format)").to(params, &block).name(:default)
517:       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
564:       def defer(deferred_block, &block)
565:         blocks = @blocks + [CachedProc.new(deferred_block)]
566:         behavior = Behavior.new(@proxy, @conditions, @params, @defaults, @identifiers, @options, blocks)
567:         with_behavior_context(behavior, &block)
568:       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

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
547:       def defer_to(params = {}, &block)
548:         defer(block).to(params)
549:       end
fixatable(enable = true) click to toggle source

Specifies that a route can be fixatable.

Parameters

enabled

True enables fixation on the route.

:api: public

     # File lib/merb-core/dispatch/router/behavior.rb, line 614
614:       def fixatable(enable = true)
615:         @route.fixation = enable
616:         self
617:       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

The name of the route.

Raises

ArgumentError

symbol is not a Symbol.

:api: private

     # File lib/merb-core/dispatch/router/behavior.rb, line 597
597:       def full_name(name)
598:         raise Error, ":this is reserved. Please pick another name." if name == :this
599:         
600:         if @route
601:           @route.name = name
602:           self
603:         else
604:           register.full_name(name)
605:         end
606:       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 #).

The default method called on objects is #.

Paramters

identifiers

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

The identify behavior object. This is optional

:api: public

     # File lib/merb-core/dispatch/router/behavior.rb, line 475
475:       def identify(identifiers = {}, &block)
476:         identifiers = if Hash === identifiers
477:           @identifiers.merge(identifiers)
478:         else
479:           { Object => identifiers }
480:         end
481:         
482:         behavior = Behavior.new(@proxy, @conditions, @params, @defaults, identifiers.freeze, @options, @blocks)
483:         with_behavior_context(behavior, &block)
484:       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 # 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

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 # method.

Block parameters

r

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
280:       def match(path = {}, conditions = {}, &block)
281:         path, conditions = path[:path], path if path.is_a?(Hash)
282:         
283:         raise Error, "The route has already been committed. Further conditions cannot be specified" if @route
284:         
285:         conditions.delete_if { |k, v| v.nil? }
286:         conditions[:path] = merge_paths(path)
287:         
288:         behavior = Behavior.new(@proxy, @conditions.merge(conditions), @params, @defaults, @identifiers, @options, @blocks)
289:         with_behavior_context(behavior, &block)
290:       end
name(prefix, name = nil) click to toggle source

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

Parameters

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
579:       def name(prefix, name = nil)
580:         unless name
581:           name, prefix = prefix, nil
582:         end
583:         
584:         full_name([prefix, @options[:name_prefix], name].flatten.compact.join('_'))
585:       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

Optional hash (see below)

&block

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

Options (opts)

:path

match against this url

Block parameters

r

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
439:       def namespace(name_or_path, opts = {}, &block)
440:         name = name_or_path.to_s # We don't want this modified ever
441:         path = opts.has_key?(:path) ? opts[:path] : name
442:         
443:         raise Error, "The route has already been committed. Further options cannot be specified" if @route
444:         
445:         # option keys could be nil
446:         opts[:controller_prefix] = name unless opts.has_key?(:controller_prefix)
447:         opts[:name_prefix]       = name unless opts.has_key?(:name_prefix)
448:         opts[:resource_prefix]   = opts[:name_prefix] unless opts.has_key?(:resource_prefix)
449:         
450:         behavior = self
451:         behavior = behavior.match("/#{path}") unless path.nil? || path.empty?
452:         behavior.options(opts, &block)
453:       end
options(opts = {}, &block) click to toggle source
Alias for: options
options(opts = {}, &block) click to toggle source

Allows the fine tuning of certain router options.

Parameters

options

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 #

&block

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

Block parameters

r

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
394:       def options(opts = {}, &block)
395:         options = @options.dup
396:         
397:         opts.each_pair do |key, value|
398:           options[key] = (options[key] || []) + [value.freeze] if value
399:         end
400:         
401:         behavior = Behavior.new(@proxy, @conditions, @params, @defaults, @identifiers, options, @blocks)
402:         with_behavior_context(behavior, &block)
403:       end
Also aliased as: options
redirect(url, opts = {}) click to toggle source

Redirects the current route.

Parameters

path

The path to redirect to.

options

Options (see below)

Options (opts)

:permanent

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
633:       def redirect(url, opts = {})
634:         raise Error, "The route has already been committed." if @route
635:         
636:         status = opts[:permanent] ? 301 : 302
637:         @route = Route.new(@conditions, {:url => url.freeze, :status => status.freeze}, @blocks, :redirects => true)
638:         @route.register
639:         self
640:       end
register(params = {}, &block) click to toggle source

Equivalent of #. 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

The parameters the route maps to.

&block

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

Block parameters

r

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
317:       def to(params = {}, &block)
318:         raise Error, "The route has already been committed. Further params cannot be specified" if @route
319:         
320:         behavior = Behavior.new(@proxy, @conditions, @params.merge(params), @defaults, @identifiers, @options, @blocks)
321:         
322:         if block_given?
323:           with_behavior_context(behavior, &block)
324:         else
325:           behavior.to_route
326:         end
327:       end
Also aliased as: with, register
with(params = {}, &block) click to toggle source

Equivalent of #. 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
687:       def _route
688:         @route
689:       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

the route to insert before.

&block

the route definition to insert.

:api: plugin

     # File lib/merb-core/dispatch/router/behavior.rb, line 739
739:       def before(route, &block)
740:         options(:before => route, &block)
741:       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
697:       def to_route
698:         raise Error, "The route has already been committed." if @route
699:         
700:         controller = @params[:controller]
701:         
702:         if prefixes = @options[:controller_prefix]
703:           controller ||= ":controller"
704:           
705:           prefixes.reverse_each do |prefix|
706:             break if controller =~ %{^/(.*)} && controller = $1
707:             controller = "#{prefix}/#{controller}"
708:           end
709:         end
710:         
711:         @params.merge!(:controller => controller.to_s.gsub(%{^/}, '')) if controller
712: 
713:         # Normalise action into a string
714:         @params[:action] = @params[:action].to_s if @params.has_key?(:action)
715:         
716:         # Sorts the identifiers so that modules that are at the bottom of the
717:         # inheritance chain come first (more specific modules first). Object
718:         # should always be last.
719:         identifiers = @identifiers.sort { |(first,_),(sec,_)| first <=> sec || 1 }
720:         
721:         @route = Route.new(@conditions.dup,@params, @blocks, :defaults => @defaults.dup, :identifiers => identifiers)
722:         
723:         if before = @options[:before] && @options[:before].last
724:           @route.register_at(Router.routes.index(before))
725:         else
726:           @route.register
727:         end
728:         self
729:       end

Disabled; run with --debug to generate this.

[Validate]

Generated with the Darkfish Rdoc Generator 1.1.6.