Template Helpers (zh tw)

#Template Helpers

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

##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("[email protected]", "example mail address") %>

會輸出：

<a href="mailto:[email protected]">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("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

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

• 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可供使用：

• 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

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

日文假資料 Helper

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

• jp_lorem_word, jp_lorem_words
• jp_lorem_sentence, jp_lorem_sentences
• jp_lorem_paragraph, jp_lorem_paragraphs
• jp_lorem_name
• jp_lorem_name_en
• jp_lorem_first_name
• jp_lorem_first_name_en
• jp_lorem_last_name
• jp_lorem_last_name_en
• jp_lorem_email

大致用法亦與英文版相同， 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>