第一節
HTML Helper
Helper主要功用在提供view常常使用的一些排列和顯示資料功能。首先介紹HTML Helper。
引言
HTML helper是Cake讓建構網站的過程變得比較不單調又比較快速的方法之一。
HTML helper有二個主要目標：幫忙加入常用的HTML程式碼，和幫助快速又輕易地建立web表單。
接下來幾節會帶你看幾個helper裡最重要的函式，
但記得最新的版本都放在http://api.cakephp.org。
HTML helper裡很多功能都用到HTML標籤定義檔，tags.ini.php。
Cake的核心設定裡含有tags.ini.php。
但如果想做一些變更，可以把/cake/config/tags.ini.php當複製到/app/config/目錄裡修改。
HTML helper依新的定義檔為你的request產生標籤。
用HTML helper建立一些view的程式碼相當有用，一旦改變tags.ini.php檔，則整個網站跟者都會一起變。
另外，如果在應用程式的核心設定檔(/app/config/core.php)內將AUTO_OUTPUT設成true，
helper會自動輸出標籤而不是只把值傳回。
這個設計滿足了那些不喜歡在view程式碼中放短標籤(<?= ?>)和一堆echo()的人。
後面只要看到含有$return參數的函式，都允許動態變更這個設定(AUTO_OUTPUT=true的設定)。
如果你暫時不想理會AUTO_OUTPUT的設定，想傳回程式碼，把$return設成true就行了。
HTML Helper函式還包含了$htmlAttributes參數，可以處理標籤裡額外的參數。
例如，想幫某個標籤加上'class'屬性，可以把它傳到$htmlAttributes參數：
array('class'=>'someClass')插入元素(element)
如果你要用Cake插入HTML裡時常重覆出現的元素，可以使用HTML helper，它對此十分拿手。
HTML helper裡有一堆函式分別負責插入媒體，建立表格，甚至還有使用PHP陣列建立沒排序列表的guiListTree。
- charset
- string $charset
- boolean $return
用來產生字集的META標籤。
- css
- string $path
- string $rel =
'stylesheet' - array $htmlAttributes
- boolean $return =
false
建立與CCS風格表的連結。$rel參數讓你提供為標籤提供rel=的值。
- image
- string $path
- array $htmlAttributes
- boolean $return =
false
輸出影像標籤。這個函式的傳回值可以直接傳入link()函式，自動建立含連結的影像。
- link
- string $title
- string $url
- array $htmlAttributes
- string $confirmMessage =
false - boolean $escapeTitle =
true - boolean $return =
false
使用這個函式在view裡建立一個連結。
需要使用JavaScript在按下連結時跳出確認視窗要求使用者確認時可以使用$confirmMessage。
例如，要刪除物件的連結，在執行前需要跳出像"Are you sure?"這樣的訊息讓使用者再確認。
$escapeTitle則用來決定是否跳脫$title內容的控制字元，若為true，則HTML，十六進位字或javascript等會被當作一般字串處理。
設成false則會以該有的處理動作處理，例如JavaScript就會看到執行結果。
- tableHeaders
- array $names
- array $tr_options
- array $th_options
建立一個格式化的表格標頭。
- tableCells
- array $data
- array $odd_tr_options
- array $even_tr_options
建立一個格式化的表格格子。
- guiListTree
- array $data
- array $htmlAttributes
- string $bodyKey =
'body' - string $childrenKey =
'children' - boolean $return =
false
由陣列內容產生巢狀無排序的樹狀列表。
表單和檢驗資料
當HTML helper幫你在view中快速建立表單的時候，它會顯得特別閃耀。
它負責產生所有的表單標籤，在發生錯誤時自動填回值，然後吐出錯誤訊息。
為了輔助說明，讓我們舉個簡明的範例。
想像一下你的應用程式需要一個Note model，而你想要建立controller邏輯，與新增和編輯Note物件的view。
在NotesController中，應該會有個edit action看起來像這樣：
編輯NotesController裡的Action
function edit($id)
{
//首先檢查一下是否有任何表單資料被提交到action內
if (!empty($this->data['Note']))
{
//這是我們嘗試檢查資料與儲存資料的地方(參考資料檢驗一章)
if ($this->Note->save($this->data['Note']))
{
//如果儲存成功，就把使用者帶到適當的地方。
$this->flash('Your information has been saved.', '/notes/edit/' . $id);
exit();
}
else
{
//為適當的欄位產生錯誤訊息，其實這個動作在這兒已經不需要了，
//因為資料已經被儲存進去，如果想先檢驗資料再存，可以呼叫
//$this->Note->validates($this->data['Note']); 進行檢驗動作。
//使用下面的方法呼叫tagErrorMsg()
$this->validateErrors($this->Note);
//然後畫出view程式碼
$this->render();
}
}
// 如果沒有收到任何表單資料，取出一條要編輯的便條，
// 把它的資訊交給view。
$this->set('note', $this->Note->find("id = $id"));
$this->render();
}將controller安排好之後，接者看看view程式碼(可以在app/views/notes/edit.thtml找到它)
我們的Note model十分單純，只有id，提交者的id和內容。
view則負責顯示內容與讓使用者輸入新資料，然後把資料存回model。
所有的view預設都可以使用HTML helper，存取的變數名叫$html.。
下面的範例，注意看一下如何處理錯誤的資料：
編輯view程式範例 (edit.thtml)
<!-- 建立表單標籤 -->
<?php echo $html->formTag('/notes/edit/' . $html->tagValue('Note/id')?>
<table cellpadding="10" cellspacing="0">
<tr>
<td align="right">Body: </td>
<td>
<!-- 這兒就是我們用HTML helper輸出文字區域標籤和錯誤訊息的地方，
controller會把我們想要編輯的資料放在$note變數內-->
<?php echo
$html->textarea('Note/body', array('cols'=>'60', 'rows'=>'10'));
?>
<?php echo $html->tagErrorMsg('Note/body',
'Please enter in a body for this note.') ?>
</td>
</tr>
<tr>
<td></td>
<td>
<!-- 我們還可以用HTML helper在表格中放入隱藏標籤。-->
<?php echo $html->hidden('Note/id')?>
<?php echo
$html->hidden('note/submitter_id',
$this->controller->Session->read('User.id'))?>
</td>
</tr>
</table>
<!-- 最後是一個提交的按鈕 -->
<?php echo $html->submit()?>
</form>
大部分產生表格標籤的函式都需要你提供欄位名稱$fildName，連tagErrorMsg也不例外。
Cake需要由$fieldName得知傳過來的是什麼資料，才可以正確的儲存和檢驗資料。
傳到$fieldName參數的字串格式長得像這樣"modelname/fieldName"。
如果你想要再為便條加上個標題，則可以在view裡加入這樣的程式：
<?php echo $html->input('Note/title') ?>
<?php echo $html->tagErrorMsg('Note/title', 'Please supply a title for this note.')?>tagErrorMsg()顯示的訊息會被包在<div
class="error_message"></div>裡以便使用CCS調整風格。
這兒列出一些HTML helper裡可以產生表格標籤的函式(大部分都很真觀，不太需要多加解釋):
- submit
- string $buttonCaption
- array $htmlAttributes
- boolean $return =
false
- password
- string $fieldName
- array $htmlAttributes
- boolean $return =
false
- textarea
- string $fieldName
- array $htmlAttributes
- boolean $return =
false
- checkbox
- string $fieldName
- array $htmlAttributes
- boolean $return =
false
- file
- string $fieldName
- array $htmlAttributes
- boolean $return =
false
- hidden
- string $fieldName
- array $htmlAttributes
- boolean $return =
false
- input
- string $fieldName
- array $htmlAttributes
- boolean $return =
false
- radio
- string $fieldName
- array $options
- array $inbetween
- array $htmlAttributes
- boolean $return =
false
- tagErrorMsg
- string $fieldName
- string $message
HTML helper還提供了一組函式幫忙建立日期類選項的標籤。
$tagName參數的處理方式與$fieldName一樣。
只要提供日期選項標籤相關的欄位名稱就行了。
資料經處理後，就會在controller裡以欄位名加上日期部分名稱呈現出來。
這樣說的確有點模糊，讓我們直接舉個例子：現在，Note裡多了一個deadline欄位，它的資料型態是時間。
然後，我的dayOptionTag裡$tagName參數被設成'note/deadline'。
在表格提交之後，'日'的資料會被以下面的型式傳到controller裡：
$this->data['Note']['deadline_day']同樣的想法，也可以用來取時間資料。下面的範例是把上頭的程式應用在存時間資料之前，
先把時間的各部分組合起來放在$data陣列中，再把資料存回model去。
在儲存前把時間資料連起來(NotesController的部分程式)
function edit($id)
{
//首先檢查一下有沒有任何表單資料提交到action裡。
if (!empty($this->data['Note']))
{
//把時間資料串連起來...
$this->data['Note']['deadline'] =
$this->data['Note']['deadline_year'] . "-" .
$this->data['Note']['deadline_month'] . "-" .
$this->data['Note']['deadline_day'];
//這裡我們試者檢驗和儲存資料
if ($this->Note->save($this->data['Note']))
{
...
產生日期與時間選項的標籤列表如下：
dayOptionTag ($tagName, $value=null, $selected=null,
$optionAttr=null)
yearOptionTag ($tagName, $value=null, $minYear=null,
$maxYear=null, $selected=null, $optionAttr=null)
monthOptionTag ($tagName, $value=null, $selected=null,
$optionAttr=null)
hourOptionTag ($tagName, $value=null, $format24Hours=false,
$selected=null, $optionAttr=null)
minuteOptionTag ($tagName, $value=null, $selected=null,
$optionAttr=null)
meridianOptionTag ($tagName, $value=null, $selected=null,
$optionAttr=null)
dateTimeOptionTag ($tagName, $dateFormat= 'DMY',
$timeFormat= '12', $selected=null, $optionAttr=null)
沒有留言:
張貼留言