Helper

第二節

AJAX Helper

Cake的Ajax helper使用最流行的Prototype和script.aculo.us二大函式庫控制Ajax與客戶端特效。 所以，為了要使用這個helper，你必需從http://script.aculo.us下載最近的版本，放在/app/webroot/js/ 另外，想使用Ajax helper的view還必需把這些函式庫包含進去。

這helper裡大部分函式都需要一個特別的陣列參數，$options。 $options用來指定Ajax操作中使用的各種參數。以下說明可以指定的值：

AjaxHelper $options 參數

/* 一般選項 */

$options['url']         // 這個動作要呼叫的URL。

$options['frequency']   // remoteTimer()或observeField()呼叫的間隔秒數。

$options['update']      // 根據Ajax操作結果進行更新的元素的DOM ID。

$options['with']        // 和Ajax表單提交時一併傳送和serialize的表單
                        // 元素的DOM ID。

$options['type']        // 設定值是'asynchronous'(預設)和'synchronous'
                        // 其中之一。可選擇操作模式。

/* 回呼函式 : XMLHttpRequest執行過程中，特定時間點所執行的JS 程式碼。*/

$options['loading']     // 流覽器將遠端文件載入時執行的JS 程式碼。

$options['loaded']      // 流覽器將遠端文件載入完成時執行的JS 程式碼。

$options['interactive'] // 當使用者可以和遠端文件互動時執行的程式碼，
                        // 即使還沒完全載入。
　　　
$options['complete']    // XMLHttpRequest完成時執行的JS 程式碼。

$options['confirm']     // XMLHttpRquest動作開始前的確認對話框顯示的文字。

$options['condition']   // XMLHttpRequest初始化前需要符合的JS 條件。

$options['before']      // request初始前呼叫的JS程式碼。

$options['after']       // 在request初始化完成之後，文件載入之前執行的JS程式。

以下是讓Ajax在Cake中既快又容易的幾個helper的函式：

  • link
  • string $title
  • string $href
  • array $options
  • boolean $confirm
  • boolean $escapeTitle

建立一個取回位於$options['url']的連結，標題使用$title，完成時更新設定的DOM元素。 這函式可以使用所有的回呼函式。

  • remoteFunction
  • array $options

這函式產生執行遠端呼叫所需的JavaScript。 主要當成linkToRemote的helper。 除非需要產生一些特別的script，否則很少用到。

  • remoteTimer
  • array $options

定期呼叫$options['url']指定的動作，時間間隔由$options['frequency']定義，單位為秒，預設為10秒。 通常使用於用遠端呼叫的結果更新特定的div(由$options['update']指定)。 這函式可以使用所有回呼函式。

  • form
  • string $action
  • string $type
  • array $options

傳回可以提交至$action的表單標籤， 透過XMLHttpRequest在背景執行可以免除傳統POST需要重新載入的問題。 這樣子傳回的表單資料和一般的方法都一樣(在controller中用$this->params['form']取用)。 接者根據操作結果進行更新$options['update']指定的DOM 元素。 這函式可以使用所有的回呼函式。

  • observeField
  • string $field_id
  • array $options

每$options['frequency']秒檢查一次由$field_id指定的DOM ID代表的欄位， 一旦發現內容有變化，馬上呼叫$options['url']裡的action。 可以更新$options['update']指定的DOM 元素，或由$options['with']指定一個表單元素。 這函式可以使用所有的回呼函式。

  • observeForm
  • string $form_id
  • array $options

和observeField()用途相同，只是它監視的是表單裡所有的元素。

  • autoComplete
  • string $field
  • string $url
  • array $options

產生ID為$field的文字欄文，內具自動完成功能。 $url所指的action應該可以傳回自動完成的字串： 基本上，這action要把一堆由<ul></ul>包起來，未經排序的自動完成字串分開。 如果要讓有自動完成功能的欄位取得blog文章的標題，controller的action看起來會像這樣：

function autocomplete ()
{
    $this->set('posts',
        $this->Post->findAll(
            "subject LIKE '{$this->data['Post']['subject']}'")
        );
    $this->layout = "ajax";
}

然後autocomplete()呼叫的view看起來會像這樣：

<ul>
<?php foreach($posts as $post): ?>
<li><?php echo $post['Post']['subject']; ?></li>
<?php endforeach; ?>
</ul>

