Template Helpers

Helper 是一些能夠在樣板語言中使用的函式,能更簡單的達成許多建置網頁時不可或缺的功能。 Fire.app 提供許多好用的內建 Helper ,若是不敷使用的話也可以自己根據需求撰寫,以下先介紹部分內建 helper :

LiveReload

使用下面的程式碼可產出 livereload-js

<%= livereload_js %>

如果只想在開發時插入 LiveReload 程式碼但不想讓它出現在輸出的靜態網頁中,可以使用:

<%= livereload_js if ENV["RACK_ENV"] != "production" %>

Content Helpers

此類型的 Helpers 為建立網站內容提供許多好用的功能,能省去一些重複作業的麻煩。

capture(&block)

此 Helper 可以把樣板語言段落以變數的方式儲存供多次利用在同一 Layout 或頁面中,例如下面的範例便是把一段樣板語言儲存在變數 @today 中:

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

使用時只要在想輸出這個段落的位置寫:

<%= @today %>

就可以取得該段落的內容。

content_for(symbol, &block)

此 Helper 可以把樣板語言段落儲存在 symbol 中供後續利用,常應用在套用 Layout 時。例如側欄的區塊只有 About 頁面要顯示老闆的話而其他頁面不用時,可以在 Layout 中側欄的區塊中加入一段:

<%= yield :special_block %>

然後在 About 頁面檔案中寫入:

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

這樣 About 頁面的側欄就會出現老闆的話了,其他頁面也可以比照辦理。

content_for?(symbol)

此 Helper 可以用來判斷目前此 symbol 是否有任何值。例如前面 content_for 的範例寫到可以讓各頁面套用 Layout 的部分也擁有不同內容,如果想讓沒有寫入特別內容的頁面顯示預設的廣告連結,便可將原本寫入的<%= yield :special_block %>改寫成:

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

Tag Helpers

此類型的 Helpers 在動態產生 HTML 內容時很有幫助。

link_to(name, href, ...)

常用的 helper ,可產生帶有屬性的連結。如:

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

輸出為:

<a id="twitter" href="http://twitter.com">twitter</a>

mail_to(email_address, …)

此 Helper 可用於建立帶有 "mailto:" 的連結。如:

<%= mail_to("example@mail.com", "example mail address") %>

會輸出:

<a href="mailto:example@mail.com">example mail address</a>

content_tag(name, content, ...)

此 Helper 可以產生具有階層的 html ,並可加上所需的屬性。例如:

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

會輸出成:

<p class="strong">OOPS!</p>

套疊使用便可產出具有階層的 HTML :

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

將會輸出:

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

tag(name, ...)

此 Helper 可產出單一個 HTML Tag 。如使用 <%= tag("br") %> 可以得到一個 <br />

image_tag(src, ...)

此 Helper 可產出 Image Tag 。如使用 <%= image_tag("test.jpg") %> 會產出 <img src="test.jpg" />

javascript_tag(...)

此 Helper 可用於插入 Javascript 段落。如使用 <%= javascript_tag "alert('OOPS')" %> 則產出如下:

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

javascript_include_tag(*sources)

此 Helper 可產生載入 Javascript 所需的 tag 。如:

<%= javascript_include_tag "main" %>

產出為:

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

stylesheet_link_tag(*sources)

此 Helper 可產生載入 CSS 所需的 Tag 。如:

<%= stylesheet_link_tag "main" %>

產出為:

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

Escape Helpers

處理頁面中需要 escape 的標籤與格式。

html_escape(string)

可將包含 HTML 的字串 escape 成一般文字,並可簡寫為 h

json_escape(string)

可將包含 JSON 的字串 escape 成一般文字,並可簡寫為 j

Lorem Ipsum Helpers

此類 Helper 能方便產生排版所需之各種假資料。

lorem_word, lorem_words

lorem_word 可自動生成「一個」假單字; lorem_words(argument) 則可依據傳入的參數生成指定數量的假單字。

lorem_sentence, lorem_sentences

lorem_sentence 可自動生成一句假句子; lorem_sentences(argument) 則可依據傳入的參數生成指定句數。

lorem_paragraph, lorem_paragraphs

lorem_paragraph 可自動生成一個文字段落;lorem_paragraphs(argument) 則可依據傳入的參數生成指定段落數。

lorem_date

可以生成假的日期,格式為 ddd mmm dd, yyyy 。亦可使用 lorem_date.to_date 取得 yyyy-mm-dd 的格式。
亦可傳入參數:

lorem_date("%Y/%m/%d", 2011..2013)

會回傳介於 2011 年和 2013 年間的假日期

lorem_name

會生成假的英文「全名」。

lorem_first_name

生成假的英文 "first name" 。

lorem_last_name

生成假的英文"last name"。

lorem_email

生成假的email。

lorem_image("WIDTHxHEIGHT")

利用 http://placehold.it/ 的服務產生假圖連結,通常會搭配 image_tag 使用。例如:

<%= image_tag(lorem_image("300x400")) %>

便會生成:

<img src="http://placehold.it/300x400" />

在頁面中會呈現一個 300x400 的假圖區塊。

也可以直接使用:

<img src="<%= lorem_image("300x400") %>" />

來達成一樣的效果。

中文假資料 Helper

針對需要中文假資料的使用者,Fire.app 也有下列中文相關的 helper 可供使用:

大致上用法與英文版本相同, Helper 名稱最後以 "_pinyin" 結尾者及 zh_lorem_email 都是用拼音取代中文顯示。

日文假資料 Helper

除了英文和中文外,也提供日文假資料 Helper 如下:

大致用法亦與英文版相同, Helper 名稱最後以 "_en" 結尾者及 jp_lorem_email 都是用拼音取代日文顯示。

自訂 Helper

如果你有自己的特殊需求,也可以自己定義helper來使用。只要在專案目錄下建立一個檔名為 view_helpers.rb 的檔案,內容格式為:

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

即可,例如我想製作一個產生假文 Menu 的 Helper ,就可以在 view_helpers.rb 裡面定義:

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

如此一來在樣板中使用 <%= lorem_menu(3) %> 就可以得到以下結果:

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