cocoon-docs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From da...@cocoon.zones.apache.org
Subject [DAISY] Updated: Tree widget
Date Thu, 04 May 2006 18:28:08 GMT
A document has been updated:

http://cocoon.zones.apache.org/daisy/documentation/739.html

Document ID: 739
Branch: main
Language: default
Name: Tree widget (unchanged)
Document Type: Cocoon Document (unchanged)
Updated on: 5/4/06 6:27:47 PM
Updated by: Bruno Dumon

A new version has been created, state: publish

Parts
=====
Content
-------
This part has been updated.
Mime type: text/xml (unchanged)
File name:  (unchanged)
Size: 6663 bytes (previous version: 43 bytes)
Content diff:
    <html>
    <body>
    
--- <p>TODO</p>
+++ <h1>Concept</h1>
    
+++ <p>The tree widget is for displaying trees of "things". The tree widget supports
+++ expanding and collapsing of nodes, single or multiple selections, and a flexible
+++ TreeModel interface to provide its data.</p>
+++ 
+++ <h1>Definition</h1>
+++ 
+++ <pre>&lt;fd:tree id="..." state="..." root-visible="true" selection="multiple|single"&gt;
+++   &lt;fd:tree-model type="..."/&gt;
+++   &lt;fd:on-selection-changed&gt;
+++    ...
+++   &lt;/fd:on-selection-changed&gt;
+++   &lt;fd:on-create&gt;
+++     ...
+++   &lt;/fd:on-create&gt;
+++   &lt;fd:validation&gt;
+++     ...
+++   &lt;/fd:validation&gt;
+++   &lt;fd:attributes&gt;
+++     ...
+++   &lt;/fd:attributes&gt;
+++ &lt;/fd:tree&gt;
+++ </pre>
+++ 
+++ <p>All elements and attributes, except for id, are optional.</p>
+++ 
+++ <p>See the <a href="daisy:481">field widget</a> for information on common
+++ attributes and elements.</p>
+++ 
+++ <h1>The tree model</h1>
+++ 
+++ <p>See the interface
+++ <a href="javadoc:org.apache.cocoon.forms.formmodel.tree.TreeModel">TreeModel</a>.
+++ Essentially, can be a tree of any sort of objects (there is no interface for the
+++ nodes in the tree). Each parent node should be able to identify its children
+++ uniquely by means of a key (some string).</p>
+++ 
+++ <p>CForms ships with two implementations of TreeModel: one generic
+++ implementation (DefaultTreeModel), and one for browsing over Cocoon/Avalon
+++ sources (= filesystem-like structures).</p>
+++ 
+++ <p>You can set the form model in the form definition, or set it at runtime using
+++ the setModel method on the tree widget.</p>
+++ 
+++ <h2>Source tree model</h2>
+++ 
+++ <p>Syntax:</p>
+++ 
+++ <pre>&lt;fd:tree-model type="source" src="..."&gt;
+++   &lt;fd:fileset&gt;
+++     &lt;fd:include pattern="..."/&gt;
+++     &lt;fd:exclude pattern="..."/&gt;
+++   &lt;/fd:fileset&gt;
+++   &lt;fd:dirset&gt;
+++     &lt;fd:include pattern="..."/&gt;
+++     &lt;fd:exclude pattern="..."/&gt;
+++   &lt;/fd:dirset&gt;
+++ &lt;/fd:tree-model&gt;
+++ </pre>
+++ 
+++ <p>The <tt>src</tt> attribute defines the root of the content to be
browsed. For
+++ example, to browse the content of the webapp directory, specify
+++ <tt>src="context://"</tt>. Of course, you can also use "file://" or other
+++ traversable sources [todo: link to some page with info about sources].</p>
+++ 
+++ <p>The <tt>fd:fileset</tt> and <tt>fd:dirset</tt> elements
are optional. The
+++ fileset patterns are used to filter files based on their name, and the dirset
+++ patterns are used to filter directories based on their names.</p>
+++ 
+++ <p>There can be multiple (or none at all) <tt>fd:include</tt> and
+++ <tt>fd:exclude</tt> elements inside <tt>fd:fileset</tt> or <tt>fd:dirset</tt>.
+++ The include patterns will be evaluated first, the exclude patterns next, so the
+++ exclude patterns have higher precendence.</p>
+++ 
+++ <p>The patterns are wildcard patterns. They are the same as for the wildcard
+++ matcher in the sitemap, thus simply use a * as wildcard (the ** syntax makes no
+++ sense here, as the pattern is evaluated on individual names, not on full paths).
+++ </p>
+++ 
+++ <h2>Custom models</h2>
+++ 
+++ <p>Syntax:</p>
+++ 
+++ <pre>&lt;fd:tree-model type="java" class="..."/&gt;
+++ </pre>
+++ 
+++ <p>whereby the class attribute specifies a class implementing
+++ <a href="javadoc:org.apache.cocoon.forms.formmodel.tree.TreeModel">TreeModel</a>.
+++ The class can implement Avalon interfaces to get the Logger, ServiceManager and
+++ Context.</p>
+++ 
+++ <h2>Programmatically assigning a model</h2>
+++ 
+++ <p>Here's an example of how to build a tree model programatically using the
+++ provided DefaultTreeModel in flowscript:</p>
+++ 
+++ <pre>importClass(Packages.org.apache.cocoon.forms.formmodel.tree.DefaultTreeModel);
+++ 
+++ [...]
+++ 
+++ var node1 = new DefaultTreeModel.DefaultTreeNode("node 1")
+++ var node2 = new DefaultTreeModel.DefaultTreeNode("node 2")
+++ var root = new DefaultTreeModel.DefaultTreeNode("root")
+++ root.add("node1", node1);
+++ node1.add("node2", node2);
+++ var treeModel = new DefaultTreeModel(root);
+++ 
+++ var treeWidget = form.getChild("mytree");
+++ treeWidget.setModel(treeModel);
+++ </pre>
+++ 
+++ <h1>Template</h1>
+++ 
+++ <p>For the display of a tree widget, three special template elements are
+++ available:</p>
+++ 
+++ <ul>
+++ <li><tt>ft:tree</tt>: global element to insert a tree widget in the
template.
+++ This also inserts two hidden fields, ":path" and ":action" to communicate a node
+++ action to the server, see below.</li>
+++ <li><tt>ft:tree-nodes</tt>: the template to be executed for each tree
node.</li>
+++ <li><tt>ft:tree-children</tt>: used inside ft:tree-nodes to recursively
apply
+++ the ft:tree-nodes template to the child nodes.</li>
+++ </ul>
+++ 
+++ <p>A very rough example is:</p>
+++ 
+++ <pre>&lt;ft:tree id="mytree"&gt;
+++   &lt;div&gt;
+++     &lt;ft:tree-nodes&gt;
+++       &lt;div&gt;
+++         ${treeNode.node.data}
+++       &lt;/div&gt;
+++       &lt;ft:tree-children/&gt;
+++     &lt;/ft:tree-nodes&gt;
+++   &lt;/div&gt;
+++ &lt;/ft:tree&gt;
+++ </pre>
+++ 
+++ <p>This example just shows the typical structural rendering, but doesn't contain
+++ any styling and javascript actions to trigger expansion and collapsion of nodes.
+++ </p>
+++ 
+++ <p>Inside ft:tree you have access to two variables:</p>
+++ 
+++ <ul>
+++ <li><tt>treeWidget</tt>, just a synonym for the normal "widget" variable
that is
+++ available in the template of each widget.</li>
+++ <li><tt>treeNode</tt>, provides access to the current tree node being
rendered.
+++ More specifically it is a
+++ <a href="javadoc:org.apache.cocoon.forms.formmodel.tree.TreeWalker">TreeWalker</a>
+++ instance. Its <tt>node</tt> property gives access to the actual tree node.</li>
+++ </ul>
+++ 
+++ <p class="note">The <tt>${treeNode.node.data}</tt> expression in the
template
+++ example above is specific to the form model you are using, since the node can be
+++ any object. The data property exists in the DefaultTreeModel nodes, however in
+++ the source tree model the nodes are Source objects, so you would use name
+++ instead of data.</p>
+++ 
+++ <h1>Tree node actions</h1>
+++ 
+++ <p>An action can be executed on a certain node in the tree. The available
+++ actions are:</p>
+++ 
+++ <ul>
+++ <li>expand</li>
+++ <li>collapse</li>
+++ <li>toggle-collapse</li>
+++ <li>select</li>
+++ <li>unselect</li>
+++ <li>toggle-select</li>
+++ </ul>
+++ 
+++ <p>To execute an action, set the hidden field named tree-widget-full-name +
+++ ":action" to one of the actions listed above. The node on which the action is
+++ applied is specified in the hidden field named tree-widget-full-name + ":path".
+++ The node is specified as a slash-separated path of node keys. In the template
+++ you can access this easily with <tt>treeNode.path</tt>.</p>
+++ 
+++ <h1>A more functional template</h1>
+++ 
+++ <p>For a complete example of a tree template, see e.g. the
+++ file_explorer_template.xml file in the CForms samples. From there, you can
+++ "steal" the styling and the javascript to perform tree node actions.</p>
+++ 
+++ <h1>API notes</h1>
+++ 
+++ <p>See the <a href="javadoc:org.apache.cocoon.forms.formmodel.tree.Tree">API
+++ docs of the tree widgets</a> for more information on how to access e.g. the
+++ selected nodes.</p>
+++ 
    </body>
    </html>


Fields
======
no changes

Links
=====
no changes

Custom Fields
=============
no changes

Collections
===========
no changes

Mime
View raw message