Xajax中文手冊(第一版)

2024-09-01 08:15:07

字體：大中小

來源：轉載

供稿：網友

原文：http://xajax.sourceforge.net/

簡體中文翻譯：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();

在頁面的 <head></head> 標簽之間, 告訴xajax生成所必需的javascript:

<?php $xajax->printjavascript(); ?>

在程序中，從javascript事件或者函數調用前面注冊的函數:

Include the xajax class library:

require_once("xajax.inc.php");

Instantiate the xajax object:

$xajax = new 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 <head></head> tags, tell xajax to generate the necessary javascript:

<?php $xajax->printjavascript(); ?>

Call the function from a javascript event or function in your application:
<div id="SomeElementId"></div>

就這么簡單. 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","<strong>text</strong>");

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","<strong>text</strong>");

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","<strong>xajax</strong>");

$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","<strong>xajax</strong>");

$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"將被替換為"<strong>xajax</strong>"; 使得所有的單詞 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 "<strong>xajax</strong>"; 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函數:

function addOption(selectId,txt,val)

{

var objOption = new Option(txt,val);

document.getElementById(selectId).options.add(objOption);

}

</script>

并且使用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:

function addOption(selectId,txt,val)

{

var objOption = new Option(txt,val);

document.getElementById(selectId).options.add(objOption);

}

</script>

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?