Ajax class

From PhiWiki
Jump to: navigation, search

Phi supports AJAX (asynchronous JavaScript and XML). With AJAX you have the possibility to get updated data via a HTTP request at runtime (when a document is already loaded). For example when a user enters characters in a search string a result set can be presented on the fly. A default Ajax instance is always created and stored in phi.ajax.

Usage

Beside plain HTML, the Ajax class is also available in Phi native mode for Javascript.pngJavaScript. You reference AJAX through the PhiBase class phi:

var a=phi.ajax;

Reimplement the following function to react on state changes:

phi.ajax.onreadystatechange=function() {
  if ( phi.ajax.readyState==4 ) {
    alert( phi.ajax.responseText );
  }
}

If you need more than one AJAX object you can create a new one using phi.createAjax() (available since v1.3.0).

var ajax=phi.createAjax();

Note: AJAX is not available in Serverscript.pngServerScript.

Properties

  • Number readyState [read]
  • String responseText [read]
  • Number status [read]
  • String statusText [read]

Number readyState

Returns the readyState of the request. Use the phi.ajax.onreadystatechange handler to react on request state changes.

phi.ajax.onreadystatechange=function() {
  if ( phi.ajax.readyState==4 ) {
    //request finished
  }
};

Returned states are:

  • 0 - Unsent
  • 1 - Opened
  • 2 - Headers received
  • 3 - Loading
  • 4 - Completed

String responseText

Returns the content of the request.

var mycontent;
phi.ajax.onreadystatechange=function() {
  if ( phi.ajax.readyState==4 ) {
    mycontent=phi.ajax.responseText;
  }
};

If the HTTP response header contains a field with Content-Type and charset=xxx the text is translated with the appropriate codec xxx. Otherwise UTF-8 is assumed.

Number status

Contains the HTTP status code (for example 404 for file not found or 200 for OK).

Note: the status code is set when the request is finished (as soon as the phi.ajax.readyState is set to 4).

See also: phi.ajax.statusText.

String statusText

Returns the human readable HTTP status string (for example OK).

Functions

Void abort()

Aborts the current HTTP request.

String getAllResponseHeaders()

Returns all response headers as a 'key: value' pair separated by \r\n.

phi.ajax.onreadystatechange=function() {
  if ( phi.ajax.readyState==2 ) {
    alert( phi.ajax.getAllResponseHeaders() );
  }
};

Note: Set-Cookie headers are filtered out for security reasons.

String getResponseHeader()

Returns the HTTP response header value for header.

var value=phi.ajax.getResponseHeader( 'Content-Length' );

Note: the phi.ajax.readyState must be at least 2.

Void open()

Opens an URL with method, url, async, user and password.

phi.ajax.open( method, url, async=true, user=String(), password=String() );

phi.ajax.open( 'GET', '/dyndata.txt?philang=es' );

Attention: in Phi native mode only the asynchronous mode is available, async=false will not work!

Void send()

Sends the request with an additional body if the opened method is POST, ie. phi.ajax.open( 'POST', url ).

phi.ajax.send( body );

phi.ajax.setRequestHeader( 'Content-Type', 'application/x-www-form-urlencoded' );
phi.ajax.send( 'philang=de&name=myname' );

Void setRequestHeader()

Sets a HTTP request header.

phi.ajax.setRequestHeader( header, value );

phi.ajax.setRequestHeader( "Content-Type", "application/x-www-form-urlencoded" );
phi.ajax.send( "philang=fr" );

Note: some HTTP header are not allowed to be overwritten, like "accept-charset", "accept-encoding", "connection", "content-length", "cookie", "cookie2", "content-transfer-encoding", "date", "expect", "host", "keep-alive", "referer", "te", "trailer", "transfer-encoding", "upgrade", "user-agent", "via" and all headers starting with "sec".

Event handler

onreadystatechange

This event handler is notified whenever the request state changes.

function stateChanged() {
  if ( phi.ajax.readyState==4 ) {
    // request finished
  }
}

phi.ajax.onreadystatechange=stateChanged;

Additional notes

The responseXML is currently not supported, because Phi does not provide a DOM structure for its elements.