Function request

Send an asynchronous Ajax request to the server.

Usage:

Example showing all optional arguments:

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

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 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 jakarta.faces.ViewState element could not be found, throw an error.
• If the ID of the jakarta.faces.ViewState element has a <VIEW_ROOT_CONTAINER_CLIENT_ID><SEP> prefix, where <SEP> is the currently configured UINamingContainer.getSeparatorChar() and <VIEW_ROOT_CONTAINER_CLIENT_ID> is the return from UIViewRoot.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 form element.
• Get the form view state by calling faces.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
    jakarta.faces.ViewState	Contents of jakarta.faces.ViewState hidden field.This is included when faces.getViewState is used.
    jakarta.faces.partial.ajax	true
    jakarta.faces.source	The identifier of the element that triggered this request.
    jakarta.faces.ClientWindow	Call faces.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 options argument. If options.execute exists:
    • If the keyword @none is present, do not create and send the post data argument jakarta.faces.partial.execute.
    • If the keyword @all is present, create the post data argument with the name jakarta.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 jakarta.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 jakarta.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 jakarta.faces.partial.render.
    • If the keyword @all is present, create the post data argument with the name jakarta.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 jakarta.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 jakarta.faces.partial.render.
  • If options.delay exists let it be the value delay, for this discussion. If options.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.
  • If options.resetValues exists and its value is true, ensure a post data argument with the name jakarta.faces.partial.resetValues and the value true is sent in addition to the other post data arguments. This will cause UIViewRoot.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 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. If the jakarta.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 Jakarta Faces Specification Document section 13.3.5.3 "Sending Events".
• Set the request header with the name: Faces-Request and the value: partial/ajax.
• Determine the posting URL as follows: If the hidden field jakarta.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.

• Determine whether or not the submitting form is using multipart/form-data as its enctype attribute. If not, send the request as an asynchronous POST using the posting 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 use XMLHttpRequest, but the request must be sent with all the parameters that a Faces XMLHttpRequest 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, and success events must be emulated when using the multipart transport. This allows any listeners to behave uniformly regardless of the multipart or XMLHttpRequest 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 faces.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.