serverpost
| resources: | Home Mailing List Installation Specification Testcases Source Code Members Bugs |
|---|
Specification
The <http:serverpost/> element specification (First draft)
Note: This document is in its very early stages and subject to revision or complete replacement. Any feedback you have whatsoever would be greatly appreciated.
The <http:serverpost/> element defined here is a conveinience widget for applications processing XML documents to submit form controls to a server and receive a response, without replacing the entire document. The element does not require the XML document to use a particular namespace for its form control elements, but instead uses a specific attribute to designate an XML element as a form control associated with a particular <http:serverpost/> element.
The http: namespace URI
This specification uses the namespace "http://serverpost.mozdev.org/namespaces/serverpost/" to indicate all elements and attributes within the http: namespace.
The <http:serverpost/> element
The <http:serverpost/> element is an XML element to process all form controls within its document associated with that <http:serverpost/> element. An element may be associated with an <http:serverpost/> element as a form control using an http:serverpostnames attribute.
The <http:serverpost/> element requires an id attribute which is unique to the document. The application uses this in the http:serverpostnames attributes to identify which form controls go to which elements.
Each <http:serverpost/> element, by its id attribute, identifies a set of form controls for submission to the server. A XML element is within that set if its http:serverpostnames attribute contains that id attribute's value, bordered by no characters other than whitespace on either side.
The <http:serverpost/> element's type attribute specifies the content-type of the HTTP request message it will submit to the server. The type attribute, thusly, also specifies how the <http:serverpost/> element must compose the message.
The <http:serverpost/> element's targetURL attribute specifies the URI the element shall submit the HTTP request message to.
The <http:serverpost/> element must support event handlers for the following events: HTTPResponseReceived, HTTPResponseError, error.
The http:serverpostnames attribute
The http:serverpostnames attribute associates an XML element acting as a form control with at least one <http:serverpost/> element. The attribute's value is a whitespace-separated list of XML names, each of which corresponds to an id attribute of a <http:serverpost/> element within the document.
Form controls
Form controls may be any XML element possessing a http:serverpostnames attribute and an DOM-compatible method named getSuccessfulFormControls. The getSuccessfulFormControls() method must return an ECMAScript-compatible array of objects. Each object in the returned array must have a name property and a value property.
A successful form control is one where a valid name=value relationship exists. It must be submitted, pending no exceptions being thrown by the client and acceptance by the <http:serverpost/> element.
A disabled form control must not be submitted or processed, nor may it be the basis for throwing an exception or stopping a submission. Disabled form controls may or may not have a valid name=value relationship; the fact that it is disabled takes precedence. Elements may signify their form controls are disabled to the <http:serverpost/> element processing form controls by using a disabled="true" attribute with a null namespace or the http: namespace.
A failed form control is one where no valid name=value relationship exists. It must not be submitted or processed, and must be the basis for immediately throwing an exception and stopping a <http:serverpost/> element's submission to a server.
Why use http:serverpost and http:serverpostnames?
Current specifications for actually specifying certain elements as form controls require an element be within the XHTML namespace, "http://www.w3.org/1999/xhtml". This precludes elements from other XML namespaces, such as the Mozilla Foundation's XUL, "http://www.mozilla.org/gatekeeper/keymaster/there.is.only.xul", from having custom methods and properties for submitting information to a server.
By using an attribute in a foreign namespace, any XML element can be identified as a source of information for submitting to a server for processing. This has advantages when you consider several XML languages which already have implementations may also have information to convey to a server. The Mozilla Foundation's XUL language is one particularly obvious example, although the appearance of controls could be written in SVG, with ECMAScript providing the necessary code to create the form controls submitted.
The element can submit several pieces of information (for example, a select-multiple element from HTML sends several values for a given form control name), based on its getSuccessfulFormControls() method. The element can submit that information to several different locations, or to the same location under different configurations, based on the id attribute references to various <http:serverpost/> elements.
Protocols for submission
The <http:serverpost/> element uses the HTTP POST method to send HTTP request messages to the server, containing the form controls in an appropriate encoding. The encoding is determined by the <http:serverpost/> element's type attribute. Implementations of this element must support "application/x-www-form-urlencoded" as the default content-type. HTML 4.01 defines this format. Implementations of this element must also support "multipart/form-data" as a possible type, in order to support internationalization, file uploads, etc. RFC 2388 defines the "multipart/form-data" content-type and its implementation. Other content-types (such as application/soap+xml) are optional.
Document Object Model Events
The <http:serverpost/> element must listen for four events targeted at it, the submit and error events (as defined by DOM 2 Events), the HTTPResponseReceived event, and the HTTPResponseError event.
HTTPResponseReceived: Designates when the HTTP server has successfully received the message and returned a response to the <http:serverpost/> element.
Type: MutationEvents
Bubbles: Yes
Cancelable: No
HTTPResponseError: Designates when the HTTP server returns an HTTP error code to the <http:serverpost/> element.
Type: MutationEvents
Bubbles: Yes
Cancelable: No
The appropriate event handlers are named onsubmit, onerror, onHTTPResponseReceived, and onHTTPResponseError, respectively.
Error processing
Errors can happen at two stages of the <http:serverpost/> element's processing: in collecting and processing the form controls for submission (client-side), or in the HTTP server's processing the submitted HTTP request message and responding (server-side).
Upon a client-side exception being thrown by a XML element identified as a form control, the <http:serverpost/> element must immediately stop all processing of form controls and, if possible, dispatch an error event as defined in DOM Level 2 Events. The <http:serverpost/> element must not submit the form controls it has already collected to the server. Any failed form control must trigger an exception.
Upon a server-side error, the server will likely return either a HTTP error code (for example, 404 Not Found) or an HTTP response message with details of the error as the content of the message. If a HTTP error code is received by the <http:serverpost/> element's implementation, the <http:serverpost/> must dispatch a HTTPResponseError event.
This specification does not currently deal with server-side errors which are not HTTP errors (for example, PHP syntax errors). That responsibility lies with the XML document or application containing the <http:serverpost/> element. A future draft of this specification may define other elements in the http: namespace for conveying error messages to the application (for example, if the server's target URL does not receive well-formed form controls from the HTTP server as a result of a <http:serverpost/> element misconfiguring the HTTP request message.)
ECMAScript properties and methods of the <http:serverpost/> element
id The id attribute of the <http:serverpost/> element.
requester The actual object which submits HTTP messages to the server and
receives HTTP responses.
targetURL The targetURL attribute of the <http:serverpost/> element. Indicates
the URL which the element's requester will submit information to.
submit() The method called to start a submission of form controls to the server.
abort() Cancels any submission to the server if not yet sent, or the
expectation of a response if the HTTP request message has been sent.
getHTTPMessageObj() Returns an object containing the body of the document and specific
HTTP headers to set on the requester.
The following properties are all null if the <http:serverpost/> element's requester has submitted a HTTP request message but has not received a HTTP response message in reply.
responseText The text of the HTTP response message after receipt.
responseXML An XML document node corresponding to the responseText property after
being parsed by the application. May be null if the responseText property's
contents are not a well-formed XML document.
responseHeaders A collection of headers from the HTTP response message rec4eived by the
<http:serverpost/> element's requester.
status The HTTP response message's HTTP status code.
statusText The HTTP response message's HTTP status text.
File processing and internationalization
The application/x-www-form-urlencoded content-type is not suitable for submitting any form controls whose names or values are outside the ASCII character set. Likewise, it is not suitable for submitting a file. The <http:serverpost/> element, if its type attribute is not explicitly set to some value other than "application/x-www-form-urlencoded" and if it detects an invalid character or a file upload, must throw an exception and cancel the submission of the form. The exception thrown must indicate to the application a need for an alternate content-type which the <http:serverpost/> element supports.
The multipart/form-data content-type can correctly handle files and characters outside the ASCII character set, so it is not subject to these restrictions or this exception.