第三節
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時會把字串中的 '>' 以 '>' 取代， '<' 以 '<' 取代。
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，記得一併放進去。命名規則如下：
LinkHelper = class name
Link = key in helpers array
link.php = name of php file in
/app/views/helpers.
回饋
請考慮將您的程式回饋回Cake-可以透過我們的Trac系統或email和其中一位開發者連繫，
或者開一個新的CakeForge專案，把你的新helper分享給其他人。
沒有留言:
張貼留言