JsDoc Reference - jsf.ajax (original) (raw)

Namespace jsf.ajax

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

Namespace Summary

Method Summary

Namespace Detail

jsf.ajax

The namespace for Ajax functionality.

Method Detail

jsf.ajax.addOnError(callback)

Register a callback for error handling.

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.addOnErrormore than once. This function must throw an error if the callbackargument is not a function.

Parameters:

callback

a reference to a function to call on an error

jsf.ajax.addOnEvent(callback)

Register a callback for event handling.

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.addOnEventmore than once. This function must throw an error if the callbackargument is not a function.

Parameters:

callback

a reference to a function to call on an event

jsf.ajax.request(source, event, options)

Send an asynchronous Ajax req uest 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, else throw an error.
• Capture the element that triggered this Ajax request (from the source argument, also known as thesource element.
• If the source element is null orundefined 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 javax.faces.ViewStateelement could not be found, throw an error.
• If the ID of the javax.faces.ViewStateelement has a <VIEW_ROOT_CONTAINER_CLIENT_ID><SEP>prefix, where is the currently configuredUINamingContainer.getSeparatorChar() and <VIEW_ROOT_CONTAINER_CLIENT_ID> is the return fromUIViewRoot.getContainerClientId() on the view from whence this state originated, then remember it as namespace prefix. This is needed during encoding of the set of post data arguments.
• If the onerror and onevent arguments are set, they must be functions, or throw an error.
• Determine the source element's formelement.
• Get the form view state by callingjsf.getViewState passing theform 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 whenjsf.getViewState is used.
    javax.faces.partial.ajax	true
    javax.faces.source	The identifier of the element that triggered this request.
    javax.faces.ClientWindow	Call jsf.getClientWindow(), passing the current form. If the return is non-null, it must be set as the value of this name/value pair, otherwise, a name/value pair for client window must not be sent.

• Collect optional post data arguments for the Ajax request.
  • Determine additional arguments (if any) from the optionsargument. 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.
  • Ifoptions.delay exists let it be the value_delay_, for this discussion. Ifoptions.delay does not exist, or is the literal string 'none', without the quotes, no delay is used. If less than _delay_milliseconds elapses between calls to _request()_only the most recent one is sent and all other requests are discarded.
  • Ifoptions.resetValues exists and its value istrue, ensure a post data argument with the name javax.faces.partial.resetValues and the value true is sent in addition to the other post data arguments. This will causeUIViewRoot.resetValues() to be called, passing the value of the "render" attribute. Note: do not use any of the @ keywords such as@form or @this with this option because UIViewRoot.resetValues() does not descend into the children of the listed components.
  • Determine additional arguments (if any) from the eventargument. 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.
• Encode the set of post data arguments. If the javax.faces.ViewState element has a namespace prefix, then make sure that all post data arguments are prefixed with this namespace prefix.
• 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 fieldjavax.faces.encodedURL is present in the submitting form, use its value as the posting URL. Otherwise, use the actionproperty of the form element as the URL.
• Determine whether or not the submitting form is using multipart/form-data as itsenctype attribute. If not, send the request as an asynchronous POST using theposting URL that was determined in the previous step. Otherwise, send the request using a multi-part capable transport layer, such as a hidden inline frame. Note that using a hidden inline frame does not useXMLHttpRequest, but the request must be sent with all the parameters that a JSFXMLHttpRequest would have been sent with. In this way, the server side processing of the request will be identical whether or the request is multipart or not.
  The begin, complete, andsuccess events must be emulated when using the multipart transport. This allows any listeners to behave uniformly regardless of the multipart orXMLHttpRequest nature of the transport.

Form serialization should occur just before the request is sent to minimize the amount of time between the creation of the serialized form data and the sending of the serialized form data (in the case of long requests in the queue). 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.responsepassing 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 iscomplete (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. Theevent 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:

The options argument is optional.

Throws:

Error if first required argumentelement is not specified, or if one or more of the components in the options.executelist is a file upload component, but the form's enctype is not set to multipart/form-data

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 therequest.responseXML object and perform the following action:

If there is no XML response returned, signal an emptyResponseerror. 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 successevent as outlined in Chapter 13 "Sending Events" section of the spec prose document linked in the overview summary.

Update Element Processing

The update element is used to update a single DOM element. The "id" attribute of the update element refers to the DOM element that will be updated. The contents of the CDATA section is the data that will be used when updating the contents of the DOM element as specified by the<update> element identifier.

• 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/orbody sections with the content from the response.

• If an<update> element is found in the response with an identifier containingjavax.faces.ViewState:

<update id="<VIEW_ROOT_CONTAINER_CLIENT_ID><SEP>javax.faces.ViewState<SEP><UNIQUE_PER_VIEW_NUMBER>">  
   <![CDATA[...]]>  
</update>  

locate and update the submitting form'sjavax.faces.ViewState value with theCDATA contents from the response. is the currently configuredUINamingContainer.getSeparatorChar(). <VIEW_ROOT_CONTAINER_CLIENT_ID> is the return fromUIViewRoot.getContainerClientId() on the view from whence this state originated. <UNIQUE_PER_VIEW_NUMBER> is a number that must be unique within this view, but must not be included in the view state. This requirement is simply to satisfy XML correctness in parity with what is done in the corresponding non-partial JSF view. Locate and update the javax.faces.ViewState value for all JSF forms covered in the render target list whose ID starts with the same <VIEW_ROOT_CONTAINER_CLIENT_ID> value.

• If anupdate element is found in the response with an identifier containingjavax.faces.ClientWindow:

<update id="<VIEW_ROOT_CONTAINER_CLIENT_ID><SEP>javax.faces.ClientWindow<SEP><UNIQUE_PER_VIEW_NUMBER>">  
   <![CDATA[...]]>  
</update>  

locate and update the submitting form'sjavax.faces.ClientWindow value with theCDATA contents from the response. is the currently configuredUINamingContainer.getSeparatorChar(). <VIEW_ROOT_CONTAINER_CLIENT_ID> is the return fromUIViewRoot.getContainerClientId() on the view from whence this state originated. <UNIQUE_PER_VIEW_NUMBER> is a number that must be unique within this view, but must not be included in the view state. This requirement is simply to satisfy XML correctness in parity with what is done in the corresponding non-partial JSF view. Locate and update the javax.faces.ClientWindow value for all JSF forms covered in the render target list whose ID starts with the same <VIEW_ROOT_CONTAINER_CLIENT_ID> value.

• If an update element is found in the response with the identifier javax.faces.Resource:

<update id="javax.faces.Resource">  
   <![CDATA[...]]>  
</update>  

append any element found in the CDATA contents which is absent in the document to the document's head section.

• If an update element is found in the response with the identifierjavax.faces.ViewHead:

<update id="javax.faces.ViewHead">  
   <![CDATA[...]]>  
</update>  

update the document's head section with the CDATAcontents from the response.

• If an update element is found in the response with the identifierjavax.faces.ViewBody:

<update id="javax.faces.ViewBody">  
   <![CDATA[...]]>  
</update>  

update the document's body section with the CDATAcontents 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 a nested <before>element:

<insert>  
    <before id="before id">  
       <![CDATA[...]]>  
    </before>  
</insert>  

• Extract this <before> element's CDATA contents from the response.
• Find the DOM element whose identifier matches before id and insert the <before> element's CDATA content before the DOM element in the document.
• If an <insert> element is found in the response with a nested <after>element:

<insert>  
    <after id="after id">  
       <![CDATA[...]]>  
    </after>  
</insert>  

• Extract this <after> element's CDATA contents from the response.
• Find the DOM element whose identifier matches after id and insert the <after> 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.
• The implementation must check if