Method: ActionDispatch::Routing::Mapper::CustomUrls#direct

Defined in:

actionpack/lib/action_dispatch/routing/mapper.rb

#direct(name, options = {}, &block) ⇒ Object

Define custom URL helpers that will be added to the application’s routes. This allows you to override and/or replace the default behavior of routing helpers, e.g:

direct :homepage do
  "https://rubyonrails.org"
end

direct :commentable do |model|
  [ model, anchor: model.dom_id ]
end

direct :main do
  { controller: "pages", action: "index", subdomain: "www" }
end

The return value from the block passed to ‘direct` must be a valid set of arguments for `url_for` which will actually build the URL string. This can be one of the following:

• A string, which is treated as a generated URL

• A hash, e.g. ‘{ controller: “pages”, action: “index” }`

• An array, which is passed to ‘polymorphic_url`

• An Active Model instance

• An Active Model class

NOTE: Other URL helpers can be called in the block but be careful not to invoke your custom URL helper again otherwise it will result in a stack overflow error.

You can also specify default options that will be passed through to your URL helper definition, e.g:

direct :browse, page: 1, size: 10 do |options|
  [ :products, options.merge(params.permit(:page, :size).to_h.symbolize_keys) ]
end

In this instance the ‘params` object comes from the context in which the block is executed, e.g. generating a URL inside a controller action or a view. If the block is executed where there isn’t a ‘params` object such as this:

Rails.application.routes.url_helpers.browse_path

then it will raise a ‘NameError`. Because of this you need to be aware of the context in which you will use your custom URL helper when defining it.

NOTE: The ‘direct` method can’t be used inside of a scope block such as ‘namespace` or `scope` and will raise an error if it detects that it is.

# File 'actionpack/lib/action_dispatch/routing/mapper.rb', line 2224

def direct(name, options = {}, &block)
  unless @scope.root?
    raise RuntimeError, "The direct method can't be used inside a routes scope block"
  end

  @set.add_url_helper(name, options, &block)
end