Module: Hanami::Helpers::AssetsHelper Private

Includes:
View::Helpers::TagHelper
Included in:
Extensions::View::StandardHelpers
Defined in:
lib/hanami/helpers/assets_helper.rb

Overview

This module is part of a private API. You should avoid using this module if possible, as it may be removed or be changed in the future.

HTML assets helpers

Inject these helpers in a view

Constant Summary collapse

NEW_LINE_SEPARATOR =

This constant is part of a private API. You should avoid using this constant if possible, as it may be removed or be changed in the future.

Since:

  • 2.1.0

"\n"
WILDCARD_EXT =

This constant is part of a private API. You should avoid using this constant if possible, as it may be removed or be changed in the future.

Since:

  • 2.1.0

".*"
JAVASCRIPT_EXT =

This constant is part of a private API. You should avoid using this constant if possible, as it may be removed or be changed in the future.

Since:

  • 2.1.0

".js"
STYLESHEET_EXT =

This constant is part of a private API. You should avoid using this constant if possible, as it may be removed or be changed in the future.

Since:

  • 2.1.0

".css"
JAVASCRIPT_MIME_TYPE =

This constant is part of a private API. You should avoid using this constant if possible, as it may be removed or be changed in the future.

Since:

  • 2.1.0

"text/javascript"
STYLESHEET_MIME_TYPE =

This constant is part of a private API. You should avoid using this constant if possible, as it may be removed or be changed in the future.

Since:

  • 2.1.0

"text/css"
FAVICON_MIME_TYPE =

This constant is part of a private API. You should avoid using this constant if possible, as it may be removed or be changed in the future.

Since:

  • 2.1.0

"image/x-icon"
STYLESHEET_REL =

This constant is part of a private API. You should avoid using this constant if possible, as it may be removed or be changed in the future.

Since:

  • 2.1.0

"stylesheet"
FAVICON_REL =

This constant is part of a private API. You should avoid using this constant if possible, as it may be removed or be changed in the future.

Since:

  • 2.1.0

"shortcut icon"
DEFAULT_FAVICON =

This constant is part of a private API. You should avoid using this constant if possible, as it may be removed or be changed in the future.

Since:

  • 2.1.0

"favicon.ico"
CROSSORIGIN_ANONYMOUS =

This constant is part of a private API. You should avoid using this constant if possible, as it may be removed or be changed in the future.

Since:

  • 0.3.0

"anonymous"
ABSOLUTE_URL_MATCHER =

This constant is part of a private API. You should avoid using this constant if possible, as it may be removed or be changed in the future.

TODO: we can drop the defined?-check and fallback once Ruby 3.3 becomes our minimum required version

Since:

  • 0.3.0

(URI::RFC2396_PARSER) ? URI::RFC2396_PARSER : URI::DEFAULT_PARSER
).make_regexp
QUERY_STRING_MATCHER =

This constant is part of a private API. You should avoid using this constant if possible, as it may be removed or be changed in the future.

Since:

  • 1.1.0

/\?/

Instance Method Summary collapse

Instance Method Details

#asset_url(source) ⇒ String

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

It generates the relative or absolute URL for the given asset. It automatically decides if it has to use the relative or absolute depending on the configuration and current environment.

Absolute URLs are returned as they are.

It can be the name of the asset, coming from the sources or third party gems.

If Fingerprint mode is on, it returns the fingerprinted path of the source

If CDN mode is on, it returns the absolute URL of the asset.

‘subresource_integrity` modes are on and the asset is missing from the manifest

Examples:

Basic Usage


<%= asset_url "application.js" %>

# "/assets/application.js"

Alias


<%= asset_url "application.js" %>

# "/assets/application.js"

Absolute URL


<%= asset_url "https://code.jquery.com/jquery-2.1.4.min.js" %>

# "https://code.jquery.com/jquery-2.1.4.min.js"

Fingerprint Mode


<%= asset_url "application.js" %>

# "/assets/application-28a6b886de2372ee3922fcaf3f78f2d8.js"

CDN Mode


<%= asset_url "application.js" %>

# "https://assets.bookshelf.org/assets/application-28a6b886de2372ee3922fcaf3f78f2d8.js"

Parameters:

  • source (String, #url)

    the asset name or asset object

Returns:

  • (String)

    the asset path

Raises:

  • (Hanami::Assets::MissingManifestAssetError)

    if ‘fingerprint` or

