Module: Hanami::Assets::Helpers

Includes:
Helpers::HtmlHelper
Defined in:
lib/hanami/assets/helpers.rb

Overview

HTML assets helpers

Include this helper in a view

rubocop:disable Metrics/ModuleLength rubocop:disable Naming/UncommunicativeMethodParamName

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:

  • 0.1.0

"\n".freeze
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:

  • 0.1.0

'.*'.freeze
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:

  • 0.1.0

'.js'.freeze
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:

  • 0.1.0

'.css'.freeze
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:

  • 0.1.0

'text/javascript'.freeze
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:

  • 0.1.0

'text/css'.freeze
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:

  • 0.1.0

'image/x-icon'.freeze
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:

  • 0.1.0

'stylesheet'.freeze
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:

  • 0.1.0

'shortcut icon'.freeze
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:

  • 0.1.0

'favicon.ico'.freeze
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'.freeze
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

/\?/.freeze

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.included(base) ⇒ Object

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.

Inject helpers into the given class

Since:

  • 0.1.0


76
77
78
79
80
81
82
83
84
# File 'lib/hanami/assets/helpers.rb', line 76

def self.included(base)
  conf = ::Hanami::Assets::Configuration.for(base)
  base.class_eval do
    include Utils::ClassAttribute

    class_attribute :assets_configuration
    self.assets_configuration = conf
  end
end

Instance Method Details

#asset_path(source, push: false, as: nil) ⇒ String

It generates the relative URL for the given source.

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

Absolute URLs are returned as they are.

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_path 'application.js' %>

# "/assets/application.js"

Absolute URL


<%= asset_path 'https://code.jquery.com/jquery-2.1.4.min.js' %>

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

Fingerprint Mode


<%= asset_path 'application.js' %>

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

CDN Mode


<%= asset_path 'application.js' %>

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

Enable Push Promise/Early Hints


<%= asset_path "application.js", push: :script %>

Raises:

Since:

  • 0.1.0


772
773
774
# File 'lib/hanami/assets/helpers.rb', line 772

def asset_path(source, push: false, as: nil)
  _asset_url(source, push: push, as: as) { _relative_url(source) }
end

#asset_url(source, push: false, as: nil) ⇒ String

It generates the absolute URL for the given source.

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

Absolute URLs are returned as they are.

If Fingerprint mode is on, it returns the fingerprint URL 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' %>

# "https://bookshelf.org/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' %>

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

CDN Mode


<%= asset_url 'application.js' %>

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

Enable Push Promise/Early Hints


<%= asset_url "application.js", push: :script %>

Raises:

Since:

  • 0.1.0


826
827
828
# File 'lib/hanami/assets/helpers.rb', line 826

def asset_url(source, push: false, as: nil)
  _asset_url(source, push: push, as: as) { _absolute_url(source) }
end

#audio(source = nil, options = {}, &blk) ⇒ Hanami::Utils::Helpers::HtmlBuilder

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

<%=

audio do
  text "Your browser does not support the audio tag"
  source src: asset_path("song.ogg", push: :audio), type: "audio/ogg"
  source src: asset_path("song.wav"), type: "audio/wav"
end

%>

Examples:

Basic Usage


<%= audio 'song.ogg' %>

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

Absolute URL


<%= audio 'https://example-cdn.com/assets/song.ogg' %>

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

Custom HTML Attributes


