第二節
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。
嵌入型編輯器更詳細的資料可以在此找到
wiki.
沒有留言:
張貼留言