yii_wiki_394_javascript-and-ajax-with-yii （在yii 中使用 javascript 和ajax）

/***

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()