Module: Lotus::Assets::Helpers

Includes:: Helpers::HtmlHelper

Defined in:: lib/lotus/assets/helpers.rb

Overview

HTML assets helpers

Include this helper in a view

See Also:

http://www.rubydoc.info/gems/lotus-helpers/Lotus/Helpers/HtmlHelper

Since:

0.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:

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

Class Method Summary collapse

.included(base) ⇒ Object private

Inject helpers into the given class.

Instance Method Summary collapse

#asset_path(source) ⇒ String

It generates the relative URL for the given source.
#asset_url(source) ⇒ String

It generates the absolute URL for the given source.
#audio(source = nil, options = {}, &blk) ⇒ Lotus::Utils::Helpers::HtmlBuilder

Generate audio tag for given source.
#favicon(source = DEFAULT_FAVICON, options = {}) ⇒ Lotus::Utils::Helpers::HtmlBuilder

Generate link tag application favicon.
#image(source, options = {}) ⇒ Lotus::Utils::Helpers::HtmlBuilder

Generate img tag for given source.
#javascript(*sources) ⇒ Lotus::Utils::Escape::SafeString

Generate script tag for given source(s).
#stylesheet(*sources) ⇒ Lotus::Utils::Escape::SafeString

Generate link tag for given source(s).
#video(source = nil, options = {}, &blk) ⇒ Lotus::Utils::Helpers::HtmlBuilder

Generate video tag for given source.

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

# File 'lib/lotus/assets/helpers.rb', line 63

def self.included(base)
  conf = ::Lotus::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) ⇒ `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 Digest mode is on, it returns the digest path of the source

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

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"

Digest Mode


<%= asset_path 'application.js' %>

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

CDN Mode


<%= asset_path 'application.js' %>

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

Parameters:

source (String) —

the asset name

Returns:

(String) —

the asset path

Raises:

(Lotus::Assets::MissingDigestAssetError) —

if digest mode is on and the asset is missing from the manifest

Since:

0.1.0



606
607
608

# File 'lib/lotus/assets/helpers.rb', line 606

def asset_path(source)
  _asset_url(source) { _relative_url(source) }
end

#asset_url(source) ⇒ `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 Digest mode is on, it returns the digest URL of the source

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

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"

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

Parameters:

source (String) —

the asset name

Returns:

(String) —

the asset URL

Raises:

(Lotus::Assets::MissingDigestAssetError) —

if digest mode is on and the asset is missing from the manifest

Since:

0.1.0



653
654
655

# File 'lib/lotus/assets/helpers.rb', line 653

def asset_url(source)
  _asset_url(source) { _absolute_url(source) }
end

#audio(source = nil, options = {}, &blk) ⇒ `Lotus::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 “digest mode” is on, src is the digest version of the relative URL.

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

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

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

Parameters:

source (String) (defaults to: nil) —

asset name or absolute URL

Returns:

(Lotus::Utils::Helpers::HtmlBuilder) —

the builder

Raises:

(Lotus::Assets::MissingDigestAssetError) —

if digest mode is on and the image is missing from the manifest
(ArgumentError) —

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

See Also:

Since:

0.1.0

# File 'lib/lotus/assets/helpers.rb', line 558

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

#favicon(source = DEFAULT_FAVICON, options = {}) ⇒ `Lotus::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 “digest mode” is on, href is the digest version of the relative URL.

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

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 id: 'fav' %>

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

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

Parameters:

source (String) (defaults to: DEFAULT_FAVICON) —

asset name

Returns:

(Lotus::Utils::Helpers::HtmlBuilder) —

the builder

Raises:

(Lotus::Assets::MissingDigestAssetError) —

if digest mode is on and the favicon is missing from the manifest

See Also:

Since:

0.1.0

# File 'lib/lotus/assets/helpers.rb', line 319

def favicon(source = DEFAULT_FAVICON, options = {})
  options[:href]   = asset_path(source)
  options[:rel]  ||= FAVICON_REL
  options[:type] ||= FAVICON_MIME_TYPE

  html.link(options)
end

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

Generate img tag for given source

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

If the “digest mode” is on, src is the digest version of the relative URL.

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

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

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

Parameters:

source (String) —

asset name or absolute URL

Returns:

(Lotus::Utils::Helpers::HtmlBuilder) —

the builder

Raises:

(Lotus::Assets::MissingDigestAssetError) —

if digest mode is on and the image is missing from the manifest

See Also:

Since:

0.1.0

# File 'lib/lotus/assets/helpers.rb', line 258

def image(source, options = {})
  options[:src] = asset_path(source)
  options[:alt] ||= Utils::String.new(::File.basename(source, WILDCARD_EXT)).titleize

  html.img(options)
end

#javascript(*sources) ⇒ `Lotus::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 “digest mode” is on, src is the digest version of the relative URL.

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

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>

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>

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

Parameters:

sources (Array<String>) —

one or more assets by name or absolute URL

Returns:

(Lotus::Utils::Escape::SafeString) —

the markup

Raises:

(Lotus::Assets::MissingDigestAssetError) —

if digest mode is on and at least one of the given sources is missing from the manifest

See Also:

Since:

0.1.0

# File 'lib/lotus/assets/helpers.rb', line 128

def javascript(*sources)
  _safe_tags(*sources) do |source|
    html.script(src: _typed_asset_path(source, JAVASCRIPT_EXT), type: JAVASCRIPT_MIME_TYPE).to_s
  end
end

#stylesheet(*sources) ⇒ `Lotus::Utils::Escape::SafeString`

Generate link tag for given source(s)

If the “digest mode” is on, href is the digest version of the relative URL.

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

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

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

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

Parameters:

sources (Array<String>) —

one or more assets by name or absolute URL

Returns:

(Lotus::Utils::Escape::SafeString) —

the markup

Raises:

(Lotus::Assets::MissingDigestAssetError) —

if digest mode is on and at least one of the given sources is missing from the manifest

See Also:

Since:

0.1.0

# File 'lib/lotus/assets/helpers.rb', line 189

def stylesheet(*sources)
  _safe_tags(*sources) do |source|
    html.link(href: _typed_asset_path(source, STYLESHEET_EXT), type: STYLESHEET_MIME_TYPE, rel: STYLESHEET_REL).to_s
  end
end

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

Generate video tag for given source

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

If the “digest mode” is on, src is the digest version of the relative URL.

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

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

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

Parameters:

source (String) (defaults to: nil) —

asset name or absolute URL

Returns:

(Lotus::Utils::Helpers::HtmlBuilder) —

the builder

Raises:

(Lotus::Assets::MissingDigestAssetError) —

if digest mode is on and the image is missing from the manifest
(ArgumentError) —

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

See Also:

Since:

0.1.0

# File 'lib/lotus/assets/helpers.rb', line 440

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

Module: Lotus::Assets::Helpers

Overview

Constant Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.included(base) ⇒ Object

Instance Method Details

#asset_path(source) ⇒ String

#asset_url(source) ⇒ String

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

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

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

#javascript(*sources) ⇒ Lotus::Utils::Escape::SafeString

#stylesheet(*sources) ⇒ Lotus::Utils::Escape::SafeString

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

.included(base) ⇒ `Object`

#asset_path(source) ⇒ `String`

#asset_url(source) ⇒ `String`

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

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

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

#javascript(*sources) ⇒ `Lotus::Utils::Escape::SafeString`

#stylesheet(*sources) ⇒ `Lotus::Utils::Escape::SafeString`

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