Since:

  • 2.1.0



694
695
696
697
698
699
# File 'lib/hanami/helpers/assets_helper.rb', line 694

def asset_url(source)
  return source.url if source.respond_to?(:url)
  return source if _absolute_url?(source)

  _context.assets[source].url
end

#audio_tag(source = nil, options = {}, &blk) ⇒ Hanami::View::HTML::SafeString

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Generate ‘audio` tag for given source

It accepts one string representing the name of the asset, if it comes from the application or third party gems. It also accepts strings representing absolute URLs in case of public CDN (eg. Bootstrap CDN).

Alternatively, it accepts a block that allows to specify one or more sources via the ‘source` tag.

If the “fingerprint mode” is on, ‘src` is the fingerprinted version of the relative URL.

If the “CDN mode” is on, the ‘src` is an absolute URL of the application CDN.

‘subresource_integrity` modes are on and the audio file is missing from the manifest

Examples:

Basic Usage


<%= audio_tag "song.ogg" %>

# <audio src="/assets/song.ogg"></audio>

Absolute URL


<%= audio_tag "https://example-cdn.com/assets/song.ogg" %>

# <audio src="https://example-cdn.com/assets/song.ogg"></audio>

Custom HTML Attributes


<%= audio_tag("song.ogg", autoplay: true, controls: true) %>

# <audio src="/assets/song.ogg" autoplay="autoplay" controls="controls"></audio>

Fallback Content


<%=
  audio("song.ogg") do
    "Your browser does not support the audio tag"
  end
%>

# <audio src="/assets/song.ogg">
#  Your browser does not support the audio tag
# </audio>

Tracks


<%=
  audio("song.ogg") do
    tag.track(kind: "captions", src: asset_url("song.pt-BR.vtt"),
          srclang: "pt-BR", label: "Portuguese")
  end
%>

# <audio src="/assets/song.ogg">
#   <track kind="captions" src="/assets/song.pt-BR.vtt" srclang="pt-BR" label="Portuguese">
# </audio>

Without Any Argument


<%= audio_tag %>

# ArgumentError

Without src And Without Block


<%= audio_tag(controls: true) %>

# ArgumentError

Fingerprint Mode


<%= audio_tag "song.ogg" %>

# <audio src="/assets/song-28a6b886de2372ee3922fcaf3f78f2d8.ogg"></audio>

CDN Mode


<%= audio_tag "song.ogg" %>

# <audio src="https://assets.bookshelf.org/assets/song-28a6b886de2372ee3922fcaf3f78f2d8.ogg"></audio>

Parameters:

  • source (String, #url) (defaults to: nil)

    asset name, absolute URL or asset object

  • options (Hash) (defaults to: {})

    HTML 5 attributes

Returns:

  • (Hanami::View::HTML::SafeString)

    the markup

Raises:

  • (Hanami::Assets::MissingManifestAssetError)

    if ‘fingerprint` or

  • (ArgumentError)

    if source isn“t specified both as argument or tag inside the given block

See Also:

  • Assets::Helpers#path

Since:

  • 2.1.0



637
638
639
640
# File 'lib/hanami/helpers/assets_helper.rb', line 637

def audio_tag(source = nil, options = {}, &blk)
  options = _source_options(source, options, &blk)
  tag.audio(**options, &blk)
end

#content_security_policy_nonceString?

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Random per request nonce value for Content Security Policy (CSP) rules.

If the ‘Hanami::Middleware::ContentSecurityPolicyNonce` middleware is in use, this helper returns the nonce value for the current request or `nil` otherwise.

For this policy to work in the browser, you have to add the ‘’nonce’‘ placeholder to the script and/or style source policy rule. It will be substituted by the current nonce value like `’nonce-A12OggyZ’.

Examples:

App configuration


