Helper

第三節

Javascript

JavaScript helper用於協助開發者透過關鍵的資訊，產生完整格式的JavaScript標籤和資料。

譯註：例如，只需提供edit.js檔名，即可使用link()完成 <script type="text/javascript" src="edit.js"></script> 完整的 HTML 字串。

  • codeBlock
  • string $string

將$string的字串包在JavaScript的<script>標籤內傳回。

  • link
  • string $url

把本機內的JavaScript連結進來使用。$url是JavaScript的檔名(含.js)

譯註：原始碼中是把$url接上一大堆路徑設定後，當成 <script ></script>的src屬性。

  • linkOut
  • string $url

和link()相同，只是這兒的標籤假設$url所參照的script不同在一個網域內。

譯註：原始碼中直接把$url字串當成 <script ></script>的src屬性。

  • escapeScript
  • string $script

把$script中的換行字元，單引號和雙引號脫逸掉。

  • event
  • string $object
  • string $event
  • string $observer
  • boolean $useCapture

在某個元素上附加事件。配合Prototype函式庫使用。

  • cacheEvents

將event()所建立的JavaScript暫存。

  • writeEvents

將cacheEvents()所暫存的事件寫入。

  • includeScript
  • string $script

將函式庫(例如Prototype函式庫)包含進來使用。 $script是指被包含進來的檔名(不含'.js')，如果是空字串，則表示將 WWW_ROOT/js/ 內所有的檔都包含進來使用。

譯註：include的意思其實就是把某個檔案內容原封不動貼上去。

Number

Number helper含有很多好用的函式可用於在view中加入格式化的字串。

  • precision
  • mixed $number
  • int $precision = 3

以$precision設定的精度將$number傳回。

  • toReadableSize
  • int $sizeInBytes

把$sizeInBytes所指的資料容量大小轉換成KB,MB,GB或TB這種人們可接受的單位傳回。

  • toPercentage
  • mixed $number
  • int $precision = 2

把精度為$presision的$number加上百分比符號後的字串傳回。

譯註：toPercentage(1.23456,2)就傳回'1.23%'。

Text

Text Helper協住關發者將完整格式的文字輸出的流覽器中。

  • highlight
  • string $text
  • string $phrase
  • string $highlighter = '<span class="highlight">\1</span>'

將$text中所出現的$phrase字串用$highlighter所提供的HTML標籤包起來。

  • stripLinks
  • string $text

將$text中所有的HTML連結(<a href= ...)去除後傳回。

  • autoLinkUrls
  • string $text
  • array $htmlOptions

在$text中找到類似http://或ftp://等字串後，加入(<a href=....)的標籤。

譯註：原文太簡化，這段文字是從原始碼中找到的，由於這函式內部會使用到HTML helper，$htmlOptions的說明可以參考HTML Help。

  • autoLinkEmails
  • string $text
  • array $htmlOptions

