/*** 
 
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 
 
****/  
  
這篇文檔要給出一個徹底全面的教程，關(guān)于如何 在Yii 中使用 JS。并不是要講如何用JS編程， 而是如何用 Yii 的方式。。。  
  
第一部分介紹幾個例子關(guān)于Yii中隱藏JS 的。  
第二部分介紹如何寫自定義的JS。  
  
1， 官方JS wrappers  
  
即使開發(fā)者沒有明確要求使用JS ， Yii 也經(jīng)常會這么干。  
Yii選擇 JQuery 作為JS 庫， 隨著不同Yii版本的發(fā)行， 相應會發(fā)行 比較新的JQuery 庫。  
不建議 大伙自行加載 其它的 JQuery 庫， 很有可能會導致沖突。   
  
  
  
1.1 表單驗證 Form validation  
  
這種情況下， JS 幾乎完全是隱藏的。（盡管從Yii 1.1.11 版本之后 JS 默認是禁用的）  
  
有2種 驗證使用了JS：   
  
client-side validation,  
AJAX validation.  
  
1.2 CGridView   
  
默認的， 腳手架 gii 創(chuàng)建 包涵了 CGridView 的 admin 頁面 以及 包含 了 CListView 的 Index 頁面。  
奇怪的是， CGridView 和 CListView 默認使用 Ajax。   
如果你需要定制， 在API 中有幾個參數(shù)。   
  
默認地使用 AJAX 有 pros 和 cons 。跟默認行為 最主要的爭議是 用戶 actions 不會在 瀏覽器瀏覽歷史中出現(xiàn)： 如， 用戶無法 返回到之前的 search filter。  
如果這個弊病 讓你 想要在CGridView 中禁用 AJAX 的 話， 你可以在 初始化 CGridView widget 時 用'ajaxUpdate' => false.  
  
  
1.3 CJui* classes   
  
在Yii 中使用 JS 最簡單的辦法就是 使用 Yii classes。  
Jui 插件已經(jīng)被包含在 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 類 的基本例子 是不夠的。我們經(jīng)常還需要 自定義 JS 動作。  
  
拿 CJuiAutoComplete 來說， 我們需要 定制一個實例有以下2個特性：  
  
A， 自動完成的備選項 都是通過 AJAX 異步得到的,  
B， 被選中 的項目的 id 會被添加到 form 中。  
  
AJAX source 和 Yii html form 的動態(tài)更新  
  