config.middleware.use Hanami::Middleware::ContentSecurityPolicyNonce
config.actions.content_security_policy[:script_src] = "'self' 'nonce'"
config.actions.content_security_policy[:style_src] = "'self' 'nonce'"

View helper


<script nonce="<%= content_security_policy_nonce %>">

Returns:

  • (String, nil)

    nonce value of the current request

Since:

  • 2.3.0



724
725
726
727
728
# File 'lib/hanami/helpers/assets_helper.rb', line 724

def content_security_policy_nonce
  return unless _context.request?

  _context.request.env[CONTENT_SECURITY_POLICY_NONCE_REQUEST_KEY]
end

#favicon_tag(source = DEFAULT_FAVICON, options = {}) ⇒ Hanami::View::HTML::SafeString

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Generate ‘link` tag application favicon.

If no argument is given, it assumes ‘favico.ico` from the application.

It accepts one string representing the name of the asset.

If the “fingerprint mode” is on, ‘href` is the fingerprinted version of the relative URL.

If the “CDN mode” is on, the ‘href` is an absolute URL of the application CDN.

‘subresource_integrity` modes are on and the favicon is file missing from the manifest

Examples:

Basic Usage


<%= favicon_tag %>

# <link href="/assets/favicon.ico" rel="shortcut icon" type="image/x-icon">

Custom Path


<%= favicon_tag "fav.ico" %>

# <link href="/assets/fav.ico" rel="shortcut icon" type="image/x-icon">

Custom HTML Attributes


<%= favicon_tag "favicon.ico", id: "fav" %>

# <link id="fav" href="/assets/favicon.ico" rel="shortcut icon" type="image/x-icon">

Fingerprint Mode


<%= favicon_tag %>

# <link href="/assets/favicon-28a6b886de2372ee3922fcaf3f78f2d8.ico" rel="shortcut icon" type="image/x-icon">

CDN Mode


<%= favicon_tag %>

# <link href="https://assets.bookshelf.org/assets/favicon-28a6b886de2372ee3922fcaf3f78f2d8.ico"
        rel="shortcut icon" type="image/x-icon">

Parameters:

  • source (String, #url) (defaults to: DEFAULT_FAVICON)

    asset name or asset object

  • options (Hash) (defaults to: {})

    HTML 5 attributes

Returns:

  • (Hanami::View::HTML::SafeString)

    the markup

Raises:

  • (Hanami::Assets::MissingManifestAssetError)

    if ‘fingerprint` or

See Also:

  • Assets::Helpers#path

Since:

  • 2.1.0



425
426
427
428
429
430
431
432
433
434
435
436
# File 'lib/hanami/helpers/assets_helper.rb', line 425

def favicon_tag(source = DEFAULT_FAVICON, options = {})
  options = options.reject { |k, _| k.to_sym == :href }

  attributes = {
    href: asset_url(source),
    rel: FAVICON_REL,
    type: FAVICON_MIME_TYPE
  }
  attributes.merge!(options)

  tag.link(**attributes)
end

#image_tag(source, options = {}) ⇒ Hanami::View::HTML::SafeString

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Generate ‘img` tag for given source

It accepts one string representing the name of the asset, if it comes from the application or third party gems. It also accepts strings representing absolute URLs in case of public CDN (eg. Bootstrap CDN).

‘alt` Attribute is auto generated from `src`. You can specify a different value, by passing the `:src` option.

If the “fingerprint mode” is on, ‘src` is the fingerprinted version of the relative URL.

If the “CDN mode” is on, the ‘src` is an absolute URL of the application CDN.

