The <http:serverpost/> element specification (First draft)

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.

1. The http: namespace URI

This specification uses the namespace "http://www.mozilla.org/xmlextras/" to indicate all elements and attributes 
within the http: namespace.

2. 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.  An
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.

3. 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.

4. 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.

5. 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.

6. 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.

7. 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.

8. 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.)

9. 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.

10. 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.

11. Proposed implementation of <http:serverpost/> in Mozilla Application Suite

A proposed implementation of <http:serverpost/> is available as a patch for the Mozilla Application Suite via
http://bugzilla.mozilla.org/show_bug.cgi?id=231833 .  Note that at the time of this specification's writing
(Feb. 12, 2004), there are some inconsistencies between the patch dated Feb. 01, 2004 and this specification.