Module: Keynote::Rumble

Included in:

Presenter

Defined in:

lib/keynote/rumble.rb

Overview

HTML markup in Ruby.

To invoke Rumble, call the build_html method in a presenter.

1. Syntax

There are four basic forms:

tagname(content)

tagname(content, attributes)

tagname do
  content
end

tagname(attributes) do
  content
end

Example:

build_html do
  div :id => :content do
    h1 'Hello World', :class => :main
  end
end

<div id="content">
  <h1 class="main">Hello World</h1>
</div>

2. Element classes and IDs

You can easily add classes and IDs by hooking methods onto the container:

div.content! do
  h1.main 'Hello World'
end

You can mix and match as you'd like (div.klass.klass1.id!), but you can only provide content and attributes on the last call:

# This is not valid:
form(:action => :post).world do
  input
end

# But this is:
form.world(:action => :post) do
  input
end

3. Text

Sometimes you need to insert plain text:

p.author do
  text 'Written by '
  a 'Bluebie', :href => 'http://creativepony.com/'
  br
  text link_to 'Home', '/'
end

<p class="author">
  Written by
  <a href="http://creativepony.com/">Bluebie</a>
  <br>
  <a href="/">Home</a>
</p>

You can also insert literal text by returning it from a block (or passing it as a parameter to the non-block form of a tag method):

p.author do
  link_to 'Home', '/'
end

<p class="author">
  <a href="/">Home</a>
</p>

Be aware that Rumble ignores the string in a block if there's other tags there:

div.comment do
  div.author "BitPuffin"
  "<p>Silence!</p>"
end

<div class="comment">
  <div class="author">BitPuffin</div>
</div>

4. Escaping

The version of Rumble that's embedded in Keynote follows normal Rails escaping rules. When text enters Rumble (by returning it from a block, passing it as a parameter to a tag method, or using the text method), it's escaped if and only if html_safe? returns false. That means that Rails helpers generally don't need special treatment, but strings need to have html_safe called on them to avoid escaping.

5. In practice

class ArticlePresenter < Keynote::Presenter
  presents :article

  def published_at
    build_html do
      div.published_at do
        span.date publication_date
        span.time publication_time
      end
    end
  end

  def publication_date
    article.published_at.strftime("%A, %B %e").squeeze(" ")
  end

  def publication_time
    article.published_at.strftime("%l:%M%p").delete(" ")
  end
end

See Also:

• https://github.com/judofyr/rumble
• https://github.com/camping/mab

Author:

• Rumble is (c) 2011 Magnus Holm (https://github.com/judofyr).

• Documentation mostly borrowed from Mab, (c) 2012 Magnus Holm.

Defined Under Namespace

Classes: Error

Constant Summary

BASIC =

A basic set of commonly-used HTML tags. These are included as methods on all presenters by default.

%w[a b br button del div em form h1 h2 h3 h4 h5 h6 hr i img input
label li link ol optgroup option p pre script select span strong sub sup
table tbody td textarea tfoot th thead time tr ul]

COMPLETE =

A more complete set of HTML5 tags. You can use these by calling use_html_5_tags in a presenter's class body.

%w[abbr acronym address applet area article aside audio base
basefont bdo big blockquote body canvas caption center cite code col
colgroup command datalist dd details dfn dir dl dt embed fieldset
figcaption figure font footer frame frameset head header hgroup iframe
ins keygen kbd legend map mark menu meta meter nav noframes noscript
object output param progress q rp rt ruby s samp section small source
strike style summary title tt u var video wbr xmp]

Instance Method Summary

• #build_html ⇒ Object

  Generate HTML using Rumble tag methods.

• #text(str = nil, &blk) ⇒ Object

  Generate a text node.

Instance Method Details

#build_html ⇒ Object

Generate HTML using Rumble tag methods. If tag methods are called outside a build_html block, they'll raise an exception.

# File 'lib/keynote/rumble.rb', line 355

def build_html
  if defined?(@rumble_context)
    ctx = @rumble_context
  end
  @rumble_context = Context.new
  yield
  rumble_cleanup(ctx).to_s
end

#text(str = nil, &blk) ⇒ Object

Generate a text node. This is helpful in situations where an element contains both text and markup.

# File 'lib/keynote/rumble.rb', line 366

def text(str = nil, &blk)
  str = Rumble.html_escape(str || blk.call)

  if defined?(@rumble_context) && @rumble_context
    @rumble_context << str
  else
    str
  end
end