xajax中文手册

* 什么是xajax?
* xajax如何工作 ?
* 为什么我要使用xajax代替其他PHP 的Ajax 库?
* 如何在我的PHP脚本之中使用xajax?
* 如何更新内容?
* 如何处理表单数据?
* 如何给xajax增加定制功能?
* 如何创建Loading...信息?
* 如何改变xajax的编码设置?
* 我能在私有或者收费产品之中使用xajax吗?

什么是xajax?
　　xajax是一个开源 的 PHP 类库 它能够让你黏合HTML 、CSS 、Javascrīpt和PHP，轻而易举的开发功能强大、基于WEB的AJAX应用软件. 使用xajax开发的应用软件，无需重新调入页面，就能够异步调用服务器端的PHP函数和更新内容.

xajax 如何工作?
　　你的应用软件需要异步调用的PHP函数， xajax的PHP对象都生成了对应的封装好了的Javascrīpt函数. 当被调用时，封装的函数使用Javascrīpt的XMLHttpRequest对象与服务器异步通讯，调用xajax对象对应的PHP函数. 调用结束后, PHP函数由xajax返回一个xajax的XML 响应传递给应用程序. XML响应包含了特定的指令和数据，他们可以被xajax的Javascrīpt消息分析器解析，并且被用于更新你的应用程序的内容.

为什么我要使用xajax代替其他PHP的ajax库?
　　你应该选择一个最适合你的项目需要的库。
　　xajax 提供了以下的功能, 它们使得ajax富有特色而又功能强大:

　　* xajax特殊的 XML 响应 / javascrīpt 消息分析系统 帮助你做到, 自动的处理函数返回的数据，按照PHP函数返回的指令更新内容或者状态. 因为xajax作了这些工作, 你不需要写javascrīpt的回调处理函数.

　　* xajax反对将代码 和数据紧密地杂糅在一起的主张, 并且保持xajax的代码从与他代码分离. 因为它是对象 构造的, 你可以加上自己定制的功能给xajax去扩展xajaxResponse 类和使用addscrīpt方法.

　　* xajax 可以工作在 Firefox, Mozilla, 大部分基于 Mozilla 的浏览器, Internet Explorer, 和 Safari.

　　* 除了更新元素的值和内含的HTML内容(innerHTML), xajax 还能用于更新样式(styles), css 类, 多选和单选按钮选择,甚至可以更新任何元素的属性.

　　* xajax 支持使用一维或者多维数组、关联数组(哈希数组) 作为xajax函数的参数从javascrīpt传送给PHP. 反之Additionally, 如果你传送一个javascrīpt的对象给xajax函数，PHP函数将接受一个描叙对象属性的关联数组(哈希数组).

　　* xajax 提供了一种简单的异步表单处理方式. 使用 xajax.getFormValues() javascrīpt 方法, 你可以轻而易举的在表单之中提交一个描绘值的数组作为参数传送到xajax异步处理函数:

Javascrīpt:

