Module: Mtl::Rails::ViewHelpers

Defined in:
lib/mtl/rails/view_helpers.rb

Overview

Assortment of Rails view helpers to simplify rendering materialize css specific components like:

  • [Icons](#label-Icons),

  • [Avatars](#label-Avatars),

  • [Nav Toolbars / Headers](#label-Navbars+-2F+Headers)

  • or [Buttons](#label-Buttons)

## Buttons

Helper methods to create flat, raised and floating material UI buttons.

## Flat buttons

A simple flat button:

“‘erb <%= mtl_button_flat ’Cancel’, users_path %> “‘

A colored flat button:

“‘erb <%= mtl_button_flat ’Delete’, user_path(@user), class: ‘red-text’, method: :delete %> “‘

## Raised button

A default raised action button:

“‘erb <%= mtl_button “Next”, next_user_path %> “`

A raised button with a sprinkle of colour:

“‘erb <%= mtl_button “Ok”, ok_path, class: ’green darken-2’ “‘

## Floating button

A round red, large floating button:

“‘erb <%= mtl_button_floating :add, new_user_path, class: ’btn-large red’ “‘

#### Reference

# Navbars / Headers

Provides a helper to render a nice navbar, that is supposed to work on both mobile as well as desktops. It is meant to be used with the mtl-default-layout as defined by Marco.

Include the following in every template that requires a navbar:

“‘ <%= mtl_header t(’my.title’) %> “‘

To render with a custom additional header content, this is then simply appended after the title in the layout.

“‘erb <%= mtl_header ’Dashboard’ do %>

<ul class="right">
  <li>Current User: Hans</li>
  <li><%= link_to 'Logout', logout_path %></li>
</ul>

<%- end %> “‘

This renders the appropriate HTML snippet, see #materialize_header for more options.

#### Reference

## Avatars

A simple avatar link, without a picture

“‘erb <%= mtl_avatar_link ’/profile’, ‘John Doe’ %> “‘

Render a large avatar link, with a custom user picture:

“‘erb <%= mtl_avatar_link ’/profile’, ‘John Doe’, ‘/john_doe.png’, size: :large %> “‘

An avatar link, with a custom user picture and some html options

“‘erb <%= mtl_avatar_link ’/profile’, ‘John Doe’, ‘/john_doe.png’, class: :red %> “‘

### Unlinked avatars

A simple avatar, without a picture

“‘erb <%= mtl_avatar ’John Doe’ %> “‘

An avatar, with a picture

“‘erb <%= mtl_avatar ’John Doe’, ‘/john_doe.png’ %> “‘

An avatar, with a picture and some html options

“‘erb <%= mtl_avatar ’John Doe’, ‘/john_doe.png’, class: :red %> “‘

### Avatar initials

This helper generates the initials for the avatar, based on the person name. It supports combined names or emails, and will return either a single initial, either a 2 letter.

Examples:

“‘erb <%= mtl_avatar_initials ’John Doe’ %> “‘

# Icons

Renders using using Google Material Icon font:

“‘erb <%= mtl_icon :cloud # renders a “cloud” icon %> <%= mtl_icon :cloud, size: :large # renders a large cloud icon %>

<%= mtl_icon :alert, class: ‘right red’ # add custom classes %> “‘

#### Reference

# Card file for files collection

Basic usage: “‘erb <%= mtl_card_file ’Document Dolorem.jpg’, ‘/path/to/file.jpg’ %> “‘ “`html <a class=“card-panel” href=“/path/to/file.jpg” target=“_blank” title=“Document Dolorem.jpg”>

Document Dolorem.jpg

  image
  JPG

</a> “‘

With title option: “‘erb <%= mtl_card_file ’Document Dolorem.jpg’, ‘/path/to/file.jpg’,

title: 'foo' %>

“‘ “`html <a class=“card-panel” href=“/path/to/file.jpg” target=“_blank” title=“foo”>

foo
Document Dolorem.jpg

  image
  JPG

</a> “‘

With type option: “‘erb <%= mtl_card_file ’Document Dolorem.jpg’, ‘/path/to/file.jpg’,

type: 'bar' %>

“‘ “`html <a class=“card-panel” href=“/path/to/file.jpg” target=“_blank” title=“Document Dolorem.jpg”>

Document Dolorem.jpg

  insert_drive_file
  BAR

</a> “‘

With preview option: “‘erb <%= mtl_card_file ’Document Dolorem.jpg’, ‘/path/to/file.jpg’,

preview: '/path/to/preview.jpg' %>

“‘ “`html <a class=“card-panel card-panel-image” href=“/path/to/file.jpg” target=“_blank”

 title="Document Dolorem.jpg" style="background-image: url(/path/to/preview.jpg)">
Document Dolorem.jpg

  image
  JPG

</a> “‘

With delete option: “‘erb <%= mtl_card_file ’Document Dolorem.jpg’, ‘/path/to/file.jpg’,

delete: '/path/to/delete/the/file' %>

“‘ “`html <a class=“card-panel” href=“/path/to/file.jpg” target=“_blank” title=“Document Dolorem.jpg”>

Document Dolorem.jpg

  image
  JPG

close

</a> “‘

With confirm option: “‘erb <%= mtl_card_file ’Document Dolorem.jpg’, ‘/path/to/file.jpg’,

delete: '/path/to/delete/the/file',
confirm: 'Sure?' %>

“‘ “`html <a class=“card-panel” href=“/path/to/file.jpg” target=“_blank” title=“Document Dolorem.jpg”>

Document Dolorem.jpg

  image
  JPG

close

</a> “‘

# Navbars

Basic usage:

“‘haml

mtl_navbar do

Hello

“‘

Fixed navbar: “‘haml

mtl_navbar fixed: true do

Hello

“‘

Extended navbar: “‘haml

mtl_navbar do |nav|

Hello
= nav.extended do
  Hellobis

“‘

Extended and fixed navbar: “‘haml

mtl_navbar fixed: true do |nav|

Hello
= nav.extended do
  Hellobis

“‘

Instance Method Summary collapse

Instance Method Details

#mtl_avatar(name, image_url = nil, options = {}) ⇒ String

Renders an avatar, for the given name, with initials and an optional picture

Parameters:

  • name (String)
  • image_url (String) (defaults to: nil) —

    Optional image url for the avatar

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

    Additional options that can be passed to ‘link_to`

Options Hash (options):

  • :size (:small, :medium, :large)

Returns:

  • (String) —

    HTML safe ‘<span/>` tag



396
397
398
399
400
 
# File 'lib/mtl/rails/view_helpers.rb', line 396

def mtl_avatar(name, image_url = nil, options = {})
  options[:class] = ['mtl-avatar', options.delete(:size), options[:class]].compact
  image = (image_url.present? ? image_tag(image_url, alt: name) : '')
  content_tag :span, image + mtl_avatar_initials(name), options
end

#mtl_avatar_link(url, name, image_url = nil, options = {}) ⇒ String

Renders an avatar link, for the given url with the name’s initials

Parameters:

  • url (String)
  • name (String)
  • image_url (String) (defaults to: nil) —

    Optional image url for the avatar

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

    Additional options that can be passed to ‘link_to`

Options Hash (options):

  • :size (:small, :medium, :large)

Returns:

  • (String) —

    HTML safe ‘<a/>` tag



381
382
383
384
385
386
387
 
# File 'lib/mtl/rails/view_helpers.rb', line 381

def mtl_avatar_link(url, name, image_url = nil, options = {})
  options[:class] = [
    'mtl-avatar', Mtl.effects, options.delete(:size), options[:class]
  ].compact
  image = (image_url.present? ? image_tag(image_url, alt: name) : '')
  link_to image + mtl_avatar_initials(name), url, options
end

#mtl_button(label, url, options = {}) ⇒ String

Renders a visually raised button, i.e. the default button style.

Parameters:

  • label (String)
  • url (String)
  • options (Hash) (defaults to: {}) —

    Additional options passed to ‘link_to`

Returns:

  • (String) —

    HTML safe ‘<a/>` tag



343
344
345
346
 
# File 'lib/mtl/rails/view_helpers.rb', line 343

def mtl_button(label, url, options = {})
  options[:class] = ['btn', Mtl.effects, options[:class]].compact
  link_to label, url, options
end

#mtl_button_flat(label, url, options = {}) ⇒ String

Renders a flat button which does not visually lift like the raised buttons.

Parameters:

  • label (String)
  • url (String)
  • options (Hash) (defaults to: {}) —

    Additional options that can be passed to ‘link_to`

Returns:

  • (String) —

    HTML safe ‘<a/>` tag



302
303
304
305
 
# File 'lib/mtl/rails/view_helpers.rb', line 302

def mtl_button_flat(label, url, options = {})
  options[:class] = ['btn-flat', options[:class]].compact
  mtl_button label, url, options
end

#mtl_button_floating(icon, url, options = {}) ⇒ String

Renders a round floating button, with an icon as it’s label.

Parameters:

  • icon (Symbol)
  • url (String)
  • options (Hash) (defaults to: {}) —

    Additional options passed to ‘link_to`

Returns:

  • (String) —

    HTML safe ‘<a/>` tag



313
314
315
316
 
# File 'lib/mtl/rails/view_helpers.rb', line 313

def mtl_button_floating(icon, url, options = {})
  options[:class] = ['btn-floating', options[:class]].compact
  mtl_button mtl_icon(icon), url, options
end

#mtl_button_more(url, options = {}) ⇒ String

Renders a flat button with the more_vert icon dots in a wrapper element. This is intended to be used to render these “more buttons” on the right, in cards or the navbar.

“‘erb <%= mtl_button_more ’#dropdown’, ‘data-mtl-dropdown’: true %> “‘

Parameters:

  • url (String) —

    usually probably references the dropdown to trigger

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

    Additional options passed to ‘link_to`

Returns:

  • (String) —

    HTML safe ‘<a/>` tag



329
330
331
332
333
334
335
 
# File 'lib/mtl/rails/view_helpers.rb', line 329

def mtl_button_more(url, options = {})
  wrapper_class = ['btn-more-wrapper', options.delete(:wrapper_class)].compact
  options[:class] = ['btn-more', options[:class]].compact.flatten

  btn = mtl_button_flat mtl_icon(:more_vert, size: :tiny), url, options
  content_tag :div, btn, class: wrapper_class
end

#mtl_card_file(filename, href, options = {}) ⇒ String

Renders a card file tag to display the file and its informations, containing icons, file name, link and an optional preview

Parameters:

  • filename (String) —

    filename of the file

  • href (String) —

    url to pass to the link_to

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

    additional options passed to ‘content_tag`

Options Hash (options):

  • :title (String) —

    Title of the link, defaults to the filename

  • :type (String) —

    To specify a custom file type, which will serve to display the icon. Will default to the file type based on the ext

  • :preview (String) —

    URL to an image to use as the file preview

  • :data-mtl-delete (String) —

    URL to use as the delete action, if any

Returns:

  • (String) —

    HTML safe String



437
438
439
 
# File 'lib/mtl/rails/view_helpers.rb', line 437

def mtl_card_file(filename, href, options = {})
  CardFilePresenter.new(self).render(filename, href, options)
end

#mtl_header(title = translate('.title', default: 'Menu'), **options) { ... } ⇒ String

Renders a specialized template for the header.

Parameters:

  • title (String) (defaults to: translate('.title', default: 'Menu')) —

    with the header to display, when set to ‘false` or an empty string, the rendering of the `<h1>` tag is skipped. By default it tries to use a translation via `.title` key

  • back (String, Boolean) —

    (URL) with a link to return to the previous view, when this string is present, then the menu is skipped and this link is always present

  • menu (String, Boolean) —

    (HTML ID) references the id of the aside menu / default nav menu to show / hide on mobile devices. The default used is ‘nav-menu`. When set to `false`, this button is skipped.

  • class (String, Array) —

    (HTML CLASS) additional, custom css class on header

Yields:

  • Additional content to be rendered as part of the header, with a navbar object as argument, to also build the extended navigation if needed (by passing another block to nav.extended)

Returns:

  • (String) —

    HTML safe string



363
364
365
366
367
368
369
370
371
 
# File 'lib/mtl/rails/view_helpers.rb', line 363

def mtl_header(title = translate('.title', default: 'Menu'), **options, &block)
  mtl_class = ['mtl-layout-default-header', options[:class]].compact.flatten.join(' ')
  mtl_nav = NavbarPresenter.new(self)
  mtl_content = block_given? ? capture(mtl_nav, &block) : nil
  render file: 'mtl/header', locals: { mtl_title: title.presence, mtl_back: options.fetch(:back, false),
                                       mtl_menu: options.fetch(:menu, 'nav-menu'),
                                       mtl_fixed: options.fetch(:fixed, false), mtl_class: mtl_class,
                                       mtl_nav: mtl_nav, mtl_content: mtl_content }
end

#mtl_icon(icon, options = {}) ⇒ String

Renders an ‘<i class=“material-icons”>icon</i>` tag to display an icon.

Parameters:

  • icon (Symbol) —

    name of the icon to render, note that these are usually underscored, like e.g. ‘:aspect_ratio`

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

    additional options passed to ‘content_tag`

Options Hash (options):

  • :size (:tiny, :small, :medium, :large)

Returns:

  • (String) —

    HTML safe String



420
421
422
423
 
# File 'lib/mtl/rails/view_helpers.rb', line 420

def mtl_icon(icon, options = {})
  options[:class] = [Mtl.icon_class, options.delete(:size), options[:class]].compact
  content_tag :i, icon, options
end

#mtl_navbar(options = {}) { ... } ⇒ String

Renders a navbar, wrapping the given block as content. Options also allows to fix the navbar and/or include an extended navigation

Parameters:

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

    a customizable set of options

  • yield.extended (Hash) —

    a customizable set of options

Options Hash (options):

  • :fixed (Boolean) —

    Define if the header has to be fixed or not

  • :class (String/Array) —

    Additional class to add the to nav-wrapper

Yields:

  • Content to be rendered into the navbar, with a navbar object as argument, to also build the extended navigation if needed (by passing another block to nav.extended)

Returns:

  • (String) —

    HTML safe String



450
451
452
 
# File 'lib/mtl/rails/view_helpers.rb', line 450

def mtl_navbar(options = {}, &block)
  NavbarPresenter.new(self).render(options, &block)
end