Module: Hanami::Helpers::AssetsHelper

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

Overview

HTML assets helpers

Inject these helpers in a view

See Also:

Since:

  • 2.1.0

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.

Since:

  • 0.3.0

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_path) ⇒ String

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_path (String, #url) —

    the asset name or asset object

Returns:

  • (String) —

    the asset path

Raises:

  • (Hanami::Assets::MissingManifestAssetError) —

    if ‘fingerprint` or

Since:

  • 2.1.0



668
669
670
671
672
673
 
# File 'lib/hanami/helpers/assets_helper.rb', line 668

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

  _context.assets[source_path].url
end

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

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 string 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



611
612
613
614
 
# File 'lib/hanami/helpers/assets_helper.rb', line 611

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

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

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



399
400
401
402
403
404
405
406
407
408
409
410
 
# File 'lib/hanami/helpers/assets_helper.rb', line 399

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

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 string 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



333
334
335
336
337
338
339
340
341
342
 
# File 'lib/hanami/helpers/assets_helper.rb', line 333

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(*source_paths, **options) ⇒ Hanami::View::HTML::SafeString

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, ‘integriy` 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.

‘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>

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:

  • source_paths (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



157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
 
# File 'lib/hanami/helpers/assets_helper.rb', line 157

def javascript_tag(*source_paths, **options)
  options = options.reject { |k, _| k.to_sym == :src }

  _safe_tags(*source_paths) do |source|
    attributes = {
      src: _typed_path(source, JAVASCRIPT_EXT),
      type: JAVASCRIPT_MIME_TYPE
    }
    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(*source_paths, **options) ⇒ Hanami::View::HTML::SafeString

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, ‘integriy` 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.

‘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">

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:

  • source_paths (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



250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
 
# File 'lib/hanami/helpers/assets_helper.rb', line 250

def stylesheet_tag(*source_paths, **options)
  options = options.reject { |k, _| k.to_sym == :href }

  _safe_tags(*source_paths) do |source_path|
    attributes = {
      href: _typed_path(source_path, STYLESHEET_EXT),
      type: STYLESHEET_MIME_TYPE,
      rel: STYLESHEET_REL
    }
    attributes.merge!(options)

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

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

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

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 string 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



509
510
511
512
 
# File 'lib/hanami/helpers/assets_helper.rb', line 509

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