A <button class="formbutton" is the most complicated element.
It has a method submit()
to which you can pass an arbitrary xul element; the button will recurse
down the element and harvest all the queries from input elements,
generate a query, send a form. The submit() method always returns a XMLHttpRequest in action.
For more information, see http://www.xulplanet.com/references/objref/XMLHttpRequest.html
You may define event handlers like <button onresult="bla"
and <button onerror="bla".
These event handlers receive the request object.
If sync is true (<button class="formbutton" sync="true"),
the default, the request is send
in "sync". You can't do anything (but wait) until the result is received.
There can only be one active
synced request on a button; the synced request is set as a property on the button.
Some properties of the synced request are also set as attributes on the button so you can
observe them. You can use button.abort() to abort a synced request.
The name of the variable used for this element in the HTTP query
value
The value of the variable used for this element in the HTTP query
action
the url to use for the request
username
the username to use for the request
password
the password to use for the request
forcemime
used for XMLHttpRequest.overrideMimeType(). ignores the mimetype
the server returns in the response headers. Instead the value of this
attribute is taken to be the correct mimetype. Usefull for badly
configured servers.
method
the method to use for the request, e.g. POST or GET
sync
boolean. wether or not to sync the request. there can only be one synced
request on any button; the request and some other parameters are set as
attributes on the button. if sync=false, you will have to handle the
xmlhttprequest that is returned from the submit() method yourself.
extendedcgi
boolean. wether or not to add the value of labels (and other optional
seed properties) to the cgi querystring. if this is true, a cgistring
like "amount=3" might turn into "amount=3&amount.label=Three"
readyState
integer. when sync=true, reflects the readystate of the most recent request
status
integer. when sync=true, reflects the status code of the most recent request
statusText
string. when sync=true, reflects the status text of the most recent request
responseText
string. when sync=true, reflects the response of the most recent request
progress
integer. when sync=true, reflects the progress of the most recent request
in %, which is usefull for progressbars. you can have a progressbar observe this property.
onstate
pseudo event handler. should point to a method to execute
when an onState event occurs. the method will receive the XMLHttpRequest
as its only parameter
onprogress
pseudo event handler. should point to a method to execute
when an onprogress event occurs. the method will receive the XMLHttpRequest
as its only parameter
onresult
pseudo event handler. should point to a method to execute
when an onresult event occurs. the method will receive the XMLHttpRequest
as its only parameter
onerror
pseudo event handler. should point to a method to execute
when an onerror event occurs. the method will receive the XMLHttpRequest
as its only parameter
onvalidate
pseudo event handler. should point to a method to execute
for validation. when validating, the method will receive a bucket
with all seeds of all harvested elements. if onvalidate returns
false, the bucket is emptied and processing canceled.
Additional Properties:
request
readonly, XMLHttpRequest. only set when sync=true. some properties
(status,readyState etc) are mirrored in the attributes of the same name
active
readonly, boolean. true while a request is pending.
Additional Methods:
submit(XULElement)
performs harvestCGI with the given XULElement and
performs a send with the result. returns the request object
or null if there is nothing to submit.
harvestCGI(XULElement)
Performs harvest with the given XULElement
passes the bucket to bucket2cgi
harvestForm(XULElement)
creates an empty bucket, adds its own seed,
traverses the XML Dom starting at
XULElement and calls harvest() with the bucket
on each formwidget it finds. In the end, calls
validation and returns a full bucket if it validates,
an empty bucket if it doesn't.
See Harvest and Seed.
seedForm(XULElement,bucket)
traverses the XML Dom starting at XULElement and calls
seed() with the bucket on each formwidget it finds.
in the end, adds its own seed and returns the bucket.
See Harvest and Seed.
send(body)
pass the given body to a XMLHttpRequest, using the various
attributes at settings. aborts any active synced request.
returns the request object.
abort()
abort an active request.
validate(bucket)
executes the method specified in onvalidate
bucket2cgi(bucket)
transforms a bucket to a CGI Query string
bucket2string(bucket)
transforms a bucket to a string. usefull for debugging.