Namespace jsf.ajax
The namespace for Ajax functionality.
Defined in: jsf.js.
Constructor Attributes | Constructor Name and Description |
---|---|
The namespace for Ajax functionality.
|
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. |
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 invokingjsf.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
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 invokingjsf.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
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:- Capture the element that triggered this Ajax request
(from the
source
argument, also known as thesource
element. - If the
source
element isnull
orundefined
throw an error. - If the
source
argument is not astring
or DOM element object, throw an error. - If the
source
argument is astring
, find the DOM element for thatstring
identifier. - If the DOM element could not be determined, throw an error.
- If the
onerror
andonevent
arguments are set, they must be functions, or throw an error. - Determine the
source
element'sform
element. - Get the
form
view state by calling jsf.viewState passing theform
element as the argument. - Collect post data arguments for the Ajax request.
- The following name/value pairs are required post data arguments:
javax.faces.partial.source
with the value as the source element identifier.- The name and value of the
source
element that triggered this request; javax.faces.partial.ajax
with the valuetrue
- The following name/value pairs are required post data arguments:
- Collect optional post data arguments for the Ajax request.
- Determine additional arguments (if any) from the
options
argument. Ifoptions.execute
exists, create the post data argument with the namejavax.faces.partial.execute
and the value as a space delimitedstring
of client identifiers. Ifoptions.render
exists, create the post data argument with the namejavax.faces.partial.render
and the value as a space delimitedstring
of client identifiers. - Determine additional arguments (if any) from the
event
argument. The following name/value pairs may be used from theevent
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.
- Determine additional arguments (if any) from the
- 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)
- 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 - Send the request as an
asynchronous POST
using theaction
property of theform
element as theurl
.
- 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
options
argument is optional.
- Throws:
- ArgNotSet Error if first required argument
element
is not specified
Receive an Ajax response from the server.
Usage:
jsf.ajax.response(request, context);
Implementation Requirements:
This function must evaluate the markup returned in therequest.responseXML
object and perform the following action:
- If an
update
element is found in the response with the identifierjavax.faces.ViewRoot
:
Update the entire DOM as follows:<update id="javax.faces.ViewRoot"> <![CDATA[...]]> </update>
- Extract the
CDATA
content and trim the <html> and </html> from theCDATA
content if it is present. - If the
CDATA
content contains a <head> element, and the document has a<head>
section, extract the contents of the <head> element from the<update>
element'sCDATA
content and replace the document's <head> section with this contents. - If the
CDATA
content contains a <body> element, and the document has a<body>
section, extract the contents of the <body> element from the<update>
element'sCDATA
content and replace the document's <body> section with this contents. - If the
CDATA
content does not contain a <body> element, replace the document's <body> section with theCDATA
contents.
- Extract the
- If an
update
element is found in the response with the identifierjavax.faces.ViewState
:
Include this<update id="javax.faces.ViewState"> <![CDATA[...]]> </update>
state
in the document as follows:- Extract this
<update>
element'sCDATA
contents from the response. - If the document contains an element with the identifier
javax.faces.ViewState
replace its contents with theCDATA
contents. - For each
<form>
element in the document:- If the
<form>
element contains an<input>
element with the identifierjavax.faces.ViewState
, replace the<input>
element contents with the<update>
element'sCDATA
contents. - If the
<form>
element does not contain an element with the identifierjavax.faces.ViewState
, create an<input>
element of the typehidden
, with the identifierjavax.faces.ViewState
, set its contents to the<update>
element'sCDATA
contents, and add the<input>
element as a child to the<form>
element.
- If the
- Extract this
- For any other
<update>
element:
Find the DOM element with the identifier that matches the<update id="update id"> <![CDATA[...]]> </update>
<update>
element identifier, and replace its contents with the<update>
element'sCDATA
contents. - If an
<insert>
element is found in the response with the attributebefore
:<insert id="insert id" before="before id"> <![CDATA[...]]> </insert>
- Extract this
<insert>
element'sCDATA
contents from the response. - Find the DOM element whose identifier matches
before id
and insert the<insert>
element'sCDATA
content before the DOM element in the document.
- Extract this
- If an
<insert>
element is found in the response with the attributeafter
:<insert id="insert id" after="after id"> <![CDATA[...]]> </insert>
- Extract this
<insert>
element'sCDATA
contents from the response. - Find the DOM element whose identifier matches
after id
and insert the<insert>
element'sCDATA
content after the DOM element in the document.
- Extract this
- If a
<delete>
element is found in the response:
Find the DOM element whose identifier matches<delete id="delete id"/>
delete id
and remove it from the DOM. - 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 matchesattribute name
), withattribute value
.
- Find the DOM element that matches the
- If an
<eval>
element is found in the response:<eval> <![CDATA[...JavaScript...]]> </eval>
- Extract this
<eval>
element'sCDATA
contents from the response and execute it as if it were JavaScript code.
- Extract this
- If a
<redirect>
element is found in the response:
Cause a redirect to the url<redirect url="redirect url"/>
redirect url
. - If an
<error>
element is found in the response:
Extract this<error> <error-name>..fully qualified class name string...<error-name> <error-message><![CDATA[...]]><error-message> </error>
<error>
element'serror-name
contents and theerror-message
contents. Signal aserverError
passing theerrorName
anderrorMessage
. Refer to section "Signaling Errors" in Chapter 13 of the spec prose document linked in the overview summary. - The
<extensions>
element provides a way for framework implementations to provide their own information.
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
Insert Element Processing
Delete Element Processing
Element Attribute Update Processing
JavaScript Processing
Redirect Processing
Error Processing
Extensions
- 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