Module: ActionDispatch::Routing::Mapper::Base

Included in:
ActionDispatch::Routing::Mapper
Defined in:
lib/action_dispatch/routing/mapper.rb

Instance Method Summary collapse

Instance Method Details

#default_url_options=(options) ⇒ Object Also known as: default_url_options 



650
651
652
 
# File 'lib/action_dispatch/routing/mapper.rb', line 650

def default_url_options=(options)
  @set.default_url_options = options
end

#has_named_route?(name) ⇒ Boolean

Query if the following named route was already defined.

Returns:

  • (Boolean) 


662
663
664
 
# File 'lib/action_dispatch/routing/mapper.rb', line 662

def has_named_route?(name)
  @set.named_routes.key?(name)
end

#match(path, options = nil) ⇒ Object

Matches a URL pattern to one or more routes.

You should not use the ‘match` method in your router without specifying an HTTP method.

If you want to expose your action to both GET and POST, use:

# sets :controller, :action, and :id in params
match ':controller/:action/:id', via: [:get, :post]

Note that ‘:controller`, `:action`, and `:id` are interpreted as URL query parameters and thus available through `params` in an action.

If you want to expose your action to GET, use ‘get` in the router:

Instead of:

match ":controller/:action/:id"

Do:

get ":controller/:action/:id"

Two of these symbols are special, ‘:controller` maps to the controller and `:action` to the controller’s action. A pattern can also map wildcard segments (globs) to params:

get 'songs/*category/:title', to: 'songs#show'

# 'songs/rock/classic/stairway-to-heaven' sets
#  params[:category] = 'rock/classic'
#  params[:title] = 'stairway-to-heaven'

To match a wildcard parameter, it must have a name assigned to it. Without a variable name to attach the glob parameter to, the route can’t be parsed.

When a pattern points to an internal route, the route’s ‘:action` and `:controller` should be set in options or hash shorthand. Examples:

match 'photos/:id', to: 'photos#show', via: :get
match 'photos/:id', controller: 'photos', action: 'show', via: :get

A pattern can also point to a ‘Rack` endpoint i.e. anything that responds to `call`:

match 'photos/:id', to: -> (hash) { [200, {}, ["Coming soon"]] }, via: :get
match 'photos/:id', to: PhotoRackApp, via: :get
# Yes, controller actions are just rack endpoints
match 'photos/:id', to: PhotosController.action(:show), via: :get

Because requesting various HTTP verbs with a single action has security implications, you must either specify the actions in the via options or use one of the [HttpHelpers](HttpHelpers) instead ‘match`

### Options

Any options not seen here are passed on as params with the URL.

:controller : The route’s controller.

:action : The route’s action.

:param : Overrides the default resource identifier ‘:id` (name of the dynamic

segment used to generate the routes). You can access that segment from
your controller using `params[<:param>]`. In your router:

    resources :users, param: :name

The `users` resource here will have the following routes generated for it:

    GET       /users(.:format)
    POST      /users(.:format)
    GET       /users/new(.:format)
    GET       /users/:name/edit(.:format)
    GET       /users/:name(.:format)
    PATCH/PUT /users/:name(.:format)
    DELETE    /users/:name(.:format)

You can override `ActiveRecord::Base#to_param` of a related model to
construct a URL:

    class User < ActiveRecord::Base
      def to_param
        name
      end
    end

    user = User.find_by(name: 'Phusion')
    user_path(user)  # => "/users/Phusion"

:path : The path prefix for the routes.

:module : The namespace for :controller.

    match 'path', to: 'c#a', module: 'sekret', controller: 'posts', via: :get
    # => Sekret::PostsController

See `Scoping#namespace` for its scope equivalent.

:as : The name used to generate routing helpers.

:via : Allowed HTTP verb(s) for route.

match 'path', to: 'c#a', via: :get
match 'path', to: 'c#a', via: [:get, :post]
match 'path', to: 'c#a', via: :all