CJuiAutoComplete 的配置 是一個 關(guān)聯(lián)數(shù)組。它的 “source” 主鍵 必須跟 AJAX 關(guān)聯(lián)， 意味著 它的 value 必須是 一個 JS function  
我們不可以簡單的這樣寫 “function()..” 因為這會被解釋執(zhí)行為 一個 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 傳遞的是一個數(shù)字 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>  
    &#39;options&#39; => array(  
        &#39;minLength&#39; => &#39;3&#39;, // min letters typed before we try to complete  
        &#39;select&#39; => "js:function(event, ui) {  
            jQuery(&#39;#MyModel_userId&#39;).val(ui.item.id);  
            return true;  
}",  
    ),  
);  
$this->widget(&#39;zii.widgets.jui.CJuiAutoComplete&#39;, $params);  
  
這段代碼 輸出了一個 保存有 被選擇的 user 的 ID 的 hidden form field。  
在select function 中， 通過 它的 html id ， 在 select fuction 中更新。  
當然， 這個 ID 是依存于 model 的名字的。經(jīng)常是  "ModuleName_AttributeName" 種形式 ，但是你應該檢查你的 HTML form  來確定一下。  
更靈活的代碼 應該用 CHtml::resolveNameID() 來算出這個ID。  
  
稍后將會說幾個 要點。  
A， 在 ajax 參數(shù)中， &rdquo;data&rdquo; 不應該是 像  "fulltext=1&term="+request.term 這樣的 string。  
B， 如果你需要 在 &rdquo;data&ldquo; 中混合 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(&#39;403&#39;, &#39;Forbidden access.&#39;);  
    }  
    if (empty($_GET[&#39;term&#39;])) {  
        throw new CHttpException(&#39;404&#39;, &#39;Missing "term" GET parameter.&#39;);  
    }  
    $term = $_GET[&#39;term&#39;];  
    $filters = empty($_GET[&#39;exclude&#39;]) ? null : (int) $_GET[&#39;exclude&#39;]);  
    header(&#39;Content-Type: application/json; charset="UTF-8"&#39;);  
    echo json_encode(User::completeTerm($term, $exclude));  
    Yii::app()->end();  
}  
  
重點的幾行 讀取 GET &rdquo;term&ldquo; 參數(shù)， 發(fā)送 JSON頭， 用JSON 加密結(jié)果。  
如果你的 編碼不是 utf-8 ， 你應該 用執(zhí)行效率稍慢的 Yii 靜態(tài)方法 CJson::encode() 而不是  json_encode()  
上面的方法中 靜態(tài)方法 User::completeTerm() 應該 返回一個 array(array("id"=>xx, "value"=>xx, "label"=>xx), array(...), array(...), ...)  
  
  
1.4 用 AJAX 和 CHtml 局部刷新  
  
在Yii 中有2 個靜態(tài)方法    
  
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(  
    &#39;Update profile&#39;,  
    array(&#39;profile/ajaxcontent&#39;, &#39;id&#39; => $id), // Yii URL  
    array(&#39;update&#39; => &#39;#my-profile&#39;) // jQuery selector  
);  
  
當然了，這種情況下， action "profile/ajaxcontent" 必須輸出 HTML, 盡管不是一個完整的 HTML 頁面。  
如果你更喜歡 返回一個 結(jié)構(gòu)化數(shù)據(jù) 并在 JS 中 解析它， 可以 用一個 "success" 替代  "update"， 如下：  
  
// the data received could look like: {"id":3, "msg":"No error found"}  
array(&#39;success&#39; => &#39;js:function(data) {   
            $("#newid").val(data.id);  
            $("#message").val(data.msg);   
}&#39;)  
  
輸出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發(fā)行。當PHP代碼需要的適合會自動加載。  
如果你想要確保它們正常加載， 可以用：   
  
// Load jQueryUI (and also jQuery which is required by jQueryUI)  
Yii::app()->clientScript->registerCoreScript(&#39;jquery.ui&#39;);  
  
默認地，  CClientScript::registerCoreScript() 會在頁面的底端加載。重復寫兩遍沒有影響。  
  
2.2 行內(nèi) JS（嵌入 HTML 的JS）  
  
Inline JS (embedded in the HTML page)   
  
一小段的 JS 可以寫在一個 PHP string 中。  
  
Yii::app()->clientScript->registerScript(&#39;uniqueid&#39;, &#39;alert("ok");&#39;);  
  
對于長的JS 代碼， 沒有了 語法高亮的支持確實很痛苦。但我們可以這樣：  
  
// raw JS file expanded into the page  
Yii::app()->clientScript->registerScript(&#39;uniqueid&#39;, file_get_contents(&#39;js/mycode.js&#39;));  
   
// JS file with embedded PHP code  
ob_start();  
include &#39;js/mycode.js&#39;;  
Yii::app()->clientScript->registerScript(&#39;uniqueid&#39;, ob_get_clean());  
  
  
2.3 引用外部的 JS   
  
當然了， 如果一個 JS 總是需要的話， 修改 layout template 是一種方法，  
但是當 JS 文件只有在某些 請求中 需要的話， 可以這樣：  
  
// Load a file with an aboslute and external URL  
Yii::app()->clientScript->registerScriptFile(&#39;http://example.com/a.js&#39;);  
   
// Load a file from "js/custom.js" under the root of the application  
Yii::app()->clientScript->registerScriptFile(Yii::app()->baseUrl . &#39;/js/custom.js&#39;);  
  
我們還可以用  CClientScript::POS_HEAD ,等參數(shù)來 決定 什么適合加載我們的 script  
我們也可以 用類似方法 加載 其他的 文件， 如CSS 等。  
  
  
2.4  通過 assets 加載 外部JS  
  
一些情況下， JS 代碼不在 一個 public 的目錄下。  
比如， 當你開發(fā)一個 extension 后， 所有的 文件都 在 "protected/extensions" 之下。  
這時候， 你必須首先 引導  Yii 將你的 JS 代碼 發(fā)布到 assets 目錄下。  
  
  
// Put the local directory into the application&#39;s assets  
$assetsUrl = Yii::app()->assetManager->publish(__DIR__ . &#39;/myassets&#39;);  
   
// Load a published file  
Yii::app()->clientScript->registerScriptFile($assetsUrl . &#39;/custom.js&#39;);  
  
更多詳細用法參考 CAssetManager::publish()  
  
  
  
2.5 用 inline代碼 還是 外部 文件？   
  
在加載 js 時， 通過 一個 JS 文件加載會更讓人青睞， 有很多原因， 最主要的是可讀性好。  
但是， 有些任務 不可以 純粹在 JS 中完成的。  
舉例來說：  
沒有 可移植的辦法 來通過 JS 來生成一個 Yii 的URL。 路徑 取決于 CUrlManager  的配置。  
  
一種解決辦法就是 把所有的 JS 代碼放入一個文件， 用 在 PHP 中定義的 JS變量 來完成。   
  
Yii::app()->clientScript->registerScriptFile(Yii::app()->baseUrl . &#39;/js/custom.js&#39;);  
$vars = array(  
    &#39;ajaxUrl&#39; => $this->createUrl(&#39;complete&#39;, &#39;id&#39; => $model->id,  
);  
Yii::app()->clientScript->registerScript(&#39;variables&#39;, &#39;var myApp = &#39; . CJavascript::encode($vars) . &#39;;&#39;);  
  
除了 CJavascript::encode(), 靜態(tài)的方法 CJavascript::quote() 也是有用的。  
  
$url = $this->createUrl(&#39;app/ajaxProcessor&#39;);  
$cs->registerScript(&#39;var1&#39;, "var myUrl = &#39;" . $url . "&#39;;"); // can break with some URLs  
$cs->registerScript(&#39;var1&#39;, "var myUrl = &#39;" . CJavascript::quote($url, true) . "&#39;;");  
  
  
3. 結(jié)束語  
  
盡管 你可以 在不關(guān)心 PHP框架的 情況下在一個 Yii 應用中 寫 JS， 但是有很多弊端。  
比如， JS 使用 的 URL 在首次配置改變時， 可能會出錯。  
或者 一些頁面會因為 Yii 的 JS 跟 開發(fā)者的 JS 庫 沖突 而崩潰掉。  
  
盡管你可以不用 Yii 提供的 wrappers ，你仍然應該使用 一下3個：  
  
CClientScript::registerCoreScript()  
CClientScript::registerScriptFile()  
CClientScript::registerScript()