Xajax手册(第一版)

ajax

原文：http://xajax.sourceforge.net/
英文原版：Copyright © 2005 J. Max Wilson
简体中文翻译：HonestQiao(乔楚)/2005-12-7 17:23/(第一版)
什么是xajax?
xajax如何工作?
为什么我要使用xajax代替其他PHP的Ajax库?
如何在我的PHP脚本之中使用xajax?
如何异步更新内容?
如何异步处理表单数据?
如何给xajax增加定制功能?
我能在私有或者收费产品之中使用xajax吗?
 
What is xajax?
How does xajax work?
Why should I use xajax instead of another Ajax library for PHP?
How do I use xajax in my PHP script?
How do I update my content asynchronously?
How do I process form data asynchronously?
How do I add custom functionality to xajax?
May I use xajax in a proprietary product and charge for it?
什么是xajax?
Xajax是一个开源的 PHP 类库 它能够让你黏合HTML、CSS、JavaScript和PHP，轻而易举的开发功能强大、基于WEB的AJAX应用软件. 使用xajax开发的应用软件，无需重新调入页面，就能够异步调用服务器端的PHP函数和更新内容.
What is xajax?
xajax is an open source PHP class library that allows you to easily create powerful, web-based, Ajax applications using HTML, CSS, JavaScript, and PHP. Applications developed with xajax can asynchronously call server-side PHP functions and update content without reloading the page.
 