‘subresource_integrity` modes are on and the image file is missing from the manifest

Examples:

Basic Usage


<%= image_tag "logo.png" %>

# <img src="/assets/logo.png" alt="Logo">

Custom alt Attribute


<%= image_tag "logo.png", alt: "Application Logo" %>

# <img src="/assets/logo.png" alt="Application Logo">

Custom HTML Attributes


<%= image_tag "logo.png", id: "logo", class: "image" %>

# <img src="/assets/logo.png" alt="Logo" id="logo" class="image">

Absolute URL


<%= image_tag "https://example-cdn.com/images/logo.png" %>

# <img src="https://example-cdn.com/images/logo.png" alt="Logo">

Fingerprint Mode


<%= image_tag "logo.png" %>

# <img src="/assets/logo-28a6b886de2372ee3922fcaf3f78f2d8.png" alt="Logo">

CDN Mode


<%= image_tag "logo.png" %>

# <img src="https://assets.bookshelf.org/assets/logo-28a6b886de2372ee3922fcaf3f78f2d8.png" alt="Logo">

Parameters:

  • source (String, #url)

    asset name, absolute URL, or asset object

  • options (Hash) (defaults to: {})

    HTML 5 attributes

Returns:

  • (Hanami::View::HTML::SafeString)

    the markup

Raises:

  • (Hanami::Assets::MissingManifestAssetError)

    if ‘fingerprint` or

See Also:

  • Assets::Helpers#path

Since:

  • 2.1.0



359
360
361
362
363
364
365
366
367
368
# File 'lib/hanami/helpers/assets_helper.rb', line 359

def image_tag(source, options = {})
  options = options.reject { |k, _| k.to_sym == :src }
  attributes = {
    src: asset_url(source),
    alt: _context.inflector.humanize(::File.basename(source, WILDCARD_EXT))
  }
  attributes.merge!(options)

  tag.img(**attributes)
end

#javascript_tag(*sources, **options) ⇒ Hanami::View::HTML::SafeString

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Generate ‘script` tag for given source(s)

It accepts one or more strings representing the name of the asset, if it comes from the application or third party gems. It also accepts strings representing absolute URLs in case of public CDN (eg. jQuery CDN).

If the “fingerprint mode” is on, ‘src` is the fingerprinted version of the relative URL.

If the “CDN mode” is on, the ‘src` is an absolute URL of the application CDN.

If the “subresource integrity mode” is on, ‘integrity` is the name of the algorithm, then a hyphen, then the hash value of the file. If more than one algorithm is used, they“ll be separated by a space.

If the Content Security Policy uses ‘nonce’ and the source is not absolute, the nonce value of the current request is automatically added as an attribute. You can override this with the ‘nonce: false` option. See #content_security_policy_nonce for more.

‘subresource_integrity` modes are on and the javascript file is missing from the manifest

Examples:

Single Asset


<%= javascript_tag "application" %>

# <script src="/assets/application.js" type="text/javascript"></script>

Multiple Assets


<%= javascript_tag "application", "dashboard" %>

# <script src="/assets/application.js" type="text/javascript"></script>
# <script src="/assets/dashboard.js" type="text/javascript"></script>

Asynchronous Execution


<%= javascript_tag "application", async: true %>

# <script src="/assets/application.js" type="text/javascript" async="async"></script>

Subresource Integrity


<%= javascript_tag "application" %>

# <script src="/assets/application-28a6b886de2372ee3922fcaf3f78f2d8.js"
#         type="text/javascript" integrity="sha384-oqVu...Y8wC" crossorigin="anonymous"></script>

Subresource Integrity for 3rd Party Scripts


<%= javascript_tag "https://example.com/assets/example.js", integrity: "sha384-oqVu...Y8wC" %>

# <script src="https://example.com/assets/example.js" type="text/javascript"
#         integrity="sha384-oqVu...Y8wC" crossorigin="anonymous"></script>

Deferred Execution


<%= javascript_tag "application", defer: true %>

# <script src="/assets/application.js" type="text/javascript" defer="defer"></script>

Disable nonce


<%= javascript_tag "application", nonce: false %>

Absolute URL


<%= javascript_tag "https://code.jquery.com/jquery-2.1.4.min.js" %>

# <script src="https://code.jquery.com/jquery-2.1.4.min.js" type="text/javascript"></script>

Fingerprint Mode


<%= javascript_tag "application" %>

# <script src="/assets/application-28a6b886de2372ee3922fcaf3f78f2d8.js" type="text/javascript"></script>

CDN Mode


<%= javascript_tag "application" %>

