Yahoo! UI Library::Connection Manager の訳

Javascript


http://developer.yahoo.net/yui/connection/index.html

いわゆるAJAXを簡単に出来るようにするラッパ・クラスみたいです。prototype.jsにも似たようなクラスがありましたよね。こちらのライブラリでも非常に簡単な手続きで、Ajax通信を実現することが出来ます。

Yahoo! UI Library: Connection Manager

The Connection Manager is a utility that enables you to make in-page HTTP requests through a simplified interface to the XMLHttpRequest object. Connection Manager handles cross-browser instantiation of XMLHttpRequest, negotiates the server response and returns the results to a pre-defined callback function you create.

This page describes the Connection Manager component and provides examples of its use. It contains these sections:


Connection ManagerはXMLHttpRequestオブジェクトを通したシンプルなインターフェースで、ページ内（非遷移）HTTPリクエストを可能にしてくれるユーティリティです。Connection Manager はクロスブラウザなXMLHttpRequestインスタンスを扱い、サーバーとの通信をしてユーザーが定義したコールバック関数の結果を返します。

このページはConnection Managerコンポーネントについて書いています。また使い方のサンプルを載せています。…略

Getting Started

<!-- Namespace source file --> 
<script src = "http://yourwebsite.com/util/YAHOO.js" ></script>

<!-- Connection Manager source file --> 
<script src = "http://yourwebsite.com/util/connection.js" ></script>

Connection ManagerはYAHOO.util.Connectのオブジェクト で定義されます。

Basic Connections

To make an asynchronous network connection with the Connection Manager component, use this code:



var cObj = YAHOO.util.Connect.asyncRequest('GET','ｈttp://www.yahoo.com',callback,null);
In this example:

  • Use the asyncRequest method to make an asynchronous request (XMLHttpRequest). This method returns a reference to the connection object, which is assigned to the variable cObj. This method takes four arguments: the HTTP method, the request, URL, the function callback, and data to post for an HTTP POST request.
  • This connection uses GET as the HTTP, and makes the request to the URL http://www.yahoo.com.
  • The callback argument is the callback function object, which you must have defined previously in your script.
  • The null is the data to post, in the case of an HTTP POST. As this is an HTTP GET request, there is no data and this argument is null.

See the examples in Using Connection Manager or the API Documentation for more details.


接続の基本

Connection Managerコンポーネントを使って非同期ネットワークコネクションを張るには下記のようなコードを使います。



//cObjはconnectionオブジェクトへのリファレンス

var cObj = YAHOO.util.Connect.asyncRequest('GET','ｈｔｔｐ://www.yahoo.com',callback,null);

・(XMLHttpRequest)非同期リクエストをするにはasyncRequest()メソッドを使を使います。
このメソッドの返り値は、connectionオブジェクトへのリファレンスです。サンプルではcObj変数に代入しています。このメソッドは４つの引数をとります。
①HTTPメソッド
②ＵＲＬ
③コールバック関数
④POSTリクエストのボディ

  • このコネクションの場合、HTTP通信のGETを使っています。そしてｈttp://www.yahoo.com.にたいしてリクエストを送信しています。
  • callback引数は、コールバック関数のオブジェクトです。スクリプトの中で、必ず事前に定義しておかなければなりません。
  • 'null'はHTTP POSTを使う場合に、送るデーターを指定します。ここではGETリクエストで送るデーターがないので、'null'になります。
  • Connection Managerを使うに際には、サンプルを見ていただくか、APIドキュメントで詳細を見てください。

Using Connection Manager

This section describes several common uses of the Connection Manager, with examples.

  • Asynchronous Connections
  • The Callback Object
  • Success Case
  • Failure Case
  • Forms
  • Transaction Status

このセクションではConnection Managerの一般的な使い方についてサンプルを交えていくつか記しています

・非同期接続
・コールバック・オブジェクト
・成功した場合?
・失敗した場合?
・フォーム
・トランザクションのステータス

Asynchronous Connection

非同期接続