1. xajax_processForm( xajax.getFormValues ( 'formId' ) ;

　　它可以处理复杂的input 元素名称 ，例如 "checkbox[][]" 或者 "name[first]" 产生的多维或者关联数组(哈希数组), 就是普通提交表单那样使用PHP的$_GET数组

　　* 使用xajax你可以动态的发送附加的javascrīpt作为请求的响应到你的应用软件中运行，而这就和动态的更新元素的属性一样方便.

　　* xajax会自动比较PHP函数返回的数据与你已经标记需要修改的元素属性. 只有当新的数据确实可以改变现有的属性，属性才会真的被更新. 这将可消除程序在一定时间间隔内更新与当前内容相同或者不同的内容而出现的明显的闪烁.

　　* 每一个通过xajax简单注册的函数都可以有不同的请求方式. 所有的函数默认使用POST方式，除非你明确的指定使用GET方式. 如果使用GET请求，你必须非常明确的考虑它确实是你所需要的

　　* 如果没有指定URI，xajax将设法自动确定脚本的URI. xajax的自动确定算法经过了充分的验证，确保在大部分HTTPS或者未知端口的HTTP服务器上也可以正常的工作.

　　* xajax使用UTF8编码所有的请求和响应，以确保支持绝大部分的字符和语言. xajax已经成功测试了多种不同的UNICODE字符，包括Spanish, Russian, Arabic, and Hebrew

　　* 几乎所有xajax生成的javascrīpt都可以通过动态的外部javascrīpt包含到你的web程序之中. 当你在浏览器之中查看程序的源代码时，不会有Javascrīpt的函数定义混杂在HTML标记之中.

　　* xajax可以使用在Smarty模板系统之中，仅仅需要创建一个smarty变量就可以包含xajax的javascrīpt:

PHP:

1. $smarty ->assign ( 'xajax_javascrīpt' , $xajax ->getJavascrīpt ( ) ) ;

　　　然后你可以使用在header模版之中使用

SMARTY:

1. [ $xajax_javascrīpt]

　　　从而把xajax应用到你的站点.

如何在我的PHP脚本之中使用xajax?
　　xajax的设计是如此的富有特色，以至于不管是已有的web程序还是新的项目，它都能够被极其简单的部署和应用. 仅仅需要七步，你就可以在几乎任何PHP脚本之中加入xajax的强大功能:

1. 包含xajax类库:

 

PHP:

1. require_once ( "xajax.inc.php" ) ;

2. 实例化xajax 对象:

 

PHP:

1. $xajax = new xajax( ) ;

3. 注册你需要通过xajax调用的PHP函数的名称:

 

PHP:

1. $xajax ->registerFunction ( "myFunction" ) ;

4. 编写注册的PHP函数，并且在函数之中使用xajaxResponse 对象返回XML指令:

PHP:

1. function myFunction( $arg )
2. [
3. 　　// 对$arg做一些基本处理例如从数据库 检索数据
4. 　　// 然后把结果赋值给变量，例如$newContent
5.  
6. 　　// 实例化xajaxResponse 对象
7. 　　$objResponse = new xajaxResponse( ) ;
8.  
9. 　　// 添加指令到响应之中，用于指派
10. 　　// 指定元素(例如id="SomeElementId")的innerHTML属性的新的内容
11. 　　$objResponse ->addAssign ( "SomeElementId" ,"innerHTML" , $newContent ) ;
13. 　　//返回xajaxResponse 对象生成的XML响应
14. 　　return $objResponse ;
15. ]  

5. 在你的脚本输出任何信息之前，调用xajax用于接管请求:

PHP:

1. $xajax ->processRequests ( ) ;

6. 在页面的 标签之间, 告诉xajax生成所必需的Javascrīpt:

PHP:

1. <?php $xajax ->printJavascrīpt ( ) ; ?>

7. 在程序中，从Javascrīpt事件或者函数调用前面注册的函数:

HTML:

1. <div id ="SomeElementId" > </div>
2. 　　<button onclick ="xajax_myFunction(SomeArgument);" >

　　就这么简单. xajax 会处理其他所有的事情. 你所要做的主要工作就是编写PHP函数，然后从函数之中返回xajax的XML响应。而后者通过xajaxResponse类可以非常简单的生成.

如何更新内容?
　　xajax最富有特色的功能或许就是xajaxResponse类. 其他的Ajax库需要你自己编写Javascrīpt的回调句柄去处理一个异步请求返回的数据并更新内容. xajax, 从另外一个角度来说, 允许你使用PHP简单的控制内容. xajaxResponse 让你在PHP函数之中创建XML指令返回给你的程序. XML将被xajax的消息分析器解析，指令将告诉xajax如何更新程序的内容和状态. xajaxResponse类目前提供了以下指令:
* addConfirmCommands (integer $iCmdNumber, string $sMessage)
弹出一个显示内容为$sMessage的confirm确认提示框
如果点击确认框中的取消将跳过后面的$iCmdNumber条命令

PHP:

1. $objResponse ->addConfirmCommands ( 1 , "Do you want to preview the new data?" ) ;

* addAssign(string $sTarget, string $sAttribute, string $sData)
给ID为$sTargetId的元素的$sAttribute属性赋值$sData

PHP:

1. $objResponse ->addAssign ( "contentDiv" ,"innerHTML" ,"Some Text" ) ;
2.         $objResponse ->addAssign ( "checkBox1" ,"checked" ,"true" ) ;

* addAppend(string $sTarget, string $sAttribute, string $sData)
给ID为$sTargetId的元素的$sAttribute属性后面追加值$sData

PHP:

1. $objResponse ->addAppend ( "contentDiv" ,"innerHTML" ,"Some Text" ) ;

* addPrepend(string $sTarget, string $sAttribute, string $sData)
给ID为$sTargetId的元素的$sAttribute属性前面添加值$sData

PHP:

1. $objResponse ->addPrepend ( "contentDiv" ,"innerHTML" ,"Some Text" ) ;

* addReplace(string $sTarget, string $sAttribute, string $sSearch, string $sData)
替换命名为$sTargetId的元素的$sAttribute属性的值之中的$sSearch为$sData

PHP:

1. $objResponse ->addReplace ( "contentDiv" ,"innerHTML" ,"text" ,"<strong>text</strong>" ) ;

* addClear(string $sTarget, string $sAttribute)
清空命名为$sTargetId的元素的$sAttribute属性的值

PHP:

1. $objResponse ->addClear ( "Input1" ,"value" ) ;

* addAlert(string $sMsg)
显示一个内容为 $sMsg 的警告框(Javascrīpt的Alert)

PHP:

1. $objResponse ->addAlert ( "This is some text" ) ;

* addRedirect(string $sURL)
转跳到另一个地址$sURL，使用addscrīpt()方法实现

PHP:

1. $objResponse ->addRedirect ( "http://www.xajaxproject.org" ) ;

* addscrīpt(string $sJS)
执行Javascrīpt代码 $sJS

PHP:

1. $objResponse ->addscrīpt ( "var txt = prompt('get some text');" ) ;

* addscrīptCall()
执行Javascrīpt代码中的函数，第一个参数表示Javascrīpt函数名，后面的参数为Javascrīpt函数的参数

PHP:

1. $objResponse ->addscrīptCall ( "myJSFunction" , "arg 1" , "arg 2" , 12345 ) ;

* addRemove(string $sTarget)
从你的页面之中移除ID为$sTarget的元素

PHP:

1. $objResponse ->addRemove ( "Div2" ) ;

* addCreate(string $sParent, string $sTag, string $sId)
在已经存在的ID为$sParentId的元素内添加一个名叫$sTag的子元素，并且把它的id赋值为$sId。INPUT类型的元素须使用addCreateInput()方法.。

PHP:

1. $objResponse ->addCreate ( "childDiv" , "h3" , "myid" ) ;

* addInsert(string $sBefore, string $sTag, string $sId)
在已经存在的ID为$sBefore的元素前面添加一个名叫$sTag的元素，并且把它的id赋值为$sId。

PHP:

1. $objResponse ->addInsertAfter ( "parentDiv" , "h3" , "myid" ) ;

* addInsertAfter(string $sAfter, string $sTag, string $sId)
在已经存在的ID为$sBefore的元素后面添加一个名叫$sTag的元素，并且把它的id赋值为$sId。

PHP:

1. $objResponse ->addInsert ( "parentDiv" , "h3" , "myid" ) ;

* addCreateInput(string $sParent, string $sType, string $sName, string $sId)
在已经存在的ID为$sParent的元素内添加一个类型为$sType，Name为$sName，ID为$sId的INPUT元素。

PHP:

1. $objResponse ->addCreateInput ( "form1" , "text" , "username" , "input1" ) ;

* addInsertInput(string $sBefore, string $sType, string $sName, string $sId)
在已经存在的ID为$sBefore的元素前面添加一个类型为$sType，Name为$sName，ID为$sId的INPUT元素。

PHP:

1. $objResponse ->addInsertInput ( "input5" , "text" , "username" , "input1" ) ;

* addInsertInputAfter(string $sAfter, string $sType, string $sName, string $sId)
在已经存在的ID为$sAfter的元素后面添加一个类型为$sType，Name为$sName，ID为$sId的INPUT元素。

普通文本

PHP:

1. $objResponse ->addInsertInputAfter ( "input7" , "text" , "email" , "input2" ) ;

* addEvent(string $sTarget, string $sEvent, string $sscrīpt)
为ID是$sTarget的元素后面添加一个名为$sEvent的事件，其执行的脚本为$sscrīpt

普通文本

PHP:

1. $objResponse ->addEvent ( "contentDiv" , "onclick" , "alert(\' Hello World\' );" ) ;

* addHandler(string $sTarget, string $sEvent, string $sHandler)
为ID是$sTarget的元素名为$sEvent的事件添加一个句柄$sHandler（即Javascrīpt函数名），可以为一个事件添加多个句柄。

PHP:

1. $objResponse ->addHandler ( "contentDiv" , "onclick" , "content_click" ) ;

# addEvent与addHandler的区别：
addEvent关心的是事件被触发，即onclick中的on-，addHandler关心的是事件触发了什么操作，即onclick中的click。
其差别类似于为一个元素定义事件属性和使用addEventListener()方法定义一个事件句柄。

* addRemoveHandler(string $sTarget, string $sEvent, string $sHandler)
删除ID是$sTarget的元素名为$sEvent的事件中的句柄$sHandler。

PHP:

1. $objResponse ->addRemoveHandler ( "contentDiv" , "onclick" , "content_click" ) ;

* addIncludescrīpt(string $sFileName)
包含名为$sFileName的Javascrīpt文件。

PHP:

1. $objResponse ->addIncludescrīpt ( "functions.js" ) ;

一个独立的XML响应可能包含多个指令, 他们将按照加入响应的顺序执行. 让我们用一个用户在你的程序之中点击按钮为例来进行说明. Onclick事件调用PHP函数对应的javascrīpt封装.这个封装通过XMLHttpRequest发送异步请求到服务器给xajax调用 PHP函数. PHP函数做了一次数据库查询, 处理了一些数据, 或者序列化. 然后你使用xajaxResponse类生成包含多个指令的xajax的XML响应 ，并回送给xajax的消息分析器执行:

PHP:

1. $objResponse = new xajaxResponse( ) ;
2. $objResponse .addAssign( "myInput1" ,"value" ,$DataFromDatabase ) ;
3. $objResponse .addAssign( "myInput1" ,"style.color" ,"red" ) ;
4. $objResponse .addAppend( "myDiv1" ,"innerHTML" ,$DataFromDatabase2 ) ;
5. $objResponse .addPrepend( "myDiv2" ,"innerHTML" ,$DataFromDatabase3 ) ;
6. $objResponse .addReplace( "myDiv3" ,"innerHTML" ,"xajax" ,"<strong>xajax</strong>" ) ;
7. $objResponse .addscrīpt( "var x = prompt(" Enter Your Name");" ) ;
8. return $objResponse ;

xajax消息分析器将会解析XML消息，并执行以下工作:

2. id为myInput1的元素的值将被赋值为 $DataFromDatabase的数据.
3. id为myInput1的元素的颜色将会变为red.
4. $DataFromDatabase2的数据会被追加到id为myDiv1的元素innerHTML之中.
5. $DataFromDatabase3的数据会被预先赋值给id为myDiv2的元素innerHTML之中.
6. id为myDiv3的元素的innerHTML 之中所有的"xajax"将被替换为"xajax "; 使得所有的单词 xajax 显示加粗.
7. 一个提示框将会显示，用来询问用户姓名，从提示框返回的值会被命名为x的javascrīpt变量接收.

　　所有这些都由构成的PHP函数在服务器端执行并返回xajax的XML响应.

如何处理表单数据?
　　xajax使得异步处理表单数据非常非常的简单. xajax.getFormValues()方法会自动的从表单提取数据，并作为一个参数提交给xajax注册的PHP函数.
　　xajax.getFormValues() 仅仅需要一个参数, 可以是你需要处理得表单的id, 或者是一个实际的表单对象. 你也可以使用xajax.getFormValues作为一个参数给xajax 函数, 例如:

PHP:

1. 　　xajax_processFormData( xajax.getFormValues( 'formId' ) ) ;

　　xajax 会生成一个与表单数据对应的请求字符串给xajax服务器解析，然后以一个与表单数据对应的数组传递给PHP函数，就想你提交表单使用PHP的$_GET数组那么简单.
　 　xajax可以处理类似普通多维数组或者联合数组(哈希数组)等形式的复杂输入名字. 例如, 如果一个表单有三个多选框(checkboxes)并且都命名为 "checkbox[]", 但是值分别为 "check1", "check2", 和 "check3", 然后使用 xajax.getFormValues 函数作为参数传递给xajax 函数, 则 PHP 函数会接受到一个如下的数组:

PHP:

1. array (
2.   'checkbox' =>
3.   array (
4.     0 => 'check1' ,
5.     1 => 'check2' ,
6.     2 => 'check3' ,
7.   ) ,
8. )

作为函数参数的数组的结构与传统意义上提交表单之后的$_GET数组的结构相同. 你可以访问数组之中的checkbox 的数据: $aFormData['checkbox'][0]

如何给xajax增加定制功能?
　　xajax可以使用各种附加的用户定制功能进行扩展. 正因为xajax是完全面向对象的，并且可以使用xajaxResponse的addscrīpt()方法，所以他具有无限扩展的可能. 你可以创建你自己的xajax响应类，来继承xajaxResponse 类以及它的方法，并加上你自己定制的响应. 让我们用一个定制的增加选择组合框(select combo boxes)选项的响应指令的例子来说明. 你可以象下面这样扩展xajaxResponse 类:

PHP:

1. class myxajaxResponse extends xajaxResponse
2. [  
3.         function addAddOption( $sSelectId , $sOptionText , $sOptionValue )
4.         [
5.                 $sscrīpt   = "var ōbjOption = new Option('" .$sOptionText ."','" .$sOptionValue ."');" ;
6.                 $sscrīpt .= "document.getElementById('" .$sSelectId ."').options.add(objOption);" ;
7.                 $this ->addscrīpt ( $sscrīpt ) ;
8.         ]
9. ]  

　　现在, 取代xajaxResponse 对象的初始化, 把你自己的 myxajaxResponse 对象的初始化定义到你的 xajax PHP 函数之中:

PHP:

1. $objResponse = new myxajaxResponse( ) ;
2. $objResponse ->addAssign ( "div1" , "innerHTML" , "Some Text" ) ;
3. $objResponse ->addAddOption ( "select1" ,"New Option" ,"13" ) ;
4.  
5. return $objResponse ;

　　被调用时，这个方法将会发送需要的javascrīpt到页面并执行. 当然你也有另外一种做法Alternatively, 你可以在你的程序之中创建一个如下的javascrīpt函数:

Javascrīpt:

1. <scrīpt type="text/javascrīpt" >
2. function addOption( selectId,txt,val)
3. [
4.         var ōbjOption = new Option( txt,val) ;
5.         document.getElementById ( selectId) .options .add ( objOption) ;
6. ]
7. </scrīpt>

　　并且使用addscrīpt() 调用这个方法:

PHP:

1. $objResponse ->addscrīpt ( "addOption('select1','New Option','13');" ) ;

如何创建Loading...信息？
　　xajax提供了一个简单但是重要的功能，那就是在xajax 进行服务器调用时模拟反馈用的“Loading...”信息。xajax已经定义了两个 Javascrīpt函数：xajax.loadingFunction()和xajax.doneLoadingFunction()，你可以用你自己 定义的Javascrīpt函数来重新定义它们以满足项目的需要，例如：

Javascrīpt:

1. xajax.loadingFunction = myCustomLoadingFunction;

或者

Javascrīpt:

1. xajax.loadingFunction = function ( ) [ xajax.$( 'loadingBar' ) .style .display ='block' ;] ;