Helper

第一節

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']))
         {

         ...

產生日期與時間選項的標籤列表如下：

  1. dayOptionTag ($tagName, $value=null, $selected=null, $optionAttr=null)

  2. yearOptionTag ($tagName, $value=null, $minYear=null, $maxYear=null, $selected=null, $optionAttr=null)

  3. monthOptionTag ($tagName, $value=null, $selected=null, $optionAttr=null)

  4. hourOptionTag ($tagName, $value=null, $format24Hours=false, $selected=null, $optionAttr=null)

  5. minuteOptionTag ($tagName, $value=null, $selected=null, $optionAttr=null)

  6. meridianOptionTag ($tagName, $value=null, $selected=null, $optionAttr=null)

  7. dateTimeOptionTag ($tagName, $dateFormat= 'DMY', $timeFormat= '12', $selected=null, $optionAttr=null)


附錄：讀者筆記

1.1.X版沒有tags.ini.php檔案？ 

蒼邪說：我的版本是1.1.15.5144，為什麼找不到tags.ini.php，搜尋過cake裡面所有檔案都沒有，還是改到哪去了呢？