Harvest and Seed
If you just want to use formwidgets, you can skip this section. If you want
to extend or create formwidgets, you should also read the xbl source. Below, I will
explain the general idea of harvest() and seed().
Every element of class formwidget has at least two methods:
harvest()
and seed()
. Both take an array of seeds
,
which I will call a bucket
, as input parameter. One seed
is
an object with three properties: name
, value
and label
.
A formwidget's harvest()
method examines the contents of the element and adds seeds
to the bucket
. Most elements only add one seed
, but some, like
multiple select listboxes, may add more.
A formwidget's seed()
method tries to do the reverse: it takes a
(filled) bucket
, and examines every seed
in it to see if it
matches the element, eg, if the "name" of the seed
matches
it's own "name" attribute. If it finds a match, it
changes the it's own value and/or label accordingly and removes the
seed from the bucket. But you can imagine the exact behaviour differs from element
to element, given the different nature of elements.
The formbutton
The formbutton's harvest()
method takes an additional XUL element
as parameter. It optionally creates an empty bucket
, and traverses the given
element recursively, down the XML dom. To every formwidget it finds,
It passes the bucket
and lets it
harvest()
itself. In the end, the bucket
contains 'the state of the form'
as an array of seeds.
The formbutton's seed()
method takes a XUL element
and a filled bucket
as parameter.It traverses the given
element recursively, down the XML dom.
It passes the bucket
to every formwidget it finds and lets it
seed()
itself. In the end, the bucket
might be empty.
Currently, when using the results of harvest()
for HTTP, the labels
are discarded. The query string is comprised of simple name/value pairs.
harvest!=inv(seed)
harvest()
and seed()
are not completely complementary:
if you harvest()
a 'form', store the bucket
,
and seed()
it later with the stored bucket
, the form
does not always return to its original state. In practice, there
are differences due to ambiguous use of label vs. value,
naming schemes, the behaviour of checkboxes, etc.