把$text字串加上email標籤(<a href="mailto:....)後傳回。

譯註：由於函式內部會使用到HTML helper，$htmlOptions的說明可以參考HTML Help。

  • autoLink
  • string $text
  • array $htmlOptions

把$text內所有URL和email連結轉成HTML標籤傳回。

譯註：由於函式內部會使用到HTML helper，$htmlOptions的說明可以參考HTML Help。

  • truncate
  • string $text
  • int $length
  • string $ending = '...'

將$text的前$length個字接上$ending字串(預設是'...')傳回。

  • excerpt
  • string $text
  • string $phrase
  • int $radius = 100
  • string $ending = '...'

從$text中節錄一小段文字傳回。 程式會在$text中找到$phrase字串，把前$radius到後$radius的字串接上$ending字串後傳回。

  • flay
  • string $text
  • boolean $allowHtml = false

將文字以flay格式轉成html，類似Textile或Redcloth，只是語法不同。

譯註：$allowHtml等於false時會把字串中的 '>' 以 '&gt;' 取代， '<' 以 '&lt;' 取代。

Time

Time Helper提供開發者一些函式把Unix的時間與日期字串轉換成看得懂的格式，顯示在流覽器中。

所有函式的$dateString字串，可PHP函式取得，也可由Unix函式取得。

  • fromString
  • string $dateString

將$dateString轉成UNIX時間。傳入的字串可以是UNIX的格式或標準strtotime()傳回的字串。

  • nice
  • string $dateString
  • boolean $return = false

傳回格式很親合的字串。 日期格式為"D, M js Y, H:i"，例如 'Mon, Jan 1st 2005, 12:00'。

  • niceShort
  • string $dateString
  • boolean $return = false

傳回的字串格式和nice()一樣，但如果日期是今天，則顯示"Tody, 12:00"，若是明天，則顯示"Yesterday, 12:00"。

  • isToday
  • string $dateString

傳回$dateString是否就是今天。

  • daysAsSql
  • string $begin
  • string $end
  • string $fieldName
  • boolean $return = false

傳回用來查詢二個時間點間的資料的SQL字串。

  • dayAsSql
  • string $dateString
  • string $fieldName
  • boolean $return = false

傳回可查詢與$dateString同一天的資料的SQL字串。

  • isThisYear
  • string $dateString
  • boolean $return = false

傳回$dateString是否是今年。

  • wasYesterday
  • string $dateString
  • boolean $return = false

傳回$dateString是否是昨天。

  • isTomorrow
  • string $dateString
  • boolean $return = false

傳回$dateString是否是明天。

  • toUnix
  • string $dateString
  • boolean $return = false

把$dateString字串轉成UNIX的時間。這函式只是把PHP的strtotime()封裝起來而以。

與fromString不同點在於toUnix只能傳入字串，fromString還可以傳入UNIX時間。

  • toAtom
  • string $dateString
  • boolean $return = false

將日期轉為Atom RSS feeds的時間格式。

  • toRSS
  • string $dateString
  • boolean $return = false

將日期轉為 RSS feeds的時間格式。

  • timeAgoInWords
  • string $dateString
  • string $format = 'j/n/y'
  • string $backwards = false
  • string $return = false
  • boolean $return = false

傳回目前時間與$dateString相差的時間或格式化的日期。 $datetime格式必需是像MySQL datetime這種strtotime()看得懂的格式。

譯註：如果相差時間大於一個月，會用"on 2/18/2006"的格式傳回，小於一個月則用"3 weeks, 4 days ago"這種格式傳回。

  • relativeTime
  • string $dateString
  • boolean $return = false

功能和timeAgoInWords()一樣，只是只能使用預設參數。請看timeAgoInWords()說明

  • wasWithinLast
  • string $timeInterval
  • string $dateString
  • boolean $return = false

如果$dateString在$timeInterval的時間內，傳回true，否則傳回false。 $timeInterval要有單位，如'6 hours', '2 days'

第四節

設計自己的Helper

有需要協助產生view程式嗎？如果發現有一小部分的view邏輯不斷的重覆出現，可以設計一個自己的Helper處理這件事。

繼承Helper類別

假設我們要設計一個輸出某種CCS風格的helper。 為了把邏輯裝進Cake既存的Helper結構，你必須建立一個新類別，放在/app/views/helpers目錄裡。 就把我們的Helper叫LinkHelper，實際的php類別看起來像這樣：

/app/views/helpers/link.php

class LinkHelper extends Helper
{
    function makeEdit($title, $url)
    {
        // 建立特殊格式連結的邏輯放這兒...
    }
}

Cake的helper類別內有一些函式可以讓你使用：

  • output
  • string $string
  • boolean $return = false

這函式可以把任何資料傳回view。 AUTO_OUTPUT(請看/app/config/core.php)和$return二個參數決定了傳回資料是要直接輸出到畫面， 還是單純回傳。

  • loadConfig

傳回應用程式目前的核心設定和標籤定義。

讓我們用output()建立標題連結和URL，並將它傳回view。

/app/views/helpers/link.php (加入邏輯)

class LinkHelper extends Helper
{
    function makeEdit($title, $url)
    {
        // 使用helper的output()函式把格式化的資料傳回view
        return $this->output("<div class=\"editOuter\"><a href=\"$url\" class=\"edit\">$title</a></div>");
    }
}

呼叫其他的Helper

你可能想用其他既存helper的功能。這時，只要在$helpers　陣列指定需要使用的helper就行了， 使用方法和在controller裡一模一樣。

/app/views/helpers/link.php (使用別的helper)

class LinkHelper extends Helper
{

    var $helpers = array('Html');

    function makeEdit($title, $url)
    {
        // 使用HTML helper輸出格式化資料：
        $link = $this->Html->link($title, $url, array('class' => 'edit'));

        return $this->output("<div class=\"editOuter\">$link</div>");
    }
}

使用自己的Helper

一旦你的helper設計好，並放在/app/views/helpers/目錄後，就可以在controller的$helpers陣列中指定使用了。

class ThingsController
{
    var $helpers = array('Html', 'Link');
}

如果還要使用HTML helper，記得一併放進去。命名規則如下：

  1. LinkHelper = class name

  2. Link = key in helpers array

  3. link.php = name of php file in /app/views/helpers.

回饋

請考慮將您的程式回饋回Cake-可以透過我們的Trac系統或email和其中一位開發者連繫， 或者開一個新的CakeForge專案，把你的新helper分享給其他人。


附錄：讀者筆記