實際涵有這種欄位的view，程式碼會像這樣：

<form action="/users/index" method="POST">
    <?php echo $ajax->autoComplete('Post/subject', '/posts/autoComplete')?>
    <?php echo $html->submit('View Post')?>
</form>

autoComplete函式會將這個資訊輸入到文字欄位內，而action所提供的自動完成字串則會被顯示在某些div上。 也可以如下例一般設定這個view的風格：

<style type="text/css">

div.auto_complete {
    position         :absolute;
    width            :250px;
    background-color :white;
    border           :1px solid #888;
    margin           :0px;
    padding          :0px;
}

li.selected { background-color: #ffb; }

</style>
  • drag
  • string $id
  • array $options

讓$id指定的DOM物件可以被拖移。 這函式的$options多了一些額外的參數：

// (版本變號請查script.aculo.us)

$options['handle']     // (v1.0)元素內handle等於設定值的子元素才能被
                       // 拖移。這個值必需是元素的參考或id。

$options['handle']     // (V1.5) 功能和上面一樣，除了變成可以設成CCS class。
                       // 在元素內的子元素中，第一個屬於這個CCS class的，
                       // 會被當成handle。

$options['revert']     // (V1.0) 如果設成true，元素會被拖移結束後回到原位。

$options['revert']     // (V1.5) Revert變成也可以是拖移結束後呼叫的函式參考。

$options['constraint'] // 如果設成'horizontal'或'vertical'，拖移的方向會被限
                       // 制在水平方向或垂直方向。
  • drop
  • string $id
  • array $options

讓$id所指的DOM元素可以把被可拖移元素放置進去。同樣的，也有一些額外的參數，說明如下：

$options['accept']      // 設定成敍述CCS class的字串或內含字串的Javascript
                        // 陣列。只允許屬於這些CCS class的可拖移元素被放置
                        // 進去。

$options['containment'] // 可放置的元素只會接受放入在列表中的元素(或元素id)
                        // 這個設定值可以是一個元素或多個元素的JavaScript
                        // 陣列.

$options['overlap']     // 如果設成horizontal(水平)或vertical(垂直)，則只有在
                        // 設定方向上重疊一半以上時才會被放置進去。
  • dropRemote
  • string $id
  • array $options
  • array $ajaxOptions

建立可放置的元素，當有元素被放置在時立即產生XMLHttpRequest。 $options跟drop()的一樣。$ajaxOptions的定義和一般的$options沒二樣。

譯註：找了原始碼後發現，$ajaxOptions會被原封不動的傳入remoteFunction()中， 而remoteFunction的傳入值正是一般常見的$options。

sortable

  • string $id
  • array $options

讓一組浮動的物件(由$id指定DOM元素ID)可排列。 $options 陣列可以把排列方法設定如下：

$options['tag']         // 設定容器內的子元素中屬於這種標籤的才能被排列。
                        // 對UL和OL容器來說，值是LI。其他種子元素則必須指定，
                        // 預設是LI。

$options['only']        // 進一步限制只擇選屬於這個CCS class的子元素為可排列(如
                        // 果設定的是一個內含字串的陣列，則可指定指定多種CCS
                        // class)。

$options['overlap']     // 不是vertical(垂直,預設)就是horizontal(水平)。 對
                        // 浮動的或水平列表，選horizontal。重直列表選vertical。

$options['constraint']  // 把可拖移元素的移動方向限制在垂直(vertical)或水平
                        // (horizontal)方向上。.

$options['containment'] // 讓可排列的元素間可以拖放。設定值是元素或元素ID的陣列，
                        // 當然是指容器內的元素。

$options['handle']      // 用handle屬性建立打拖移元素，handle屬性請看drag()
                        // 的敍述。
 
  • editor
  • string $id
  • string $url
  • array $options

使用DOM id為$id的元素建立嵌入型編輯器。 這種編輯器不在編輯模式時時會變形成一排文字，滑鼠過去時會亮起來，按下去會進入編輯模式，隨即放大成一般編輯元素的編輯器。 第二個參數是當按下確定時，資料被傳送的URL。 嵌入型編輯器更詳細的資料可以在此找到 Script.aculo.us wiki.


附錄：讀者筆記