API: connection YAHOO.util.Connect (YUI Library)

# Yahoo! UI Library

### connection 2.8.1

Yahoo! UI Library > connection > YAHOO.util.Connect
Search:
Filters Show Private Show Protected Show Deprecated

## Class YAHOO.util.Connect

The Connection Manager singleton provides methods for creating and managing asynchronous transactions.

### Properties

#### _customEvents - `private static object`

A reference table that maps callback custom events members to its specific event name.

#### _default_form_header - `private static boolean`

The default header used for transactions involving the use of HTML forms.

#### _default_post_header - `private static boolean`

The default header used for POST transactions.

#### _default_xhr_header - `private static boolean`

The default header value for the label "X-Requested-With". This is sent with each transaction, by default, to identify the request as being made by YUI Connection Manager.

#### _formNode - `private static object`

Property modified by setForm() to set a reference to the HTML form node if the desired action is file upload.

#### _has_default_header - `private static boolean`

Determines if custom, default headers are set for each transaction.

#### _has_http_headers - `private static boolean`

Determines if HTTP headers are set.

#### _hasSubmitListener - `private static object`

Determines whether YAHOO.util.Event is available and returns true or false. If true, an event listener is bound at the document level to trap click events that resolve to a target type of "Submit". This listener will enable setForm() to determine the clicked "Submit" value in a multi-Submit button, HTML form.

#### _http_header - `private static object`

Object literal of HTTP header(s)

#### _isFileUpload - `private static boolean`

Property modified by setForm() to determine if a file(s) upload is expected.

#### _isFormSubmit - `private static boolean`

Property modified by setForm() to determine if the data should be submitted as an HTML form.

#### _msxml_progid - `private static array`

Array of MSFT ActiveX ids for XMLHttpRequest.

#### _poll - `private static object`

Collection of polling references to the polling mechanism in handleReadyState.

#### _polling_interval - `private static int`

The polling frequency, in milliseconds, for HandleReadyState. when attempting to determine a transaction's XHR readyState. The default is 50 milliseconds.

#### _sFormData - `private static string`

Property modified by setForm() to set the HTML form data for each transaction.

#### _submitElementValue - `private static string`

Tracks the name-value pair of the "clicked" submit button if multiple submit buttons are present in an HTML form; and, if YAHOO.util.Event is available.

#### _timeOut - `private static object`

Queue of timeout values for each transaction callback with a defined timeout value.

#### _transaction_id - `private static int`

A transaction counter that increments the transaction id for each transaction.

#### _use_default_post_header - `private static boolean`

Determines if a default header of Content-Type of 'application/x-www-form-urlencoded' will be added to any client HTTP headers sent for POST transactions.

#### _use_default_xhr_header - `private static boolean`

Determines if a default header of 'X-Requested-With: XMLHttpRequest' will be added to each transaction.

#### abortEvent - `private static CustomEvent`

Custom event that fires when a transaction is successfully aborted.

#### completeEvent - `private static CustomEvent`

Custom event that fires when a transaction response has completed.

#### failureEvent - `private static CustomEvent`

Custom event that fires when handleTransactionResponse() determines a response in the HTTP 4xx/5xx range.

#### startEvent - `private static CustomEvent`

Custom event that fires at the start of a transaction

#### successEvent - `private static CustomEvent`

Custom event that fires when handleTransactionResponse() determines a response in the HTTP 2xx range.

### Methods

#### _swf

`private static void _swf ( URI )`
This method creates and instantiates the Flash transport.

Parameters:
  `URI <string>` to connection.swf.

#### _xdrStart

`private static void _xdrStart ( The )`
This method fires the global and transaction start events.

Parameters:
  `The <object>` transaction object.
  `The <string>` transaction's callback object.

#### abort

`static boolean abort ( o , callback , isTimeout )`
Method to terminate a transaction, if it has not reached readyState 4.

Parameters:
  `o <object>` The connection object returned by asyncRequest.
  `callback <object>` User-defined callback object.
  `isTimeout <string>` boolean to indicate if abort resulted from a callback timeout.

#### appendPostData

`private static array appendPostData ( postData )`
Parses the POST data and creates hidden form elements for each key-value, and appends them to the HTML form object.

Parameters:
  `postData <string>` The HTTP POST data

Returns: `array`
  formElements Collection of hidden fields.

#### asyncRequest

`static object asyncRequest ( method , uri , callback , postData )`
Method for initiating an asynchronous request via the XHR object.

Parameters:
  `method <string>` HTTP transaction method
  `uri <string>` Fully qualified path of resource
  `callback <callback>` User-defined callback function or object
  `postData <string>` POST body

Returns: `object`
  Returns the connection object

#### createExceptionObject

`private static object createExceptionObject ( tId , callbackArg , isAbort )`
If a transaction cannot be completed due to dropped or closed connections, there may be not be enough information to build a full response object. The failure callback will be fired and this specific condition can be identified by a status property value of 0. If an abort was successful, the status property will report a value of -1.

Parameters:
  `tId <int>` The Transaction Id
  `callbackArg <callbackArg>` The user-defined argument or arguments to be passed to the callback
  `isAbort <boolean>` Determines if the exception case is caused by a transaction abort

#### createFrame

`private static void createFrame ( optional )`
Creates an iframe to be used for form file uploads. It is remove from the document upon completion of the upload transaction.

Parameters:
  `optional <string>` qualified path of iframe resource for SSL in IE.

