Class: Merb::Router::Behavior

Proxy routes with the default behaviors.

Parameters

&block:

defines routes within the provided context.

:api: private

     # File merb-core/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)

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

[Source]

     # File merb-core/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}", '').to_sym unless name_prefix.empty?
660:           captured_routes[name] = route
661:         end
662:         
663:         captured_routes
664:       end

default(defaults = {}, &block)

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

[Source]

     # File merb-core/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

default_routes(params = {}, &block)

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

[Source]

     # File merb-core/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)

Alias for default

defer(deferred_block, &block)

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

[Source]

     # File merb-core/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)

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

[Source]

     # File merb-core/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)

Specifies that a route can be fixatable.

Parameters

enabled<Boolean>:

True enables fixation on the route.

:api: public

[Source]

     # File merb-core/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)

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

[Source]

     # File merb-core/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)

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

[Source]

     # File merb-core/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)

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

[Source]

     # File merb-core/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)

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

[Source]

     # File merb-core/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)

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

[Source]

     # File merb-core/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)

Alias for options

options(opts = {}, &block)

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

[Source]

     # File merb-core/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

redirect(url, opts = {})

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

[Source]

     # File merb-core/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)

Alias for to

to(params = {}, &block)

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

Route:

It registers a new route and returns it.

Examples

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

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

:api: public

[Source]

     # File merb-core/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

with(params = {}, &block)

Alias for to

_route()

Returns the current route.

Returns

Route:

the route.

:api: private

[Source]

     # File merb-core/lib/merb-core/dispatch/router/behavior.rb, line 687
687:       def _route
688:         @route
689:       end

before(route, &block)

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

[Source]

     # File merb-core/lib/merb-core/dispatch/router/behavior.rb, line 736
736:       def before(route, &block)
737:         options(:before => route, &block)
738:       end

to_route()

Turns a route definition into a Route object.

Returns

Route:

the route generated.

:api: private

[Source]

     # File merb-core/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 =~ %r{^/(.*)} && controller = $1
707:             controller = "#{prefix}/#{controller}"
708:           end
709:         end
710:         
711:         @params.merge!(:controller => controller.to_s.gsub(%r{^/}, '')) if controller
712:         
713:         # Sorts the identifiers so that modules that are at the bottom of the
714:         # inheritance chain come first (more specific modules first). Object
715:         # should always be last.
716:         identifiers = @identifiers.sort { |(first,_),(sec,_)| first <=> sec || 1 }
717:         
718:         @route = Route.new(@conditions.dup,@params, @blocks, :defaults => @defaults.dup, :identifiers => identifiers)
719:         
720:         if before = @options[:before] && @options[:before].last
721:           @route.register_at(Router.routes.index(before))
722:         else
723:           @route.register
724:         end
725:         self
726:       end

Methods

Included Modules

Classes and Modules

Public Instance methods

Parameters

Parameters

Block parameters

Parameters

Returns

Examples

Examples

Parameters

Returns

Note

Examples

Parameters

Parameters

Raises

Paramters

Block parameters

Parameters

Block parameters

Returns

Examples

Parameters

Raises

Parameters

Options (opts)

Block parameters

Examples

Parameters

Block parameters

Examples

Parameters

Options (opts)

Parameters

Block parameters

Returns

Examples

Protected Instance methods

Returns

Params

Returns