<%= audio('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
    track(kind: 'captions', src:  asset_path('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>

Sources


<%=
  audio do
    text "Your browser does not support the audio tag"
    source(src: asset_path('song.ogg'), type: 'audio/ogg')
    source(src: asset_path('song.wav'), type: 'auido/wav')
  end
%>

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

Without Any Argument


<%= audio %>

# ArgumentError

Without src And Without Block


<%= audio(controls: true) %>

# ArgumentError

Fingerprint Mode


<%= audio 'song.ogg' %>

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

CDN Mode


<%= audio 'song.ogg' %>

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

Enable Push Promise/Early Hints


<%= audio 'movie.mp4', push: true %>

Options Hash (options):

  • :push (TrueClass, FalseClass)

    HTTP/2 Push Promise/Early Hints flag

Raises:

See Also:

Since:

  • 0.1.0


717
718
719
720
# File 'lib/hanami/assets/helpers.rb', line 717

def audio(source = nil, options = {}, &blk)
  options = _source_options(source, options, as: :audio, &blk)
  html.audio(blk, options)
end

#favicon(source = DEFAULT_FAVICON, options = {}) ⇒ Hanami::Utils::Helpers::HtmlBuilder

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

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

Custom Path


<%= favicon 'fav.ico' %>

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

Custom HTML Attributes


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

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

Fingerprint Mode


<%= favicon %>

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

CDN Mode


<%= favicon %>

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

Enable Push Promise/Early Hints


<%= favicon 'favicon.ico', push: true %>

Options Hash (options):

  • :push (TrueClass, FalseClass)

    HTTP/2 Push Promise/Early Hints flag

Raises:

See Also:

Since:

  • 0.1.0


443
444
445
446
447
448
449
450
451
452
453
454
# File 'lib/hanami/assets/helpers.rb', line 443

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

  attributes = {
    href: asset_path(source, push: options.delete(:push) || false, as: :image),
    rel: FAVICON_REL,
    type: FAVICON_MIME_TYPE
  }
  attributes.merge!(options)

  html.link(attributes)
end

#image(source, options = {}) ⇒ Hanami::Utils::Helpers::HtmlBuilder

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 'logo.png' %>

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

Custom alt Attribute


<%= image 'logo.png', alt: 'Application Logo' %>

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

Custom HTML Attributes


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

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

Absolute URL


<%= image 'https://example-cdn.com/images/logo.png' %>

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

Fingerprint Mode


<%= image 'logo.png' %>

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

CDN Mode


<%= image 'logo.png' %>

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

Enable Push Promise/Early Hints


<%= image 'logo.png', push: true %>

Options Hash (options):

  • :push (TrueClass, FalseClass)

    HTTP/2 Push Promise/Early Hints flag

Raises:

See Also:

Since:

  • 0.1.0


371
372
373
374
375
376
377
378
379
380
# File 'lib/hanami/assets/helpers.rb', line 371

def image(source, options = {})
  options = options.reject { |k, _| k.to_sym == :src }
  attributes = {
    src: asset_path(source, push: options.delete(:push) || false, as: :image),
    alt: Utils::String.titleize(::File.basename(source, WILDCARD_EXT))
  }
  attributes.merge!(options)

  html.img(attributes)
end

#javascript(*sources, push: true, **options) ⇒ Hanami::Utils::Escape::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.

It makes the script(s) eligible for HTTP/2 Push Promise/Early Hints. You can opt-out with inline option: `push: false`.

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

Examples:

Single Asset


<%= javascript 'application' %>

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

Multiple Assets


<%= javascript 'application', 'dashboard' %>

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

Asynchronous Execution


<%= javascript 'application', async: true %>

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

Subresource Integrity


<%= javascript 'application' %>

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

Subresource Integrity for 3rd Party Scripts


<%= javascript '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 'application', defer: true %>

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

Absolute URL


<%= javascript '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 'application' %>

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

CDN Mode


<%= javascript 'application' %>

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

Disable Push Promise/Early Hints


<%= javascript 'application', push: false %>
<%= javascript 'http://cdn.example.test/jquery.js', 'dashboard', push: false %>

Raises:

See Also:

Since:

  • 0.1.0


179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
# File 'lib/hanami/assets/helpers.rb', line 179

def javascript(*sources, push: true, **options) # rubocop:disable Metrics/MethodLength
  options = options.reject { |k, _| k.to_sym == :src }

  _safe_tags(*sources) do |source|
    attributes = {
      src: _typed_asset_path(source, JAVASCRIPT_EXT, push: push, as: :script),
      type: JAVASCRIPT_MIME_TYPE
    }
    attributes.merge!(options)

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

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

#stylesheet(*sources, push: true, **options) ⇒ Hanami::Utils::Escape::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.

It makes the script(s) eligible for HTTP/2 Push Promise/Early Hints. You can opt-out with inline option: `push: false`.

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

Examples:

Single Asset


<%= stylesheet 'application' %>

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

Multiple Assets


<%= stylesheet '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 'application' %>

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

Subresource Integrity for 3rd Party Assets


<%= stylesheet '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 '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 'application' %>

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

CDN Mode


<%= stylesheet 'application' %>

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

Disable Push Promise/Early Hints


<%= stylesheet 'application', push: false %>
<%= stylesheet 'http://cdn.example.test/bootstrap.css', 'dashboard', push: false %>

Raises:

See Also:

Since:

  • 0.1.0


280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
# File 'lib/hanami/assets/helpers.rb', line 280

def stylesheet(*sources, push: true, **options) # rubocop:disable Metrics/MethodLength
  options = options.reject { |k, _| k.to_sym == :href }

  _safe_tags(*sources) do |source|
    attributes = {
      href: _typed_asset_path(source, STYLESHEET_EXT, push: push, as: :style),
      type: STYLESHEET_MIME_TYPE,
      rel: STYLESHEET_REL
    }
    attributes.merge!(options)

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

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

#video(source = nil, options = {}, &blk) ⇒ Hanami::Utils::Helpers::HtmlBuilder

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

<%=

video do
  text "Your browser does not support the video tag"
  source src: asset_path("movie.mp4", push: :video), type: "video/mp4"
  source src: asset_path("movie.ogg"), type: "video/ogg"
end

%>

Examples:

Basic Usage


<%= video 'movie.mp4' %>

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

Absolute URL


<%= video 'https://example-cdn.com/assets/movie.mp4' %>

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

Custom HTML Attributes


<%= video('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
    track(kind: 'captions', src:  asset_path('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>

Sources


<%=
  video do
    text "Your browser does not support the video tag"
    source(src: asset_path('movie.mp4'), type: 'video/mp4')
    source(src: asset_path('movie.ogg'), type: 'video/ogg')
  end
%>

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

Without Any Argument


<%= video %>

# ArgumentError

Without src And Without Block


<%= video(content: true) %>

# ArgumentError

Fingerprint Mode


<%= video 'movie.mp4' %>

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

CDN Mode


<%= video 'movie.mp4' %>

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

Enable Push Promise/Early Hints


<%= video 'movie.mp4', push: true %>

Options Hash (options):

  • :push (TrueClass, FalseClass)

    HTTP/2 Push Promise/Early Hints flag

Raises:

See Also:

Since:

  • 0.1.0


584
585
586
587
# File 'lib/hanami/assets/helpers.rb', line 584

def video(source = nil, options = {}, &blk)
  options = _source_options(source, options, as: :video, &blk)
  html.video(blk, options)
end