/***
http://www.yiiframework.com/wiki/394/javascript-and-ajax-with-yii
Javascript and AJAX with Yii
translated by php工程師
http://blog.csdn.net/phpgcs
1. Official JS wrappers
1.1 Form validation
1.2 CGridView
1.3 CJui* classes
1.4 Partial update with AJAX and CHtml
1.5 Extensions that wrap JS into PHP classes
2. Writing custom JS code
2.1 Requiring some JS libraries (jQuery and such)
2.2 Inline JS (embedded in the HTML page)
2.3 JS in an external file
2.5 Inline code or external file?
3. Final words
****/
這篇文檔要給出一個徹底全面的教程，關於如何 在Yii 中使用 JS。並不是要講如何用JS編程， 而是如何用 Yii 的方式。。。
第一部分介紹幾個例子關於Yii中隱藏JS 的。
第二部分介紹如何寫自定義的JS。
1， 官方JS wrappers
即使開發者沒有明確要求使用JS ， Yii 也經常會這麼干。
Yii選擇 JQuery 作為JS 庫， 隨著不同Yii版本的發行， 相應會發行 比較新的JQuery 庫。
不建議 大伙自行加載 其它的 JQuery 庫， 很有可能會導致沖突。
1.1 表單驗證 Form validation
這種情況下， JS 幾乎完全是隱藏的。（盡管從Yii 1.1.11 版本之後 JS 默認是禁用的）
有2種 驗證使用了JS：
client-side validation,
AJAX validation.
1.2 CGridView
默認的， 腳手架 gii 創建 包涵了 CGridView 的 admin 頁面 以及 包含 了 CListView 的 Index 頁面。
奇怪的是， CGridView 和 CListView 默認使用 Ajax。
如果你需要定制， 在API 中有幾個參數。
默認地使用 AJAX 有 pros 和 cons 。跟默認行為 最主要的爭議是 用戶 actions 不會在 浏覽器浏覽歷史中出現： 如， 用戶無法 返回到之前的 search filter。
如果這個弊病 讓你 想要在CGridView 中禁用 AJAX 的 話， 你可以在 初始化 CGridView widget 時 用'ajaxUpdate' => false.
1.3 CJui* classes
在Yii 中使用 JS 最簡單的辦法就是 使用 Yii classes。
Jui 插件已經被包含在 PHP 類中了。你可以參照 這些類的列表。每一個文檔頁面都 是從一個例子開始的。
CJuiWidget
zii.widgets.jui
CJuiAccordion CJuiAccordion displays an accordion widget.
CJuiAutoComplete CJuiAutoComplete displays an autocomplete field.
CJuiButton CJuiButton displays a button widget.
CJuiDatePicker CJuiDatePicker displays a datepicker.
CJuiDialog CJuiDialog displays a dialog widget.
CJuiDraggable CJuiDraggable displays a draggable widget.
CJuiDroppable CJuiDroppable displays a droppable widget.
CJuiInputWidget CJuiInputWidget is the base class for JUI widgets that can collect user input.
CJuiProgressBar CJuiProgressBar displays a progress bar widget.
CJuiResizable CJuiResizable displays a resizable widget.
CJuiSelectable CJuiSelectable displays an accordion widget.
CJuiSlider CJuiSlider displays a slider.
CJuiSliderInput CJuiSliderInput displays a slider. It can be used in forms and post its value.
CJuiSortable CJuiSortable makes selected elements sortable by dragging with the mouse.
CJuiTabs CJuiTabs displays a tabs widget.
在 Yii 的 web widgets 中 也有 幾個 JS 類， 特別是 CTreeView。
1.3.1 向一個 PHP class 傳遞 JS 代碼。 (以 CJuiAutoComplete 為例 )
在很多時候， 使用CJui 類 的基本例子 是不夠的。我們經常還需要 自定義 JS 動作。
拿 CJuiAutoComplete 來說， 我們需要 定制一個實例有以下2個特性：
A， 自動完成的備選項 都是通過 AJAX 異步得到的,
B， 被選中 的項目的 id 會被添加到 form 中。
AJAX source 和 Yii html form 的動態更新
CJuiAutoComplete 的配置 是一個 關聯數組。它的 “source” 主鍵 必須跟 AJAX 關聯， 意味著 它的 value 必須是 一個 JS function
我們不可以簡單的這樣寫 “function()..” 因為這會被解釋執行為 一個 string value ！
正確的語法是： "js:fucntion(request, response){...} "
這個 “js：“前綴 告訴 yii 後面的 都是純 JS 代碼，應該跳過。
更新 form 的原則跟這個 是一樣的 ：
from within PHP, we pass a JS function that will read the item chosen.
在這裡 ， 語法是： 'select' => "js:function(…".
1.3.2 完整的例子：The complete example
界面上只顯示 項目的 names 但是 form 傳遞的是一個數字 ID。
echo $form->hiddenField($model, 'userId');
$quotedUrl = CJavascript::encode($this->createUrl(array('user/complete')));
$params = array(
'name' => "userComplete",
'source' => 'js:function(request, response) {
$.ajax({
url: "'. $quotedUrl . '",
data: { "term": request.term, "fulltext": 1 },
success: function(data) { response(data); }
});
}',
// additional javascript options for the autocomplete plugin
// See <http://jqueryui.com/demos/autocomplete/#options>
'options' => array(
'minLength' => '3', // min letters typed before we try to complete
'select' => "js:function(event, ui) {
jQuery('#MyModel_userId').val(ui.item.id);
return true;
}",
),
);
$this->widget('zii.widgets.jui.CJuiAutoComplete', $params);
這段代碼 輸出了一個 保存有 被選擇的 user 的 ID 的 hidden form field。
在select function 中， 通過 它的 html id ， 在 select fuction 中更新。
當然， 這個 ID 是依存於 model 的名字的。經常是 "ModuleName_AttributeName" 種形式 ，但是你應該檢查你的 HTML form 來確定一下。
更靈活的代碼 應該用 CHtml::resolveNameID() 來算出這個ID。
稍後將會說幾個 要點。
A， 在 ajax 參數中， ”data” 不應該是 像 "fulltext=1&term="+request.term 這樣的 string。
B， 如果你需要 在 ”data“ 中混合 PHP 值 ，使用 CJavaScript::encode().
C, AJAX call 的 url 是在 PHP 中組建的， 因為這是唯一的可移植的方案。
/**
* Propose completions for a term (AJAX).
*/
public function actionAjaxComplete()
{
if (!YII_DEBUG && !Yii::app()->request->isAjaxRequest) {
throw new CHttpException('403', 'Forbidden access.');
}
if (empty($_GET['term'])) {
throw new CHttpException('404', 'Missing "term" GET parameter.');
}
$term = $_GET['term'];
$filters = empty($_GET['exclude']) ? null : (int) $_GET['exclude']);
header('Content-Type: application/json; charset="UTF-8"');
echo json_encode(User::completeTerm($term, $exclude));
Yii::app()->end();
}
重點的幾行 讀取 GET ”term“ 參數， 發送 JSON頭， 用JSON 加密結果。
如果你的 編碼不是 utf-8 ， 你應該 用執行效率稍慢的 Yii 靜態方法 CJson::encode() 而不是 json_encode()
上面的方法中 靜態方法 User::completeTerm() 應該 返回一個 array(array("id"=>xx, "value"=>xx, "label"=>xx), array(...), array(...), ...)
1.4 用 AJAX 和 CHtml 局部刷新
在Yii 中有2 個靜態方法
CHtml::ajaxLink()
CHtml::ajaxbutton()
The following code will replace the content of the HTML element of ID "my-profile" with the output of a call to the action "ajaxcontent" of the controller "profile".
echo CHtml::ajaxLink(
'Update profile',
array('profile/ajaxcontent', 'id' => $id), // Yii URL
array('update' => '#my-profile') // jQuery selector
);
當然了，這種情況下， action "profile/ajaxcontent" 必須輸出 HTML, 盡管不是一個完整的 HTML 頁面。
如果你更喜歡 返回一個 結構化數據 並在 JS 中 解析它， 可以 用一個 "success" 替代 "update"， 如下：
// the data received could look like: {"id":3, "msg":"No error found"}
array('success' => 'js:function(data) {
$("#newid").val(data.id);
$("#message").val(data.msg);
}')
輸出JSON 最簡便的方法就是 用 CJson::encode() 。
1.5 Extensions that wrap JS into PHP classes
除了官方的Yii 類， 許多 extension 都提供 JS 特性。
一些 extensions 僅僅是一些 wrappers ， 試圖讓 yii 跟 某些 JS 插件的整合更方便。
如果你正在著一些特殊的特性， 請參照 JS extensions 列表 。
/****
2. Writing custom JS code
translated by php工程師
http://blog.csdn.net/phpgcs
****/
在寫你自定義的 代碼之前， 別忘了 檢查下 是否有適合你需求的 PHP wrappers 如，
JUI Widgets
Web Widgets
JS extensions
2.1 加載 JS 庫。
Requiring some JS libraries (jQuery and such)
一些 JS 庫隨著Yii發行。當PHP代碼需要的適合會自動加載。
如果你想要確保它們正常加載， 可以用：
// Load jQueryUI (and also jQuery which is required by jQueryUI)
Yii::app()->clientScript->registerCoreScript('jquery.ui');
默認地， CClientScript::registerCoreScript() 會在頁面的底端加載。重復寫兩遍沒有影響。
2.2 行內 JS（嵌入 HTML 的JS）
Inline JS (embedded in the HTML page)
一小段的 JS 可以寫在一個 PHP string 中。
Yii::app()->clientScript->registerScript('uniqueid', 'alert("ok");');
對於長的JS 代碼， 沒有了 語法高亮的支持確實很痛苦。但我們可以這樣：
// raw JS file expanded into the page
Yii::app()->clientScript->registerScript('uniqueid', file_get_contents('js/mycode.js'));
// JS file with embedded PHP code
ob_start();
include 'js/mycode.js';
Yii::app()->clientScript->registerScript('uniqueid', ob_get_clean());
2.3 引用外部的 JS
當然了， 如果一個 JS 總是需要的話， 修改 layout template 是一種方法，
但是當 JS 文件只有在某些 請求中 需要的話， 可以這樣：
// Load a file with an aboslute and external URL
Yii::app()->clientScript->registerScriptFile('http://example.com/a.js');
// Load a file from "js/custom.js" under the root of the application
Yii::app()->clientScript->registerScriptFile(Yii::app()->baseUrl . '/js/custom.js');
我們還可以用 CClientScript::POS_HEAD ,等參數來 決定 什麼適合加載我們的 script
我們也可以 用類似方法 加載 其他的 文件， 如CSS 等。
2.4 通過 assets 加載 外部JS
一些情況下， JS 代碼不在 一個 public 的目錄下。
比如， 當你開發一個 extension 後， 所有的 文件都 在 "protected/extensions" 之下。
這時候， 你必須首先 引導 Yii 將你的 JS 代碼 發布到 assets 目錄下。
// Put the local directory into the application's assets
$assetsUrl = Yii::app()->assetManager->publish(__DIR__ . '/myassets');
// Load a published file
Yii::app()->clientScript->registerScriptFile($assetsUrl . '/custom.js');
更多詳細用法參考 CAssetManager::publish()
2.5 用 inline代碼 還是 外部 文件？
在加載 js 時， 通過 一個 JS 文件加載會更讓人青睐， 有很多原因， 最主要的是可讀性好。
但是， 有些任務 不可以 純粹在 JS 中完成的。
舉例來說：
沒有 可移植的辦法 來通過 JS 來生成一個 Yii 的URL。 路徑 取決於 CUrlManager 的配置。
一種解決辦法就是 把所有的 JS 代碼放入一個文件， 用 在 PHP 中定義的 JS變量 來完成。
Yii::app()->clientScript->registerScriptFile(Yii::app()->baseUrl . '/js/custom.js');
$vars = array(
'ajaxUrl' => $this->createUrl('complete', 'id' => $model->id,
);
Yii::app()->clientScript->registerScript('variables', 'var myApp = ' . CJavascript::encode($vars) . ';');
除了 CJavascript::encode(), 靜態的方法 CJavascript::quote() 也是有用的。
$url = $this->createUrl('app/ajaxProcessor');
$cs->registerScript('var1', "var myUrl = '" . $url . "';"); // can break with some URLs
$cs->registerScript('var1', "var myUrl = '" . CJavascript::quote($url, true) . "';");
3. 結束語
盡管 你可以 在不關心 PHP框架的 情況下在一個 Yii 應用中 寫 JS， 但是有很多弊端。
比如， JS 使用 的 URL 在首次配置改變時， 可能會出錯。
或者 一些頁面會因為 Yii 的 JS 跟 開發者的 JS 庫 沖突 而崩潰掉。
盡管你可以不用 Yii 提供的 wrappers ，你仍然應該使用 一下3個：
CClientScript::registerCoreScript()
CClientScript::registerScriptFile()
CClientScript::registerScript()
