The
<tree class="widgettree"
is a addon, not a formwidget.
To use it, you need to include WidgetTree.css in your source as well.
It allows you to edit the contents
of a treecell in a tree by doubleclicking on it. It only works for
contenttrees.
It should at least have
one
<treewidgets
element, inside the tree tag, after the
treechildren, like this:
...
...
...
The treewidgets element shows up as a toolbar
at the bottom of the tree. If you doubleclick a cell,
a formwidget - by default a textbox - appears in the toolbar.
This formwidget is used to edit the content of the selected cell.
In a widgettree, a treecell has attributes
value
and
label
. treecol elements has a
name
attribute.
The treecols name and the treecell's value and label combine into
one 'seed' which is fed to the formwidget.
In a treecell, only the label is displayed, as usual,
but if you specify
<tree showvalues="true"
, the new value of a
cell (after editing) is displayed as part of the new label.
custom formwidgets
You can add you own formwidgets inside the
<treewidgets
element.
You specify which widget to use for a column with the
<treecol widget="mywidget""
attribute on
the column definition.
The widget should be a real formwidget, that implements
harvest
and
seed
as explained in the
chapter
harvest and seed.
If you want it to except values for several columns with
different names, don't give the widget a name, so it will except
any incoming seed.
toolbar behaviour
By default, a blank toolbar is visible if the tree is inactive.
If you set
<treewidgets inactive="hidden"
, the
toolbar will appear only when necessary.
If you specify
<treewidgets inactive="mywidget"
,
the widget with id "mywidget" will appear when the treewidgets
element is inactive.
treecol attributes
As noted, widgettree treecols have some extra attributes like
name
and
widget
. The
isindex
attribute defines if a treecol is treated as an 'index column' during harvest.
And if a widget returns more than one 'seed' (like a checkgroup), the treecol attributes
valueseparator
and
labelseparator
define
how the seeds are stored in the treecell.
For backwards compatibility, the
id
attribute is required for widgettree columns,
even in 1.8> versions of mozilla.
onsave sequence
After you hit the "save" button in the toolbar, the tree will try to update
the selected cell's contents. It takes a few steps:
The active widget is harvested
into a bucket as explained in the chapter
harvest and seed.
Some usefull additional seeds are added to the bucket: if there is a indexcolumn in your tree,
a seed with your seeds name plus ".id" is added, with the value of the indexcolumn for the selected row.
a seed with your seeds name plus ".org" is also added,
with the original (previous) value and label of the selected cell.
The bucket is then sent to a handler specified by the
<treewidgets onsave="blah
attribute.
If the method exists and returns false, submission is cancelled.
Otherwise, submission continues
with the bucket, which may have been altered by the handler.
After the onsave handler is called, the tree searches the treewidgets
element for a
formbutton.
if it finds one, it uses that to send the current bucket through HTTP to a server.
If the send action is sync and returns an error, submission is cancelled. Otherwise,
submission continues.
Finally, the selected cell's contents are updated with the leftovers from your
bucket.
Example:
Tree
Additional Attributes:
showvalues
if "true", updated values are shown in brackets in the label of the treecell
Additional Properties:
editing
readonly. true when editing.
Additional Methods:
-
edit(rownumber,columnelement)
selects cell with rownumber and columnelement and starts editing session.
for backwards compatibilty, the columns xulelement is passed, not the column object.
-
cancel()
stops editing session for currently selected cell
-
setCell(value,label)
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.
TreeCol
Required Attributes:
id
a unique id in the document's scope
Additional Attributes:
name
the name of a seed for any cell in this column
widget
the id of the widget used to edit cell in this column with.
by default, an anonymous textbox appears
isindex
if this attributes exists, the treecol is taken to be
an index column. index column's seeds are added to he bucket
during the onsave sequence. if there is no index column,
the primary column is used. if there is no primary
column, no seeds are added.
valueseparator
string used to seperate an array of values from a widget
that returns multiple seeds (like a checkgroup)
labelseparator
string used to seperate an array of labels from a widget
that returns multiple seeds (like a checkgroup)
TreeCell
Additional Attributes:
value
the value of a seed generated from this cell. it is used
for all types of cells.
Additional CellProperties:
readonly
on a <treecell properties="readonly"
, doubleclicking
it is disabled. CSS greys the cell out and removes the cursor.
editing
when a cell is selected and a widget activated, the
<treecell properties="editing"
is added, mainly for CSS.
TreeWidgets
Attributes:
inactive
the id of the widget to show when the tree is inactive.
inactive="hidden" hides the widget toolbar when inactive.
onsave
pseudo event handler. triggered when the widget is submitted.
receives a bucket with the results from the widgets plus a
few extra seeds. if it returns false, submission is canceled,
otherwise submission continues with the bucket, which may have
been altered by the handler.
Methods:
edit(widgetid,name,value,label)
starts an editing session with the given widget, seeding
it with the value and label. if the currently selected col
has value- and labelseparators, the label and
value are separated into multiple seeds first.
save()
saves the currently active widget. calls onsave() first,
then calls send(), then updates the tree, then
closes everything.
cancel()
cancels the currently active widget. old values are retained.
send(bucket)
searches a formbutton in the widgettree. tries to send
the bucket with that formbutton.