ajax prototype架構之Ajax.Request 類

使用 Ajax.Request 類

如果你不使用任何的協助程式包，你很可能編寫了整個大量的代碼來建立 XMLHttpRequest 對象並且非同步跟蹤它的進程，然後解析響應並處理它。當你不需要支援多於一種類型的瀏覽器時你會感到非常的幸運。

為了支援 AJAX 功能。這個包定義了 Ajax.Request 類。

假如你有一個應用程式可以通過http://yoursever/app/get_sales?empID=1234&year=1998 與伺服器通訊。它返回下面這樣的 XML 響應：

<?xml version="1.0" encoding="utf-8" ?> 
<ajax-response>
    <response type="object" id="productDetails">
        <monthly-sales>
            <employee-sales>
                <employee-id>1234</employee-id> 
                <year-month>1998-01</year-month> 
                <sales>$8,115.36</sales> 
            </employee-sales>
            <employee-sales>
                <employee-id>1234</employee-id> 
                <year-month>1998-02</year-month> 
                <sales>$11,147.51</sales> 
            </employee-sales>
        </monthly-sales>
    </response>
</ajax-response>    

用 Ajax.Request 對象和伺服器通訊並且得到這段 XML 是非常簡單的。下面的例子示範了它是如何完成的：

<script>...
    function searchSales()
    ...{
        var empID = $F(''lstEmployees'');
        var y = $F(''lstYears'');
        var url = ''http://yourserver/app/get_sales'';
        var pars = ''empID='' + empID + ''&year='' + y;
        
        var myAjax = new Ajax.Request(
            url, 
            ...{
                method: ''get'', 
                parameters: pars, 
                onComplete: showResponse
            });
        
    }

    function showResponse(originalRequest)
    ...{
        // 將返回的 XML 放到 textarea 內
        $(''result'').value = originalRequest.responseText;
    }
</script>

<select id="lstEmployees" size="10" onchange="searchSales()">
    <option value="5">Buchanan, Steven</option>
    <option value="8">Callahan, Laura</option>
    <option value="1">Davolio, Nancy</option>
</select>
<select id="lstYears" size="3" onchange="searchSales()">
    <option selected="selected" value="1996">1996</option>
    <option value="1997">1997</option>
    <option value="1998">1998</option>
</select>
<br><textarea id=result cols=60 rows=10 ></textarea>

你注意到傳入 Ajax.Request 構造方法的第二個對象了嗎？參數 {method: ''get'', parameters: pars, onComplete: showResponse} 表示一個匿名對象的真實寫法。他表示你傳入的這個對象有一個名為 method 值為 ''get'' 的屬性，另一個屬性名稱為 parameters 包含 HTTP 要求的查詢字串，和一個 onComplete 屬性/方法包含函數 showResponse。

還有一些其它的屬性可以在這個對象裡面定義和設定，如 asynchronous，可以為 true 或 false 來決定 AJAX 對伺服器的調用是否是非同步（預設值是 true）。

這個參數定義 AJAX 調用的選項。在我們的例子中，在第一個參數通過 HTTP GET 命令請求那個 url，傳入了變數 pars 包含的查詢字串，Ajax.Request 對象在它完成接收響應的時候將調用 showResponse 方法。

也許你知道，XMLHttpRequest 在HTTP請求期間將報告進度情況。這個進度被描述為四個不同階段：Loading, Loaded, Interactive, 或 Complete。你可以使 Ajax.Request 對象在任何階段調用自訂方法 ，Complete 是最常用的一個。想調用自訂的方法只需要簡單的在請求的選項參數中的名為 onXXXXX 屬性/方法中提供自訂的方法對象。 就像我們例子中的 onComplete。你傳入的方法將會被用一個參數調用，這個參數是 XMLHttpRequest 對象自己。你將會用這個對象去得到返回的資料並且或許檢查包含有在這次調用中的HTTP 結果代碼的 status 屬性。

還有另外兩個有用的選項用來處理結果。我們可以在 onSuccess 選項處傳入一個方法，當 AJAX 無誤的執行完後調用，相反的，也可以在 onFailure 選項處傳入一個方法，當伺服器端出現錯誤時調用。正如 onXXXXX 選項傳入的方法一樣，這兩個在被調用的時候也傳入一個帶有 AJAX 請求的 XMLHttpRequest 對象。

我們的例子沒有用任何有趣的方式處理這個 XML 響應， 我們只是把這段 XML 放進了一個文本域裡面。對這個響應的一個典型的應用很可能就是找到其中的想要的資訊，然後更新頁面中的某些元素， 或者甚至可能做某些 XSLT 轉換而在頁面中產生一些 HTML。

在 1.4.0 版本中，一種新的事件回傳外理被引入。如果你有一段代碼總是要為一個特殊的事件執行，而不管是哪個 AJAX 調用引發它，那麼你可以使用新的 Ajax.Responders 對象。

假設你想要在一個 AJAX 調用正在運行時，顯示一些提示效果，像一個不斷轉動的表徵圖之類的，你可以使用兩個全域事件控制代碼來做到，其中一個在第一個調用開始時顯示表徵圖，另一個在最後一個調用完成時隱藏表徵圖。看下面的例子。

<script>
    var myGlobalHandlers = ...{
        onCreate: function()...{
            Element.show(''systemWorking'');
        },

        onComplete: function() ...{
            if(Ajax.activeRequestCount == 0)...{
                Element.hide(''systemWorking'');
            }
        }
    };

    Ajax.Responders.register(myGlobalHandlers);
</script>

<div id=''systemWorking''><img src=''spinner.gif''>Loading...</div>

更完全的解釋，請參閱 Ajax.Request 參考和options 參考。