From 53152dccd205564d23c643c492818ff405e40ebf Mon Sep 17 00:00:00 2001 From: schneems Date: Tue, 23 Aug 2016 12:56:58 -0500 Subject: Fully document asset_path. --- .../lib/action_view/helpers/asset_url_helper.rb | 65 +++++++++++++++++++--- 1 file changed, 58 insertions(+), 7 deletions(-) (limited to 'actionview') diff --git a/actionview/lib/action_view/helpers/asset_url_helper.rb b/actionview/lib/action_view/helpers/asset_url_helper.rb index ba695791b1..c5b5e77178 100644 --- a/actionview/lib/action_view/helpers/asset_url_helper.rb +++ b/actionview/lib/action_view/helpers/asset_url_helper.rb @@ -118,16 +118,67 @@ module ActionView module AssetUrlHelper URI_REGEXP = %r{^[-a-z]+://|^(?:cid|data):|^//}i - # Computes the path to asset in public directory. If :type - # options is set, a file extension will be appended and scoped - # to the corresponding public directory. + # This is the entry point for all assets. + # When using the asset pipeline (i.e. sprockets and sprockets-rails), the + # behavior is "enhanced". You can bypass the asset pipeline by passing in + # `public_folder: true` to the options. # # All other asset *_path helpers delegate through this method. # - # asset_path "application.js" # => /assets/application.js - # asset_path "application", type: :javascript # => /assets/application.js - # asset_path "application", type: :stylesheet # => /assets/application.css - # asset_path "http://www.example.com/js/xmlhr.js" # => http://www.example.com/js/xmlhr.js + # === With the asset pipeline + # + # All options passed to asset_path will be passed to `compute_asset_path + # which is implemented by sprockets-rails. + # + # asset_path("application.js") # => "/assets/application-60aa4fdc5cea14baf5400fba1abf4f2a46a5166bad4772b1effe341570f07de9.js" + # + # === Without the asset pipeline (`public_folder: true`) + # + # Accepts a `type` option that can specify the asset's extension. No error + # checking is done to verify the source passed into `asset_path` is valid + # and that the file exists on disk. + # + # asset_path("application.js", public_folder: true) # => "application.js" + # asset_path("filedoesnotexist.png", public_folder: true) # => "filedoesnotexist.png" + # asset_path("application", type: :javascript, public_folder: true) # => "/javascripts/application.js" + # asset_path("application", type: :stylesheet, public_folder: true) # => "/stylesheets/application.css" + # + # === Options applying to all assets + # + # Below lists scenarios that apply to `asset_path` whether or not you're + # using the asset pipeline. + # + # - All fully qualified urls are returned immediately. This bypasses the + # asset pipeline and all other behavior described. + # + # asset_path("http://www.example.com/js/xmlhr.js") # => "http://www.example.com/js/xmlhr.js" + # + # - All assets that begin with a forward slash are assumed to be full + # urls and will not be expanded. This will bypass the asset pipeline. + # + # asset_path("/foo.png") # => "/foo.png" + # + # - All blank strings will be returned immediately. This bypasses the + # asset pipeline and all other behavior described. + # + # asset_path("") # => "" + # + # - If `config.relative_url_root` is specified, all assets will have that + # root prepended. + # + # Rails.application.config.relative_url_root = "bar" + # asset_path("foo.js", public_folder: true) # => "bar/foo.js" + # + # - A different asset host can be specified via `config.action_controller.asset_host` + # this is commonly used in conjunction with a CDN. + # + # Rails.application.config.action_controller.asset_host = "assets.example.com" + # asset_path("foo.js", public_folder: true) # => "http://assets.example.com/foo.js" + # + # - An extension name can be specified manually with `extname`. + # + # asset_path("foo", public_folder: true, extname: ".js") # => "/foo.js" + # asset_path("foo.css", public_folder: true, extname: ".js") # => "/foo.css.js" def asset_path(source, options = {}) raise ArgumentError, "nil is not a valid asset source" if source.nil? -- cgit v1.2.3