xajax 如何工作?
你的应用软件需要异步调用的PHP函数， xajax的PHP对象都生成了对应的封装好了的JavaScript函数. 当被调用时，封装的函数使用JavaScript的XMLHttpRequest对象与服务器异步通讯，调用xajax对象对应的PHP函数. 调用结束后, PHP函数由xajax返回一个xajax的XML响应传递给应用程序. XML响应包含了特定的指令和数据，他们可以被xajax的JavaScript消息分析器解析，并且被用于更新你的应用程序的内容.
How does xajax work?
The xajax PHP object generates JavaScript wrapper functions for the PHP functions you want to be able to call asynchronously from your application. When called, these wrapper functions use JavaScript's XMLHttpRequest object to asynchronously communicate with the xajax object on the server which calls the corresponding PHP functions. Upon completion, an xajax XML response is returned from the PHP functions, which xajax passes back to the application. The XML response contains instructions and data that are parsed by xajax's JavaScript message pump and used to update the content of your application.
为什么我要使用xajax代替其他PHP的ajax库?
你应该选择一个最是和你的项目需要的库.
xajax 提供了以下的功能, 它们使得ajax富有特色而又功能强大:
Why should I use xajax instead of another Ajax library for PHP?
You should choose whatever library will best meet the needs of your project.
xajax offers the following features that, together, make it unique and powerful:
Xajax特殊的 XML 响应 / javascript 消息分析系统 帮助你做到, 自动的处理函数返回的数据，按照PHP函数返回的指令更新内容或者状态. 因为xajax作了这些工作Because xajax does the work, 你不需要写javascript的回调处理函数.
xajax's unique XML response / javascript message-pump system does the work for you, automatically handling the data returned from your functions and updating your content or state according to the instructions you return from your PHP functions. Because xajax does the work, you don't have to write javascript callback handler functions.
Xajax反对将代码和数据紧密地杂糅在一起的主张, 并且保持xajax的代码从与他代码分离. 因为它是对象构造的, 你可以加上自己定制的功能给xajax去扩展xajaxResponse 类和使用addScript方法.
xajax is object oriented to maintain tighter relationships between the code and data, and to keep the xajax code separate from other code. Because it is object oriented, you can add your own custom functionality to xajax by extending the xajaxResponse class and using the addScript() method.
xajax 可以工作在 Firefox, Mozilla, 大部分基于 Mozilla 的浏览器, Internet Explorer, 和 Safari.
xajax works in Firefox, Mozilla, probably other Mozilla based browsers, Internet Explorer, and Safari.
除了更新元素的值和内含的HTML内容(innerHTML), xajax 还能用于更新样式(styles), css 类, 多选和单选按钮选择,甚至可以更新任何元素的属性.
In addition to updating element values and innerHTML, xajax can be used to update styles, css classes, checkbox and radio button selection, or nearly any other element attribute.
xajax 支持使用一维或者多维数组、关联数组(哈希数组) 作为xajax函数的参数从javascript传送给PHP. 反之Additionally, 如果你传送一个javascript的对象给xajax函数，PHP函数将接受一个描叙对象属性的关联数组(哈希数组).
xajax supports passing single and multidimensional arrays and associative arrays from javascript to PHP as parameters to your xajax functions. Additionally, if you pass a javascript object into an xajax function, the PHP function will receive an associative array representing the properties of the object.
xajax 提供了一种简单的异步表单处理方式. 使用 xajax.getFormValues() javascript 方法, 你可以轻而易举的在表单之中提交一个描绘值的数组作为参数传送到xajax异步处理函数:
xajax_processForm(xajax.getFormValues('formId');
. 它可以处理复杂的input 元素名称 ，例如 "checkbox[][]" 或者 "name[first]" 产生的多维或者关联数组(哈希数组), 就是普通提交表单那样使用PHP的$_GET数组
xajax provides easy asynchronous Form processing. By using the xajax.getFormValues() javascript method, you can easily submit an array representing the values in a form as a parameter to a xajax asynchronous function:
xajax_processForm(xajax.getFormValues('formId');
. It even works with complex input names like "checkbox[][]" and "name[first]" to produce multidimensional and associative arrays, just as if you had submitted the form and used the PHP $_GET array
使用xajax你可以动态的发送附加的javascript作为请求的响应到你的应用软件中运行，而这就和动态的更新元素的属性一样方便.
Using xajax you can dynamically send additional javascript to your application to be run in response to a request as well as dynamically update element attributes.
Xajax会自动比较PHP函数返回的数据与你已经标记需要修改的元素属性. 只有当新的数据确实可以改变现有的属性，属性才会真的被更新. 这将可消除程序在一定时间间隔内更新与当前内容相同或者不同的内容而出现的明显的闪烁.
xajax automatically compares the data returned from the PHP functions to the data that is already in the attribute of the element you have marked for change. The attribute is only updated with the new data if it will actually change what is already in the attribute. This eliminates the flicker often observed in applications that update content at a regular time interval with data which may or may not differ from extant content.
每一个通过xajax简单注册的函数都可以有不同的请求方式. 所有的函数默认使用POST方式，除非你明确的指定使用GET方式. 如果使用GET请求，你必须非常明确的考虑它确实是你所需要的
Each function registered to be accessible through xajax can have a different request type. All functions default to use POST unless GET is explicitly set. This is to encourage careful consideration of when to use GET requests
如果没有指定URI，xajax将设法自动确定脚本的URI. Xajax的自动确定算法经过了充分的验证，确保在大部分HTTPS或者未知端口的HTTP服务器上也可以正常的工作.
If no request URI is specified, xajax tries to autodetect the URL of the script. The xajax autodetection algorithm is sophisticated enough that, on most servers, it will work under a secure https:// protocol as well as http:// and with nonstandard ports.
Xajax使用UTF8编码所有的请求和响应，以确保支持绝大部分的字符和语言. Xajax已经成功测试了多种不同的UNICODE字符，包括Spanish, Russian, Arabic, and Hebrew
xajax encodes all of its requests and responses in UTF-8 so that it can support a wider range of characters and languages. xajax has been successfully tested with various unicode characters including Spanish, Russian, Arabic, and Hebrew
几乎所有xajax生成的javascript都可以通过动态的外部javascript包含到你的web程序之中. 当你在浏览器之中查看程序的源代码时，不会有JavaScript的函数定义混杂在HTML标记之中.
Nearly all of the javascript generated by xajax is included into your web application through dynamic external javascript. When you view the source of your application in your browser, the markup will be not cluttered by JavaScript function definitions.
Xajax可以使用在Smarty模板系统之中，仅仅需要创建一个smarty变量就可以包含xajax的javascript:
$smarty->assign('xajax_javascript', $xajax->getJavascript());
然后你可以使用在header模版之中使用
{$xajax_javascript}
从而把xajax应用到你的站点.
xajax can be used with the Smarty templating system by creating a variable in smarty that contains the xajax javascript:
$smarty->assign('xajax_javascript', $xajax->getJavascript());
Then you can use
{$xajax_javascript}
in your header template to use xajax on your site.
如何在我的PHP脚本之中使用xajax?
Xajax的设计是如此的富有特色，以至于不管是已有的web程序还是新的项目，它都能够被极其简单的部署和应用. 仅仅需要七步，你就可以在几乎任何PHP脚本之中加入xajax的强大功能:
How do I use xajax in my PHP script?
xajax is designed to be extremely easy to implement in both existing web applications as well as new projects. You can add the power of xajax to nearly any PHP script in seven easy steps:
包含xajax类库:
require_once("xajax.inc.php");
实例化xajax 对象:
$xajax = new xajax();
注册你需要通过xajax调用的PHP函数的名称:
$xajax->registerFunction("myFunction");
编写注册的PHP函数，并且在函数之中使用xajaxResponse 对象返回XML指令:
function myFunction($arg)
{
   // 对$arg做一些基本处理例如从数据库检索数据
   // 然后把结果赋值给变量，例如$newContent
  
   // 实例化xajaxResponse 对象
   $objResponse = new xajaxResponse();
  
   // 添加指令到响应之中，用于指派
   //指定元素(例如id="SomeElementId")的innerHTML属性的新的内容
   $objResponse->addAssign("SomeElementId","innerHTML", $newContent);
  
   //返回xajaxResponse 对象生成的XML响应
   return $objResponse->getXML();
}
在你的脚本输出任何信息之前，调用xajax用于接管请求:
$xajax->processRequests();
在页面的 标签之间, 告诉xajax生成所必需的JavaScript:
printJavascript(); ?>
在程序中，从JavaScript事件或者函数调用前面注册的函数:

Include the xajax class library:
require_once("xajax.inc.php");
Instantiate the xajax object:
$xajax = new xajax();
Register the names of the PHP functions you want to be able to call through xajax:
$xajax->registerFunction("myFunction");
Write the PHP functions you have registered and use the xajaxResponse object to return XML commands from them:
function myFunction($arg)
{
  // do some stuff based on $arg like query data from a database and
  // put it into a variable like $newContent

  // Instantiate the xajaxResponse object
  $objResponse = new xajaxResponse();

  // add a command to the response to assign the innerHTML attribute of
  // the element with id="SomeElementId" to whatever the new content is
  $objResponse->addAssign("SomeElementId","innerHTML", $newContent);

  //return the XML response generated by the xajaxResponse object
  return $objResponse->getXML();
}
Before your script sends any output, have xajax handle any requests:
$xajax->processRequests();
Between your tags, tell xajax to generate the necessary JavaScript:
printJavascript(); ?>
Call the function from a JavaScript event or function in your application:

 
就这么简单. xajax 会处理其他所有的事情. 你所要做的主要工作就是编写PHP函数，然后从函数之中返回xajax的XML响应。而后者通过xajaxResponse类可以非常简单的生成.
That's it. xajax takes care of most everything else. Your biggest task is writing the PHP functions and returning xajax XML responses from them-- which is made extremely easy by the xajaxResponse class.
 
如何异步更新内容?
Xajax最富有特色的功能或许就是xajaxResponse类. 其他的Ajax库需要你自己编写JavaScript的回调句柄去处理一个异步请求返回的数据并更新内容. xajax, 从另外一个角度来说, 允许你使用PHP简单的控制内容. xajaxResponse 让你在PHP函数之中创建XML指令返回给你的程序. XML将被xajax的消息分析器解析，指令将告诉xajax如何更新程序的内容和状态. xajaxResponse类目前提供了以下指令:
How do I update my content asynchronously?
Perhaps the most unique feature of xajax is the xajaxResponse class. Other Ajax libraries require you to write your own callback handlers in JavaScript to process the data returned from an asynchronous request and to update the content. xajax, on the other hand, allows you to easily control your content from PHP. The xajaxResponse class allows you to create XML instructions to return to your application from your PHP functions. The XML is parsed by xajax message pump and the instructions tell xajax how to update the content and state of your application. The xajaxResponse class currently offers the following commands:
addAssign($sTargetId,$sAttribute,$sData)
给命名为$sTargetId的元素的$sAttribute属性赋值$sData
$objResponse->addAssign("contentDiv","innerHTML","Some Text");
$objResponse->addAssign("checkBox1","checked","true");
addAssign($sTargetId,$sAttribute,$sData)
Assigns the $sAttribute of the element identified by $sTargetId to $sData
$objResponse->addAssign("contentDiv","innerHTML","Some Text");
$objResponse->addAssign("checkBox1","checked","true");
addAppend($sTargetId,$sAttribute,$sData)
给命名为$sTargetId的元素的$sAttribute属性追加值$sData
$objResponse->addAppend("contentDiv","innerHTML","Some Text");
addAppend($sTargetId,$sAttribute,$sData)
Appends $sData to the $sAttribute of the element identified by $sTargetId
$objResponse->addAppend("contentDiv","innerHTML","Some Text");
addPrepend($sTargetId,$sAttribute,$sData)
预备给命名为$sTargetId的元素的$sAttribute属性赋值$sData
$objResponse->addPrepend("contentDiv","innerHTML","Some Text");
addPrepend($sTargetId,$sAttribute,$sData)
Prepends $sData to the $sAttribute of the element identified by $sTargetId
$objResponse->addPrepend("contentDiv","innerHTML","Some Text");
addReplace($sTargetId,$sAttribute,$sSearch,$sData)
替换命名为$sTargetId的元素的$sAttribute属性的值之中的$sSearch为$sData
$objResponse->addReplace("contentDiv","innerHTML","text","text");
addReplace($sTargetId,$sAttribute,$sSearch,$sData)
replaces all instances of $sSearch with $sData in the $sAttribute of the element identified by $sTargetId
$objResponse->addReplace("contentDiv","innerHTML","text","text");
addClear($sTargetId,$sAttribute)
清空命名为$sTargetId的元素的$sAttribute属性的值
$objResponse->addClear("Input1","value");
addClear($sTargetId,$sAttribute)
Clears the $sAttribute of the element identified by $sTargetId
$objResponse->addClear("Input1","value");
addCreate($sParentId, $sTagname, $sId, $sType)
在已经存在的命名为$sParentId的元素下添加一个名叫$sTagName的子元素，并且把他的id赋值为$sId，可选的类型赋值为 $sType.
$objResponse->addCreate("form1","input", "pass", "password");
addCreate($sParentId, $sTagname, $sId, $sType)
Adds a new $sTagName child element to an existing element identified by $sParentId, and assigns it the id $sId and the optional type $sType.
$objResponse->addCreate("form1","input", "pass", "password");
addRemove($sElementId)
从你的程序之中移除命名为$sElementId的元素
$objResponse->addRemove("div1");
addRemove($sElementId)
Removes the element identified by $sElementId from your application
$objResponse->addRemove("div1");
addAlert($sMsg)
显示一个内容为 $sMsg 的警告框(JavaScript的Alert)
$objResponse->addAlert("This is some text");
addAlert($sMsg)
Display an alert box with $sMsg
$objResponse->addAlert("This is some text");
addScript($sJS)
执行JavaScript代码 $sJS (演示代码原文有误)
$objResponse->addScript("var txt = prompt('get some text');");
addScript($sJS)
Execute the JavaScript code $sJS
$objResponse->addAlert("var txt = prompt('get some text');");
 
一个独立的XML响应可能包含多个指令, 他们将按照加入响应的顺序执行. 让我们用一个用户在你的程序之中点击按钮为例来进行说明. Onclick事件调用PHP函数对应的javascript封装.这个封装通过XMLHttpRequest发送异步请求到服务器给xajax调用PHP函数. PHP函数做了一次数据库查询, 处理了一些数据, 或者序列化. 然后你使用xajaxResponse类生成包含多个指令的xajax的XML响应 ，并回送给xajax的消息分析器执行:
A single XML response may contain multiple commands, which will executed in the order they were added to the response. For example, let's say that a user clicks on a button in your application. The onclick event calls the javascript wrapper for a PHP function. That wrapper sends an asynchronous request to the server through XMLHttpRequest where xajax calls the PHP function. The PHP function does a database lookup, some data manipulation, or serialization. You use the xajaxResponse class to generate an xajax XML response containing multiple commands to send back to the xajax message pump to be executed:
    $objResponse = new xajaxResponse();
    $objResponse.addAssign("myInput1","value",$DataFromDatabase);
    $objResponse.addAssign("myInput1","style.color","red");
    $objResponse.addAppend("myDiv1","innerHTML",$DataFromDatabase2);
    $objResponse.addPrepend("myDiv2","innerHTML",$DataFromDatabase3);
    $objResponse.addReplace("myDiv3","innerHTML","xajax","xajax");
    $objResponse.addScript("var x = prompt("Enter Your Name");");
           
    return $objResponse->getXML();
 
$objResponse = new xajaxResponse();
    $objResponse.addAssign("myInput1","value",$DataFromDatabase);
$objResponse.addAssign("myInput1","style.color","red");
$objResponse.addAppend("myDiv1","innerHTML",$DataFromDatabase2);
$objResponse.addPrepend("myDiv2","innerHTML",$DataFromDatabase3);
$objResponse.addReplace("myDiv3","innerHTML","xajax","xajax");
$objResponse.addScript("var x = prompt("Enter Your Name");");
return $objResponse->getXML();
xajax消息分析器将会解析XML消息，并执行以下工作:
id为myInput1的元素的值将被赋值为 $DataFromDatabase的数据.
id为myInput1的元素的颜色将会变为red.
$DataFromDatabase2的数据会被追加到id为myDiv1的元素innerHTML之中.
$DataFromDatabase3的数据会被预先赋值给id为myDiv2的元素innerHTML之中.
id为myDiv3的元素的innerHTML 之中所有的"xajax"将被替换为"xajax"; 使得所有的单词 xajax 显示加粗.
一个提示框将会显示，用来询问用户姓名，从提示框返回的值会被命名为x的javascript变量接收.
The xajax message pump would parse the XML message and perform the following:
The value of the element with id myInput1 would be assigned to the data in $DataFromDatabase.
The color of the text in the element with id myInput1 would be changed to red.
The data in $DataFromDatabase2 would be appended to the innerHTML of the element with id myDiv1.
The data in $DataFromDatabase3 would be prepended to the innerHTML of the element with id myDiv2.
All occurrences of "xajax" in the innerHTML of the element with id myDiv3 would be replaced with "xajax"; making all of the instances of the word xajax appear bold.
a prompt would be displayed asking for the user's name and the value returned from the prompt would be placed into a javascript variable named x.
所有这些都由构成的PHP函数在服务器端执行并返回xajax的XML响应.
All of this is implemented on the server side in the PHP function by forming and returning an xajax XML response.
如何异步处理表单数据?
Xajax使得异步处理表单数句非常非常的简单. xajax.getFormValues()方法会自动的从表单提取数据，并作为一个参数提交给xajax注册的PHP函数.
xajax.getFormValues() 仅仅需要一个参数, 可以是你需要处理得表单的id, 或者是一个实际的表单对象. 你也可以使用xajax.getFormValues作为一个参数给xajax 函数, 例如:
xajax_processFormData(xajax.getFormValues('formId'));
xajax 会生成一个与表单数据对应的请求字符串给xajax服务器解析，然后以一个与表单数据对应的数组传递给PHP函数，就想你提交表单使用PHP的$_GET数组那么简单.
Xajax可以处理类似普通多维数组或者联合数组(哈希数组)等形式的复杂输入名字. 例如, 如果一个表单有三个多选框(checkboxes)并且都命名为 "checkbox[]", 但是值分别为 "check1", "check2", 和 "check3", 然后使用 xajax.getFormValues 函数作为参数传递给xajax 函数, 则 PHP 函数会接受到一个如下的数组:
array (
  'checkbox' =>
  array (
    0 => 'check1',
    1 => 'check2',
    2 => 'check3',
  ),
)
作为函数参数的数组的结构与传统意义上提交表单之后的$_GET数组的结构相同. 你可以访问数组之中的checkbox 的数据: $aFormData['checkbox'][0]
How do I process form data asynchronously?
xajax makes processing form data asynchronously extremely easy. The xajax.getFormValues() method can be used to automatically extract the data from a form and pass it as a parameter to a PHP function you have registered with xajax.
xajax.getFormValues() takes one argument, which can be either the id of the form you want to process, or the actual form object. You use xajax.getFormValues as a parameter to your xajax function, like this:
xajax_processFormData(xajax.getFormValues('formId'));
xajax generates a query string representing the form data which is parsed by the xajax server and passed to your PHP function as an array representing the form data, just as if you had submitted the form and used the PHP $_GET array.
xajax will even handle complex input names to generate multidimensional and associative arrays. For instance, if you have a form with three checkboxes and you give them all the name "checkbox[]", but different values like "check1", "check2", and "check3", and you use the xajax.getFormValues function as a parameter to your xajax function, the PHP function will receive and array that looks like this:
array (
  'checkbox' =>
  array (
    0 => 'check1',
    1 => 'check2',
    2 => 'check3',
  ),
)
The array argument to your function mirrors the structure that the $_GET array would have if you were to submit the form traditionally. You can then access the checkbox data in the array like this:
$aFormData['checkbox'][0]
如何给xajax增加定制功能?
Xajax可以使用各种服加的用户定制功能进行扩展. 正因为xajax是完全面向对象的，并且可以使用xajaxResponse的addScript()方法，所以他具有无限扩展的可能. 你可以创建你自己的xajax响应类，来继承xajaxResponse 类以及它的方法，并加上你自己定制的响应. 让我们用一个定制的增加选择组合框(select combo boxes)选项的响应指令的例子来说明. 你可以象下面这样扩展xajaxResponse 类:
class myXajaxResponse extends xajaxResponse
{ 
  function addAddOption($sSelectId, $sOptionText, $sOptionValue) 
  { 
    $sScript  = "var objOption = new Option('".$sOptionText."','".$sOptionValue."');";
    $sScript .= "document.getElementById('".$sSelectId."').options.add(objOption);";
    $this->addScript($sScript);
  }
}
现在, 取代xajaxResponse 对象的初始化, 把你自己的 myXajaxResponse 对象的初始化定义到你的 xajax PHP 函数之中:
$objResponse = new myXajaxResponse();
$objResponse->addAssign("div1", "innerHTML", "Some Text"); 
$objResponse->addAddOption("select1","New Option","13"); 
 
return $objResponse->getXML();
被调用时，这个方法将会发送需要的javascript到页面并执行. 当然你也有另外一种做法Alternatively, 你可以在你的程序之中创建一个如下的javascript函数:

并且使用addScript() 调用这个方法:
$objResponse->addScript("addOption('select1','New Option','13');");
How do I add custom functionality to xajax?
xajax can be extended with all kinds of additional custom functionality. The extendability of xajax is made possible because it is object oriented, and by the addScript() method of the xajaxResponse class. You can create your own xajax response class that extends the xajaxResponse class and has all of the normal xajaxResponse methods, plus your own custom responses. For instance, let's say that you wanted to add a custom response command to add options to select combo boxes. You could extend the xajaxResponse class like this:
class myXajaxResponse extends xajaxResponse
{ 
  function addAddOption($sSelectId, $sOptionText, $sOptionValue) 
  { 
    $sScript  = "var objOption = new Option('".$sOptionText."','".$sOptionValue."');";
    $sScript .= "document.getElementById('".$sSelectId."').options.add(objOption);";
    $this->addScript($sScript);
  }
}
Now, instead of instantiating an xajaxResponse object, you instantiate and use your myXajaxResponse object in your xajax PHP functions:
$objResponse = new myXajaxResponse();
$objResponse->addAssign("div1", "innerHTML", "Some Text"); 
$objResponse->addAddOption("select1","New Option","13"); 
 
return $objResponse->getXML();
This method would send the necessary javascript to the page when it was called and execute it. Alternatively, you could create a javascript function in your application:

and call it with the addScript() method:
$objResponse->addScript("addOption('select1','New Option','13');");
我能在私有或者收费产品之中使用xajax吗?
简而言之: 能，只要你愿意.
xajax PHP 类库的发布遵循 GNU Lesser General Public License (LGPL).
May I use xajax in a proprietary product and charge for it?
In short: Yes, you may.
The xajax PHP class library is released under the GNU Lesser General Public License (LGPL).
 
简体中文手册版权所有 © 2005 HonestQiao(乔楚)
Copyright © 2005 J. Max Wilson