# <script src="https://assets.bookshelf.org/assets/application-28a6b886de2372ee3922fcaf3f78f2d8.js"
#         type="text/javascript"></script>

Parameters:

  • sources (Array<String, #url>)

    one or more assets by name or absolute URL

Returns:

  • (Hanami::View::HTML::SafeString)

    the markup

Raises:

  • (Hanami::Assets::MissingManifestAssetError)

    if ‘fingerprint` or

See Also:

  • Assets::Helpers#path

Since:

  • 2.1.0



170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
# File 'lib/hanami/helpers/assets_helper.rb', line 170

def javascript_tag(*sources, **options)
  options = options.reject { |k, _| k.to_sym == :src }
  nonce_option = options.delete(:nonce)

  _safe_tags(*sources) do |source|
    attributes = {
      src: _typed_url(source, JAVASCRIPT_EXT),
      type: JAVASCRIPT_MIME_TYPE,
      nonce: _nonce(source, nonce_option)
    }
    attributes.merge!(options)

    if _context.assets.subresource_integrity? || attributes.include?(:integrity)
      attributes[:integrity] ||= _subresource_integrity_value(source, JAVASCRIPT_EXT)
      attributes[:crossorigin] ||= CROSSORIGIN_ANONYMOUS
    end

    tag.script(**attributes).to_s
  end
end

#stylesheet_tag(*sources, **options) ⇒ Hanami::View::HTML::SafeString

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Generate ‘link` tag for given source(s)

It accepts one or more strings representing the name of the asset, if it comes from the application or third party gems. It also accepts strings representing absolute URLs in case of public CDN (eg. Bootstrap CDN).

If the “fingerprint mode” is on, ‘href` is the fingerprinted version of the relative URL.

If the “CDN mode” is on, the ‘href` is an absolute URL of the application CDN.

If the “subresource integrity mode” is on, ‘integrity` is the name of the algorithm, then a hyphen, then the hashed value of the file. If more than one algorithm is used, they“ll be separated by a space.

If the Content Security Policy uses ‘nonce’ and the source is not absolute, the nonce value of the current request is automatically added as an attribute. You can override this with the ‘nonce: false` option. See #content_security_policy_nonce for more.

‘subresource_integrity` modes are on and the stylesheet file is missing from the manifest

Examples:

Single Asset


<%= stylesheet_tag "application" %>

# <link href="/assets/application.css" type="text/css" rel="stylesheet">

Multiple Assets


<%= stylesheet_tag "application", "dashboard" %>

# <link href="/assets/application.css" type="text/css" rel="stylesheet">
# <link href="/assets/dashboard.css" type="text/css" rel="stylesheet">

Disable nonce


<%= stylesheet_tag "application", nonce: false %>

Subresource Integrity


<%= stylesheet_tag "application" %>

# <link href="/assets/application-28a6b886de2372ee3922fcaf3f78f2d8.css"
#       type="text/css" integrity="sha384-oqVu...Y8wC" crossorigin="anonymous"></script>

Subresource Integrity for 3rd Party Assets


<%= stylesheet_tag "https://example.com/assets/example.css", integrity: "sha384-oqVu...Y8wC" %>

# <link href="https://example.com/assets/example.css"
#       type="text/css" rel="stylesheet" integrity="sha384-oqVu...Y8wC" crossorigin="anonymous"></script>

Absolute URL


<%= stylesheet_tag "https://maxcdn.bootstrapcdn.com/bootstrap/3.3.6/css/bootstrap.min.css" %>

# <link href="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.6/css/bootstrap.min.css"
#       type="text/css" rel="stylesheet">

Fingerprint Mode


<%= stylesheet_tag "application" %>

# <link href="/assets/application-28a6b886de2372ee3922fcaf3f78f2d8.css" type="text/css" rel="stylesheet">

CDN Mode


<%= stylesheet_tag "application" %>

# <link href="https://assets.bookshelf.org/assets/application-28a6b886de2372ee3922fcaf3f78f2d8.css"
#       type="text/css" rel="stylesheet">

Parameters:

  • sources (Array<String, #url>)

    one or more assets by name or absolute URL

Returns:

  • (Hanami::View::HTML::SafeString)

    the markup

Raises:

  • (Hanami::Assets::MissingManifestAssetError)

    if ‘fingerprint` or

See Also:

  • Assets::Helpers#path

Since:

  • 2.1.0



274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
# File 'lib/hanami/helpers/assets_helper.rb', line 274

def stylesheet_tag(*sources, **options)
  options = options.reject { |k, _| k.to_sym == :href }
  nonce_option = options.delete(:nonce)

  _safe_tags(*sources) do |source|
    attributes = {
      href: _typed_url(source, STYLESHEET_EXT),
      type: STYLESHEET_MIME_TYPE,
      rel: STYLESHEET_REL,
      nonce: _nonce(source, nonce_option)
    }
    attributes.merge!(options)

    if _context.assets.subresource_integrity? || attributes.include?(:integrity)
      attributes[:integrity] ||= _subresource_integrity_value(source, STYLESHEET_EXT)
      attributes[:crossorigin] ||= CROSSORIGIN_ANONYMOUS
    end

    tag.link(**attributes).to_s
  end
end

#video_tag(source = nil, options = {}, &blk) ⇒ Hanami::View::HTML::SafeString

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Generate ‘video` tag for given source

It accepts one string representing the name of the asset, if it comes from the application or third party gems. It also accepts strings representing absolute URLs in case of public CDN (eg. Bootstrap CDN).

Alternatively, it accepts a block that allows to specify one or more sources via the ‘source` tag.

If the “fingerprint mode” is on, ‘src` is the fingerprinted version of the relative URL.

If the “CDN mode” is on, the ‘src` is an absolute URL of the application CDN.

‘subresource_integrity` modes are on and the video file is missing from the manifest

Examples:

Basic Usage


<%= video_tag "movie.mp4" %>

# <video src="/assets/movie.mp4"></video>

Absolute URL


<%= video_tag "https://example-cdn.com/assets/movie.mp4" %>

# <video src="https://example-cdn.com/assets/movie.mp4"></video>

Custom HTML Attributes


<%= video_tag("movie.mp4", autoplay: true, controls: true) %>

# <video src="/assets/movie.mp4" autoplay="autoplay" controls="controls"></video>

Fallback Content


<%=
  video("movie.mp4") do
    "Your browser does not support the video tag"
  end
%>

# <video src="/assets/movie.mp4">
#  Your browser does not support the video tag
# </video>

Tracks


<%=
  video("movie.mp4") do
    tag.track(kind: "captions", src: asset_url("movie.en.vtt"),
          srclang: "en", label: "English")
  end
%>

# <video src="/assets/movie.mp4">
#   <track kind="captions" src="/assets/movie.en.vtt" srclang="en" label="English">
# </video>

Without Any Argument


<%= video_tag %>

# ArgumentError

Without src And Without Block


<%= video_tag(content: true) %>

# ArgumentError

Fingerprint Mode


<%= video_tag "movie.mp4" %>

# <video src="/assets/movie-28a6b886de2372ee3922fcaf3f78f2d8.mp4"></video>

CDN Mode


<%= video_tag "movie.mp4" %>

# <video src="https://assets.bookshelf.org/assets/movie-28a6b886de2372ee3922fcaf3f78f2d8.mp4"></video>

Parameters:

  • source (String, #url) (defaults to: nil)

    asset name, absolute URL or asset object

  • options (Hash) (defaults to: {})

    HTML 5 attributes

Returns:

  • (Hanami::View::HTML::SafeString)

    the markup

Raises:

  • (Hanami::Assets::MissingManifestAssetError)

    if ‘fingerprint` or

  • (ArgumentError)

    if source isn“t specified both as argument or tag inside the given block

See Also:

  • Assets::Helpers#path

Since:

  • 2.1.0



535
536
537
538
# File 'lib/hanami/helpers/assets_helper.rb', line 535

def video_tag(source = nil, options = {}, &blk)
  options = _source_options(source, options, &blk)
  tag.video(**options, &blk)
end