:to : Points to a ‘Rack` endpoint. Can be an object that responds to `call` or a

string representing a controller's action.

    match 'path', to: 'controller#action', via: :get
    match 'path', to: -> (env) { [200, {}, ["Success!"]] }, via: :get
    match 'path', to: RackApp, via: :get

:on : Shorthand for wrapping routes in a specific RESTful context. Valid values

are `:member`, `:collection`, and `:new`. Only use within `resource(s)`
block. For example:

    resource :bar do
      match 'foo', to: 'c#a', on: :member, via: [:get, :post]
    end

Is equivalent to:

    resource :bar do
      member do
        match 'foo', to: 'c#a', via: [:get, :post]
      end
    end

:constraints : Constrains parameters with a hash of regular expressions or an object that

responds to `matches?`. In addition, constraints other than path can also
be specified with any object that responds to `===` (e.g. String, Array,
Range, etc.).

    match 'path/:id', constraints: { id: /[A-Z]\d{5}/ }, via: :get

    match 'json_only', constraints: { format: 'json' }, via: :get

    class PermitList
      def matches?(request) request.remote_ip == '1.2.3.4' end
    end
    match 'path', to: 'c#a', constraints: PermitList.new, via: :get

See `Scoping#constraints` for more examples with its scope equivalent.

:defaults : Sets defaults for parameters

    # Sets params[:format] to 'jpg' by default
    match 'path', to: 'c#a', defaults: { format: 'jpg' }, via: :get

See `Scoping#defaults` for its scope equivalent.

:anchor : Boolean to anchor a ‘match` pattern. Default is true. When set to false,

the pattern matches any request prefixed with the given path.

    # Matches any request starting with 'path'
    match 'path', to: 'c#a', anchor: false, via: :get

:format : Allows you to specify the default value for optional ‘format` segment or

disable it by supplying `false`.



587
588
 
# File 'lib/action_dispatch/routing/mapper.rb', line 587

def match(path, options = nil)
end

#mount(app = nil, deprecated_options = nil, as: DEFAULT, via: nil, at: nil, defaults: nil, constraints: nil, anchor: false, format: false, path: nil, internal: nil, **mapping, &block) ⇒ Object

Mount a Rack-based application to be used within the application.

mount SomeRackApp, at: "some_route"

For options, see ‘match`, as `mount` uses it internally.

All mounted applications come with routing helpers to access them. These are named after the class specified, so for the above example the helper is either ‘some_rack_app_path` or `some_rack_app_url`. To customize this helper’s name, use the ‘:as` option:

mount(SomeRackApp, at: "some_route", as: "exciting")

This will generate the ‘exciting_path` and `exciting_url` helpers which can be used to navigate to this mounted app.

Raises:

  • (ArgumentError) 


605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
 
# File 'lib/action_dispatch/routing/mapper.rb', line 605

def mount(app = nil, deprecated_options = nil, as: DEFAULT, via: nil, at: nil, defaults: nil, constraints: nil, anchor: false, format: false, path: nil, internal: nil, **mapping, &block)
  if deprecated_options.is_a?(Hash)
    as = assign_deprecated_option(deprecated_options, :as, :mount) if deprecated_options.key?(:as)
    via ||= assign_deprecated_option(deprecated_options, :via, :mount)
    at ||= assign_deprecated_option(deprecated_options, :at, :mount)
    defaults ||= assign_deprecated_option(deprecated_options, :defaults, :mount)
    constraints ||= assign_deprecated_option(deprecated_options, :constraints, :mount)
    anchor = assign_deprecated_option(deprecated_options, :anchor, :mount) if deprecated_options.key?(:anchor)
    format = assign_deprecated_option(deprecated_options, :format, :mount) if deprecated_options.key?(:format)
    path ||= assign_deprecated_option(deprecated_options, :path, :mount)
    internal ||= assign_deprecated_option(deprecated_options, :internal, :mount)
    assign_deprecated_options(deprecated_options, mapping, :mount)
  end

  path_or_action = at

  if app.nil?
    hash_app, hash_path = mapping.find { |key, _| key.respond_to?(:call) }
    mapping.delete(hash_app) if hash_app

    app ||= hash_app
    path_or_action ||= hash_path
  end

  raise ArgumentError, "A rack application must be specified" unless app.respond_to?(:call)
  raise ArgumentError, <<~MSG unless path_or_action
    Must be called with mount point

      mount SomeRackApp, at: "some_route"
      or
      mount(SomeRackApp => "some_route")
  MSG

  rails_app = rails_app? app
  as = app_name(app, rails_app) if as == DEFAULT

  target_as = name_for_action(as, path_or_action)
  via ||= :all

  match(path_or_action, to: app, as:, via:, defaults:, constraints:, anchor:, format:, path:, internal:, **mapping, &block)

  define_generate_prefix(app, target_as) if rails_app
  self
end

#with_default_scope(scope, &block) ⇒ Object 



655
656
657
658
659
 
# File 'lib/action_dispatch/routing/mapper.rb', line 655

def with_default_scope(scope, &block)
  scope(**scope) do
    instance_exec(&block)
  end
end