#### createResponseObject

`private static object createResponseObject ( o , callbackArg )`
This method evaluates the server response, creates and returns the results via its properties. Success and failure cases will differ in the response object's property values.

Parameters:
  `o <object>` The connection object
  `callbackArg <callbackArg>` The user-defined argument or arguments to be passed to the callback

#### createXhrObject

`private static createXhrObject ( transactionId )`
Instantiates a XMLHttpRequest object and returns an object with two properties: the XMLHttpRequest instance and the transaction id.

Parameters:
  `transactionId <int>` Property containing the transaction id for this transaction.

Returns: ``
  object

#### getConnectionObject

`private static object getConnectionObject ( )`
This method is called by asyncRequest to create a valid connection object for the transaction. It also passes a transaction id and increments the transaction id counter.

#### handleReadyState

`private static void handleReadyState ( o , callback )`
This method serves as a timer that polls the XHR object's readyState property during a transaction, instead of binding a callback to the onreadystatechange event. Upon readyState 4, handleTransactionResponse will process the response, and the timer will be cleared.

Parameters:
  `o <object>` The connection object
  `callback <callback>` The user-defined callback object

#### handleTransactionResponse

`private static void handleTransactionResponse ( o , callback , isAbort )`
This method attempts to interpret the server response and determine whether the transaction was successful, or if an error or exception was encountered.

Parameters:
  `o <object>` The connection object
  `callback <object>` The user-defined callback object
  `isAbort <boolean>` Determines if the transaction was terminated via abort().

#### handleXdrResponse

`private static void handleXdrResponse ( The )`
This method is the initial response handler for XDR transactions. The Flash transport calls this function and sends the response payload.

Parameters:
  `The <object>` response object sent from the Flash transport.

#### initCustomEvents

`private static void initCustomEvents ( o , callback )`
This method creates and subscribes custom events, specific to each transaction

Parameters:
  `o <object>` The connection object
  `callback <callback>` The user-defined callback object

#### initHeader

`static void initHeader ( label , value , isDefault )`
Method that initializes the custom HTTP headers for the each transaction.

Parameters:
  `label <string>` The HTTP header label
  `value <string>` The HTTP header value
  `isDefault <string>` Determines if the specific header is a default header automatically sent with each transaction.

#### isCallInProgress

`static boolean isCallInProgress ( o )`
Determines if the transaction is still being processed.

Parameters:
  `o <object>` The connection object returned by asyncRequest

#### releaseObject

`private static void releaseObject ( o )`
Dereference the XHR instance and the connection object after the transaction is completed.

Parameters:
  `o <object>` The connection object

#### resetDefaultHeaders

`static void resetDefaultHeaders ( )`
Resets the default HTTP headers object

#### resetFormState

`private static void resetFormState ( )`
Resets HTML form properties when an HTML form or HTML form with file upload transaction is sent.

#### setDefaultPostHeader

`static setDefaultPostHeader ( b )`
Member to override the default POST header.

Parameters:
  `b <boolean>` Set and use default header - true or false .

Returns: ``
  void

#### setDefaultXhrHeader

`static setDefaultXhrHeader ( b )`
Member to override the default transaction header..

Parameters:
  `b <boolean>` Set and use default header - true or false .

Returns: ``
  void

#### setForm

`static string setForm ( form , optional )`
This method assembles the form label and value pairs and constructs an encoded string. asyncRequest() will automatically initialize the transaction with a a HTTP header Content-Type of application/x-www-form-urlencoded.

Parameters:
  `form <string || object>` id or name attribute, or form object.
  `optional <boolean>` enable file upload.
  `optional <boolean>` enable file upload over SSL in IE only.

Returns: `string`
  string of the HTML form field name and value pairs..

#### setHeader

`private static void setHeader ( o )`
Accessor that sets the HTTP headers for each transaction.

Parameters:
  `o <object>` The connection object for the transaction.

#### setPollingInterval

`static setPollingInterval ( i )`
Member to modify the default polling interval.

Parameters:
  `i <int>` The polling interval in milliseconds.

Returns: ``
  void

#### setProgId

`static setProgId ( id )`
Member to add an ActiveX id to the existing xml_progid array. In the event(unlikely) a new ActiveX id is introduced, it can be added without internal code modifications.

Parameters:
  `id <string>` The ActiveX id to be added to initialize the XHR object.

Returns: ``
  void

#### transport

`static void transport ( URI )`
This method instantiates the Flash transport and establishes a static reference to it, used for all XDR requests.

Parameters:
  `URI <string>` to connection.swf.

#### uploadFile

`private static void uploadFile ( id , callback , uri , postData )`
Uploads HTML form, inclusive of files/attachments, using the iframe created in createFrame to facilitate the transaction.

Parameters:
  `id <int>` The transaction id.
  `callback <object>` User-defined callback object.
  `uri <string>` Fully qualified path of resource.
  `postData <string>` POST data to be submitted in addition to HTML form.

#### xdr

`private static void xdr ( The , HTTP , URI , The )`
This method calls the public method on the Flash transport to start the XDR transaction. It is analogous to Connection Manager's asyncRequest method.

Parameters:
  `The <object>` transaction object.
  `HTTP <string>` request method.
  `URI <string>` for the transaction.
  `The <object>` transaction's callback object.
  `The <object>` JSON object used as HTTP POST data.

Copyright © 2010 Yahoo! Inc. All rights reserved.