Class | Merb::Router::Behavior |
In: |
merb-core/lib/merb-core/dispatch/router/behavior.rb
merb-core/lib/merb-core/dispatch/router/resources.rb |
Parent: | Object |
Proxy routes with the default behaviors.
&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 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 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
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.
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. |
r<Behavior>: | optional - The defaults behavior object. |
:api: public
# 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
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.
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. |
Route: | the default route |
# 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 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
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.
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 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
Takes a block and stores it for deferred conditional routes. The block takes the request object and the params hash as 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. |
Route : | The default route. |
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.
defer_to do |request, params| params.merge :controller => 'here', :action => 'there' if request.xhr? end
:api: public
# 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
Names this route in Router. Name must be a Symbol. The current name_prefix is ignored.
symbol<Symbol>: | The name of the route. |
ArgumentError: | symbol is not a Symbol. |
:api: private
# 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
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.
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. |
r<Behavior>: | The identify behavior object. This is optional |
:api: public
# 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
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.
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. |
r<Behavior>: | optional - The match behavior object. |
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.
# 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 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
Registers the route as a named route with the name given.
symbol<Symbol>: | the name of the route. |
ArgumentError: | symbol is not a Symbol. |
:api: public
# 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
Creates a namespace for a route. This way you can have logical separation to your routes.
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. |
:path<String>: | match against this url |
r<Behavior>: | The namespace behavior object. This is optional |
namespace :admin do resources :accounts resource :email end # /super_admin/accounts namespace(:admin, :path=>"super_admin") do resources :accounts end
:api: public
# 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
Allows the fine tuning of certain router options.
options<Hash>: | The options to set for all routes defined in the scope. The currently supported options are: |
&block: | All routes defined in the block will be scoped to the options defined by the options method. |
r<Behavior>: | The options behavior object. This is optional |
# If :group is not matched in the path, it will be "registered" instead # of nil. match("/users(/:group)").default(:group => "registered")
:api: public
# 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
Redirects the current route.
path<String>: | The path to redirect to. |
options<Hash>: | Options (see below) |
:permanent<Boolean>: | Whether or not the redirect should be permanent. The default value is false. |
:api: public
# 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
Creates a Route from one or more Behavior objects, unless a block is passed in.
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. |
r<Behavior>: | optional - The to behavior object. |
Route: | It registers a new route and returns it. |
match('/:controller/:id).to(:action => 'show') to(:controller => 'simple') do match('/test').to(:action => 'index') match('/other').to(:action => 'other') end
:api: public
# 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
Returns the current route.
Route: | the route. |
:api: private
# File merb-core/lib/merb-core/dispatch/router/behavior.rb, line 687 687: def _route 688: @route 689: end
Allows to insert the route at a certain spot in the list of routes instead of appending to the list.
route<Route>: | the route to insert before. |
&block: | the route definition to insert. |
:api: plugin
# File merb-core/lib/merb-core/dispatch/router/behavior.rb, line 736 736: def before(route, &block) 737: options(:before => route, &block) 738: end
Turns a route definition into a Route object.
Route: | the route generated. |
:api: private
# 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