An asynchronous connection requires a user-defined, callback object with defined properties to handle the response once a transaction is complete. Calling the asyncRequest method without providing a callback results in silent success and failure cases.

This example shows how to construct a callback object with two members - success and failure - to handle the server response. The appropriate function will be called and receive a response object as an argument.



// oはサーバーからのレスポンスを格納したオブジェクト
var responseSuccess = function(o){ //transaction success case logic } //成功時

var responseFailure = function(o){ //transaction failure case logic } //失敗時
//コールバック関数を格納するオブジェクト

var callback =

{

      success:responseSuccess,

	failure:responseFailure

}

非同期接続では、トランザクションが完了した時のレスポンスを扱うために、ユーザー定義のコールバック・オブジェクトと定義済みプロパティが必要です。asyncRequest()メソッドはコールバック関数を提供しません。ただ結果として成功か失敗かを返すだけです。

このサンプルで、成功時・失敗時のサーバーレスポンスを扱うコールバックオブジェクトのコンストラクト方法をお見せします。(トランザクション失敗時には失敗時の、成功時には成功時の）適切な関数が呼ばれ、レスポンスで返ってきたオブジェクトを引数として受け取ります。

The Callback Object

In the asynchronous example, we defined a callback object to handle the server response. The callback object should include the following members to correctly process the response:



var callback =

{

  success: function ,

  failure: function,

  argument:  string, number, object, array

}

When negotiating a transaction, the connection manager will determine if the connection and response was successful and call the appropriate callback handler. Additionally, you can define the member argument to pass values to both the success and failure handler.

However, in a scenario where an object's method is used as a callback, any usage of "this" in the method lose scope. While this can be partially resolved by passing a reference to "this" as a user-defined argument, it still invalidates the use of 'this' within the member. To use an object's method as a callback handler and maintain scope, define the callback member scope with a value of 'this'. 



//コールバックオブジェクト

var callback =

{

  success: this.handleSuccess ,

  failure: this.handleFailure,

  argument: arguments ,

  scope: this

}
YAHOO.util.Connect.asyncRequest('GET','http://www.yahoo.com',callback,null);



コールバック・オブジェクト

非同期のサンプルでは、サーバーレスポンスを扱う「コールバックオブジェクト」を定義しました。レスポンスを正しく処理するには、コールバックオブジェクトに次のようなメンバを含んでおく必要があります。



//コールバックオブジェクト

var callback =

{

  success: function ,

  failure: function,

  argument:  string, number, object, array

}

トランザクション通信をしているとき、Connection Managerは、接続とレスポンスがうまく通ってるかどうかを判断し、適切なコールバックハンドラを呼び出します。また、成功時のハンドラと失敗時のハンドラへ渡す引数をメンバ(argument)として定義することが出来ます。


しかし、オブジェクトのメソッドがコールバックとして呼ばれるような場合だと、メソッド内で"this"をどんな風に使ってもスコープを失ってしまいます。この問題はユーザー定義の引数として"this"へリファレンスを渡すことで解決される一方、メンバの中での'this'の使用を無効化してしまいます。オブジェクトのメソッドをコールバックハンドラとして使い、スコープを保ち続けるには'this'を値に取るコールバック・メンバ・スコープを定義します。

＊書いてることはなんとなく分かるんですけど、うまく説明は出来ません･･･



//コールバックオブジェクト

var callback =

{

  success: this.handleSuccess ,

  failure: this.handleFailure,

  argument: arguments ,

  scope: this

}
YAHOO.util.Connect.asyncRequest('GET','http://www.yahoo.com',callback,null);

Success Case

In a success case, an object with the following properties is passed to the callback object's success handler:

成功時には、コールバック・オブジェクト・サクセス・ハンドラに次のプロパティを伴ったオブジェクトが渡されます。

　　　
プロパティ 説明
tld トランザクションID
status トランザクションの結果のHTTPステータスコード
statusText HTTPステータスに付随するメッセージ
allResponseHeaders 返ってきたHTTPヘッダ全て。文字列。
responseText サーバーレスポンス。文字列である
responseXML サーバーレスポンス。XML DOMオブジェクトである
argument コールバックオブジェクト中で定義された、ユーザー定義のメンバ

Failure Case

If the server responds with an error, Connection Manager will try to capture as much information as possible and pass an object to the callback object's failure handler. The properties will be the same as in a success case, except the properties will be defined with values only when they are available.

If the server does not respond, either due to the connection being dropped or closed, there may not be a readable response. If a transaction is terminated in such a manner, the callback object's failure handler will receive an object with the following properties:

失敗した場合

サーバーがエラー応答した場合、Connection Manager はできる限りの情報をキャプチャーしようとします。そして、オブジェクトをコールバック・オブジェクトの失敗時のハンドラに渡します。値が取得可能なときにだけ定義されるという点を除いて、プロパティは成功時と全く同じになります。

もしサーバーが応答しない場合は、接続が切れてるか閉じてるかどっちかのせいで、読み取り可能なレスポンスがないかもしれません。トランザクションがこういうやり方で中断された場合、コールバック・オブジェクトの失敗時のハンドラは次のようなプロパティを伴ったオブジェクトを受け取ります。

　　
プロパティ 説明
tld トランザクションID
status 0
statusText "communication failure"
　argument コールバックオブジェクト中で定義された、ユーザー定義の引数??

Forms

The Connection Manager can automatically perform an HTML form POST by initializing a transaction through the setForm method. By calling this method before initiating the transaction, a POST body is constructed from the named form and submitted to the specified URL. To use this functionality, your HTML form and form elements must have a defined name attribute. 



YAHOO.util.Connect.setForm(formName);

var cObj = YAHOO.util.Connect.asyncRequest('POST', 'http://www.yahoo.com', callbackObject);

フォーム（から値を取得）

＊Name属性のついたフォームから値を抜き出す

Connection Managerは　setForm()メソッドでトランザクションを初期化することによって、HTMLフォームの"POST"機能を自動的に執り行います。setForm()メソッドをトランザクションの初期化前に呼び出すと、POSTのボディをNAMEをつけたフォームの値で構成し、asyncRequest()メソッドで指定したURLに送信します。ちゃんと機能させるには、HTMLフォームとフォーム要素にNAME属性を定義しておかないといけません。

Transaction Status

The isCallInProgress method can be used to determine if an asynchronous transaction has not completed. The method returns true if the transaction is still in progress. 



//Initiate an asynchronous transaction.

var cObj = YAHOO.util.Connect.asyncRequest('GET','http://www.yahoo.com',callback);

//The variable callStatus will be true if the transaction has not been completed.

var callStatus = YAHOO.util.Connect.isCallInProgress(cObj);

To abort a transaction in progress, call the abort method and pass the connection object - returned by the original asyncRequest method - as the parameter. 



//Initiate an asynchronous transaction.

var cObj = YAHOO.util.Connect.asyncRequest('GET','http://www.yahoo.com', callback)

//Abort the transaction

YAHOO.util.Connect.abort(cObj);


トランザクション・ステータス

isCallInProgressメソッドは、非同期トランザクションが完了しなかった場合に使われうるものです。このメソッドは、トランザクションがなおも進行中であればtrueを返します。



//非同期トランザクションの開始

cObjはコネクションオブジェクト

var cObj = YAHOO.util.Connect.asyncRequest('GET','http://www.yahoo.com',callback);

//トランザクションが終わってないなら、返り値はtrueである

var callStatus = YAHOO.util.Connect.isCallInProgress(cObj);

進行中のトランザクションを中断するには、abort()メソッドを呼び出し、コネクション・オブジェクトをパラメーターとして渡します。コネクション・オブジェクトとはasyncRequest()メソッドの返り値のことです。



//非同期トランザクションの開始

var cObj = YAHOO.util.Connect.asyncRequest('GET','http://www.yahoo.com', callback)

//トランザクションの中断

YAHOO.util.Connect.abort(cObj);