Template Helpers

#Template Helpers

Template helpers are methods which can be used to simplify HTML building. Fire.app provides a lot of built-in helpers and you can customize what you want.

##Content Helpers

These helpers handle duplicate work when building content.

• capture(&block)

The capture method allows you to extract part of a template into a variable. You can use this variable anywhere in your templates or layouts.

For example, below we put a section of template into the variable @today.

<% @today = capture do %>
  Today is
  <%= Time.now.to_date %>
<% end %>

To use the variable, just write this:

<%= @today %>

===

• content_for(symbol, &block)

This helper stores a block of markup in an identifier for later use. You can make subsequent calls to the stored content in other templates, helper modules or layouts by passing the identifier as an argument to content_for.

For example, we can write this inside the sidebar area in our layout template.

<%= yield :special_block %>

And write this in the "about" page:

<% content_for :special_block do %>
  <h2>Our boss says</h2>
  <p>Blah blah blah blah blah…</p>
<% end %>

This uses the same layout and shows "Our boss says" only in the "about" page.

===

• content_for?(symbol)

This helper checks whether any content has been captured yet using content_for. Continuing with the previous example, if we want every page without a special block to show a default link, we can change <%= yield :special_block %> to:

<% if content_for?(:special_block) %>
  <%= yield :special_block %>
<% else %>
  <a href="#">Special Discount!!!</a>
<% end %>

##Tag Helpers

Tag helpers are used to construct HTML "tags" within a view template.

• link_to(name, href, ...)

This helper creates a link tag with attributes.

<%= link_to("twitter", "http://twitter.com", :id => "twitter") %>
# => <a id="twitter" href="http://twitter.com">twitter</a>

===

• mail_to(email_address, …)

This helper creates a mailto link tag for the specified email_address.

<%= mail_to("[email protected]", "example mail address") %>
# => <a href="mailto:[email protected]">example mail address</a>

===

• content_tag(name, content, ...)

This helper returns an HTML block tag of type name surrounding the content, and attributes can be added. For example:

<%= content_tag(:p, "OOPS!", :class => "strong") %>
# => <p class="strong">OOPS!</p>

Nesting is also supported as shown here:

<%= content_tag(:div, content_tag(:p, "OOPS!"), :class => "strong", :id => "oops") %>

The code above returns the following:

<div id="oops" class="strong">
  <p>OOPS!</p>
</div>

===

• tag(name, ...)

This helper returns an empty HTML tag.

<%= tag("br") %>
# => <br />

===

• image_tag(src, ...)

This helper returns an img tag.

<%= image_tag("test.jpg") %>
# => <img src="test.jpg" />

===

• javascript_tag(...)

This helper is used to insert javascripts. As shown here:

<%= javascript_tag "alert('OOPS')" %>

The code above returns the following:

<script type="text/javascript">
//<![CDATA[
alert('OOPS')
//]]>
</script>

===

• javascript_include_tag(*sources)

This helper returns an HTML script tag for each of the sources provided. For example:

<%= javascript_include_tag "main" %>
# => <script src="/javascripts/main.js" type="text/javascript"></script>

===

• stylesheet_link_tag(*sources)

This helper returns a stylesheet link tag for the sources specified as arguments. For example:

<%= stylesheet_link_tag "main" %>
# => <link href="/stylesheets/main.css" media="screen" rel="stylesheet" type="text/css" />

##Escape Helpers

These process specified tags and formats that need to escape.

• html_escape(string)

This helper escapes HTML tags. It also has an alias: h.

===

• json_escape(string)

This helper escapes JSON. It also has an alias: j.

Lorem Ipsum Helpers

Fire.app also comes with some helpers to make filler texts and images. The idea is borrowed from Frank and Middleman.

lorem_word                    # returns a single sentence
lorem_words(argument)         # returns individual words, length base on its argument
lorem_sentence
lorem_sentences(argument)
lorem_paragraph
lorem_paragraphs(argument)
lorem_date                    # returns "ddd mmm dd, yyyy"
lorem_date("%Y/%m/%d", 2011..2013) # returns "yyyy/mm/dd". Year must be in between 2011 to 2013. 
lorem_date.to_date            # returns "yyyy-mm-dd"
lorem_name                    # returns full name
lorem_first_name
lorem_last_name
lorem_image("WIDTHxHEIGHT")   # returns a lorem image url

lorem_image("WIDTHxHEIGHT") uses http://placehold.it/ to generate lorem image url. Usually use this with image_tag. For example:

<%= image_tag(lorem_image("300x400")) %>
# => <img src="http://placehold.it/300x400" />

Or use it in HTML directly:

<img src="<%= lorem_image("300x400") %>" />
# => <img src="http://placehold.it/300x400" />

Traditional Chinese Lorem Ipsum Helpers

Fire.app also provide helpers for traditional Chinese:

• zh_lorem_word, zh_lorem_words
• zh_lorem_sentence, zh_lorem_sentences
• zh_lorem_paragraph, zh_lorem_paragraphs
• zh_lorem_name
• zh_lorem_name_pinyin
• zh_lorem_first_name
• zh_lorem_first_name_pinyin
• zh_lorem_last_name
• zh_lorem_last_name_pinyin
• zh_lorem_email

The helpers ending in "_pinyin" and the zh_lorem_email helper replace Chinese with Pinyin.

Pull requests are welcome if you want to provide these helpers in your own language.

##Custom Helper

You can customize your own helpers by creating a file named view_helpers.rb in the root folder. The idea is borrowed from Serve and Middleman. The file format looks like this:

module ViewHelpers
  def helper_name(arg1, arg2, ....)
      return "something"
  end
end

For example, take view_helpers.rb as shown here:

module ViewHelpers
  def lorem_menu(num)
    @list = ""
    (1..num).map do |list|
      @list += content_tag(:li, link_to(lorem_word, '#'));
    end
    return '<ul class="menu">'+@list+'</ul>'
  end
end

Now using <%= lorem_menu(3) %> returns a lorem menu:

<ul class="menu">
    <li><a href="#">adipisci</a></li>
    <li><a href="#">dolor</a></li>
    <li><a href="#">eum</a></li>
</ul>