Namespace jsf.ajax

The namespace for Ajax functionality.
Defined in: jsf.js.

Namespace Summary
Constructor Attributes	Constructor Name and Description
	jsf.ajax The namespace for Ajax functionality.

Method Summary
Method Attributes	Method Name and Description
<static>	jsf.ajax.addOnError(callback) Register a callback for error handling.
<static>	jsf.ajax.addOnEvent(callback) Register a callback for event handling.
<static>	jsf.ajax.request(source, event, options) Send an asynchronous Ajax request to the server.
<static>	jsf.ajax.response(request, context) Receive an Ajax response from the server.

Namespace Detail

jsf.ajax

The namespace for Ajax functionality.

Method Detail

<static> jsf.ajax.addOnError(callback)

Usage:


jsf.ajax.addOnError(handleError);
...
var handleError = function handleError(data) {
...
}

Implementation Requirements:

This function must accept a reference to an existing JavaScript function. The JavaScript function reference must be added to a list of callbacks, making it possible to register more than one callback by invoking jsf.ajax.addOnError more than once. This function must throw an error if the callback argument is not a function.

Parameters:
callback: a reference to a function to call on an error

<static> jsf.ajax.addOnEvent(callback)

Usage:


jsf.ajax.addOnEvent(statusUpdate);
...
var statusUpdate = function statusUpdate(data) {
...
}

Implementation Requirements:

This function must accept a reference to an existing JavaScript function. The JavaScript function reference must be added to a list of callbacks, making it possible to register more than one callback by invoking jsf.ajax.addOnEvent more than once. This function must throw an error if the callback argument is not a function.

Parameters:
callback: a reference to a function to call on an event

<static> jsf.ajax.request(source, event, options)

Send an asynchronous Ajax request to the server.

Usage:


Example showing all optional arguments:

<commandButton id="button1" value="submit"
    onclick="jsf.ajax.request(this,event,
      {execute:'button1',render:'status',onevent: handleEvent,onerror: handleError});return false;"/>
</commandButton/>

Implementation Requirements:

This function must:

Be used within the context of a form.
Capture the element that triggered this Ajax request (from the source argument, also known as the source element.
If the source element is null or undefined throw an error.
If the source argument is not a string or DOM element object, throw an error.
If the source argument is a string, find the DOM element for that string identifier.
If the DOM element could not be determined, throw an error.
If the onerror and onevent arguments are set, they must be functions, or throw an error.
Determine the source element's form element.
Get the form view state by calling jsf.getViewState passing the form element as the argument.

Collect post data arguments for the Ajax request.

The following name/value pairs are required post data arguments:

name	value
`javax.faces.ViewState`	`Contents of javax.faces.ViewState hidden field. This is included when jsf.getViewState is used.`
`javax.faces.partial.ajax`	`true`
`javax.faces.source`	`The identifier of the element that triggered this request.`

Collect optional post data arguments for the Ajax request.
- Determine additional arguments (if any) from the options argument. If options.execute exists:
  - If the keyword @none is present, do not create and send the post data argument javax.faces.partial.execute.
  - If the keyword @all is present, create the post data argument with the name javax.faces.partial.execute and the value @all.
  - Otherwise, there are specific identifiers that need to be sent. Create the post data argument with the name javax.faces.partial.execute and the value as a space delimited string of client identifiers.
- If options.execute does not exist, create the post data argument with the name javax.faces.partial.execute and the value as the identifier of the element that caused this request.
- If options.render exists:
  - If the keyword @none is present, do not create and send the post data argument javax.faces.partial.render.
  - If the keyword @all is present, create the post data argument with the name javax.faces.partial.render and the value @all.
  - Otherwise, there are specific identifiers that need to be sent. Create the post data argument with the name javax.faces.partial.render and the value as a space delimited string of client identifiers.
- If options.render does not exist do not create and send the post data argument javax.faces.partial.render.
- Determine additional arguments (if any) from the event argument. The following name/value pairs may be used from the event object:
  - target - the ID of the element that triggered the event.
  - captured - the ID of the element that captured the event.
  - type - the type of event (ex: onkeypress)
  - alt - true if ALT key was pressed.
  - ctrl - true if CTRL key was pressed.
  - shift - true if SHIFT key was pressed.
  - meta - true if META key was pressed.
  - right - true if right mouse button was pressed.
  - left - true if left mouse button was pressed.
  - keycode - the key code.
Encode the set of post data arguments.
Join the encoded view state with the encoded set of post data arguments to form the query string that will be sent to the server.
Create a request context object and set the properties:
- source (the source DOM element for this request)
- onerror (the error handler for this request)
- onevent (the event handler for this request)
The request context will be used during error/event handling.
Send a begin event following the procedure as outlined in the Chapter 13 "Sending Events" section of the spec prose document linked in the overview summary
Set the request header with the name: Faces-Request and the value: partial/ajax.


Determine the posting URL as follows: If the hidden field
javax.faces.encodedURL is present in the submitting form, use its
value as the posting URL.  Otherwise, use the action 
property of the form element as the URL.
Send the request as an asynchronous POST using the
posting URL that was determined in the previous step.


Before the request is sent it must be put into a queue to ensure requests
are sent in the same order as when they were initiated.  The request callback function
must examine the queue and determine the next request to be sent.  The behavior of the
request callback function must be as follows:

If the request completed successfully invoke jsf.ajax.response
passing the request object.
If the request did not complete successfully, notify the client.
Regardless of the outcome of the request (success or error) every request in the
queue must be handled.  Examine the status of each request in the queue starting from
the request that has been in the queue the longest.  If the status of the request is
complete (readyState 4), dequeue the request (remove it from the queue).
If the request has not been sent (readyState 0), send the request.  Requests that are
taken off the queue and sent should not be put back on the queue.


					
					
					
						
							
							Parameters:
							
								
									source
									
								
								The DOM element that triggered this Ajax request, or an id string of the
element to use as the triggering element.
							
								
									event
									
								
								The DOM event that triggered this Ajax request.  The
event argument is optional.
							
								
									options
									
								
								The set of available options that can be sent as
request parameters to control client and/or server side
request processing. Acceptable name/value pair options are:


name
value


execute
space seperated list of client identifiers


render
space seperated list of client identifiers


onevent
function to callback for event


onerror
function to callback for error


params
object containing parameters to include in the request


The options argument is optional.
							
							
						
						
						
						
							
							Throws:
							
								
									 
								
								ArgNotSet Error if first required argument element is not specified
							
							
						
						
						
						

					
				
					 
					<static> 
					
					
					jsf.ajax.response(request, context)
					
					
					
						Receive an Ajax response from the server.
Usage:

jsf.ajax.response(request, context);

Implementation Requirements:
This function must evaluate the markup returned in the
request.responseXML object and perform the following action:

If there is no XML response returned, signal an emptyResponse
error. If the XML response does not follow the format as outlined
in Appendix A of the spec prose document linked in the
 overview summary signal a malformedError error.  Refer to
section "Signaling Errors" in Chapter 13 of the spec prose document linked in the
 overview summary.
If the response was successfully processed, send a success
event as outlined in Chapter 13 "Sending Events" section of the spec prose
document linked in the
overview summary.
Update Element Processing
If an update element is found in the response
with the identifier javax.faces.ViewRoot:
<update id="javax.faces.ViewRoot">
   <![CDATA[...]]>
</update>
Update the entire DOM replacing the appropriate head and/or
body sections with the content from the response. 
If an update element is found in the response with the identifier
javax.faces.ViewState:
<update id="javax.faces.ViewState">
   <![CDATA[...]]>
</update>
locate and update the submitting form's javax.faces.ViewState value
with the CDATA contents from the response. 
If an update element is found in the response with the identifier
javax.faces.ViewHead:
<update id="javax.faces.ViewHead">
   <![CDATA[...]]>
</update>
update the document's head section with the CDATA 
contents from the response.
If an update element is found in the response with the identifier
javax.faces.ViewBody:
<update id="javax.faces.ViewBody">
   <![CDATA[...]]>
</update>
update the document's body section with the CDATA 
contents from the response.
For any other <update> element:
<update id="update id">
   <![CDATA[...]]>
</update>
Find the DOM element with the identifier that matches the
<update> element identifier, and replace its contents with
the <update> element's CDATA contents.

Insert Element Processing
If an <insert> element is found in the response with the
attribute before:
<insert id="insert id" before="before id">
   <![CDATA[...]]>
</insert>

Extract this <insert> element's CDATA contents
from the response.
Find the DOM element whose identifier matches before id and insert
the <insert> element's CDATA content before
the DOM element in the document.


If an <insert> element is found in the response with the
attribute after:
<insert id="insert id" after="after id">
   <![CDATA[...]]>
</insert>

Extract this <insert> element's CDATA contents
from the response.
Find the DOM element whose identifier matches after id and insert
the <insert> element's CDATA content after
the DOM element in the document.


Delete Element Processing
If a <delete> element is found in the response:
<delete id="delete id"/>
Find the DOM element whose identifier matches delete id and remove it
from the DOM.
Element Attribute Update Processing
If an <attributes> element is found in the response:
<attributes id="id of element with attribute">
   <attribute name="attribute name" value="attribute value">
   ...
</attributes>

Find the DOM element that matches the <attributes> identifier.
For each nested <attribute> element in <attribute>,
update the DOM element attribute value (whose name matches attribute name),
with attribute value.


JavaScript Processing
If an <eval> element is found in the response:
<eval>
   <![CDATA[...JavaScript...]]>
</eval>

Extract this <eval> element's CDATA contents
from the response and execute it as if it were JavaScript code.


Redirect Processing
If a <redirect> element is found in the response:
<redirect url="redirect url"/>
Cause a redirect to the url redirect url.
Error Processing
If an <error> element is found in the response:
<error>
   <error-name>..fully qualified class name string...<error-name>
   <error-message><![CDATA[...]]><error-message>
</error>
Extract this <error> element's error-name contents
and the error-message contents. Signal a serverError passing
the errorName and errorMessage.  Refer to
section "Signaling Errors" in Chapter 13 of the spec prose document linked in the
 overview summary.
Extensions
The <extensions> element provides a way for framework
implementations to provide their own information.



						
						
					
					
					
					
						
							
							Parameters:
							
								
									request
									
								
								The XMLHttpRequest instance that
contains the status code and response message from the server.
							
								
									context
									
								
								An object containing the request context, including the following properties:
the source element, per call onerror callback function, and per call onevent callback function.
							
							
						
						
						
						
							
							Throws:
							
								
									 
								
								EmptyResponse error if request contains no data

name	value
`execute`	`space seperated list of client identifiers`
`render`	`space seperated list of client identifiers`
`onevent`	`function to callback for event`
`onerror`	`function to callback for error`
`params`	`object containing parameters to include in the request`

Classes

Namespace jsf.ajax