Alien-GvaScript
view release on metacpan or search on metacpan
lib/Alien/GvaScript/TreeNavigator.pod view on Meta::CPAN
=encoding ISO8859-1
=head1 NAME
Alien::GvaScript::TreeNavigator - Navigation in a tree structure
=head1 SYNOPSIS
<head>
<script src="prototype.js"></script>
<script src="Keymap.js"></script>
<script src="Navigator.js"></script>
<link href="Navigator.css" rel="stylesheet" type="text/css">
</head>
<body onload="new GvaScript.TreeNavigator('TN_tree')">
<div id="TN_tree">
<div class="TN_node">
<span class="TN_label">Label 1</span>
<div class="TN_content">
<div class="TN_node">
<span class="TN_label">Label 1.1</span>
<div class="TN_content">
...Content of node 1.1
</div>
</div>
<div class="TN_leaf">
<span class="TN_label">Label 1.2 for leaf</span>
</div>
</div>
</div>
</div>
</body>
=head1 DESCRIPTION
Handles navigation in a data tree. The tree
description is usual HTML, with some special classes to
identify nodes. Nodes can be browsed, closed or
opened. All operations take place directly within the
tree, not in a separate panel.
=head2 Tree structure
A tree is a collection of I<nodes>. Each node must have a I<label>
element and can have a I<content> element. A node may be either
I<open> (its content is visible) or I<closed> (its content is
invisible). The label of the node is always visible, if the node
itself is visible. Some nodes can be declared as I<leaves> : in that
case they have no content and have no open/close operations.
The content of a node may include other nodes, so a whole subtree may
become invisible if the parent node is closed. Opening or closing
nodes may be controlled by the mouse, by the keyboard, or through the
programming interface.
A node's content may also by dynamic, by
specifying C<TN:contentURL> with the URL as value:
<div class="TN_node TN_closed" TN:contentURL="/my/url.html">
<div class="TN_label">Label for dynamic node</div>
</div>
If the user opens that node, the content of the URL will by
dynamically fetched and inserted into the tree. The content then
stays there, but can be forcibly reloaded by hitting the
C<Ctrl-R> key.
=head2 HTML tree declaration
lib/Alien/GvaScript/TreeNavigator.pod view on Meta::CPAN
Every node must in turn contain an inline element
declared with class C<TN_label> -- usually this is
a SPAN element. If the node is not a leaf, it may
then contain a block element declared
with class C<TN_content> -- usually this is
another DIV element. Both the label and the content
should be direct children of the node element.
At initialisation time, a new SPAN element is
automatically inserted before each label, in order to
add the +/- navigation buttons.
=head2 Icons customization
By default, the navigation buttons inserted on the
left of labels are small icons representing +/- signs.
To show other icons, change the CSS rules about the
C<TN_button> class:
.TN_button {
background-image: url(myIconForOpenNodes.gif);
}
.TN_closed .TN_button {
background-image: url(myIconForClosedNodes.gif);
}
In addition, if you want another icon for illustrating
the node's content (like for example an open or closed
folder), you can proceed as follows:
=over
=item *
add an empty C<span> element within the
labels that should have the icon
<span class="TN_label"><span class="specialNode"></span>some label</span>
=item *
define CSS background images for selectors
C<.specialNode> and C<.TN_closed .specialNode>,
as in the example above
=back
=head1 Usage : navigation
Navigation in the tree is either with the mouse or with
the keyboard. At any point in time, at most one node is
I<selected> : this is the one that receives keyboard
events. Hence if the tree has no
selected node, no keyboard events are interpreted.
=head2 Mouse events
Mousing over a node label adds the class
C<TN_mouse> to that node; the default style for
that class is just to underline the label.
Clicking on a node label selects that node and
fires the C<Ping> event.
Clicking on the square +/- icon on the left of the
label toggles the open/closed status of the node.
=head2 Keyboard events
=over
=item C<keypad +>
open the node
=item C<keypad ->
close the node
=item C<keypad *>
open the node and all its subnodes
=item C<keypad />
close the node and all its subnodes
=item C<Ctrl-keypad *>
activate "show all" mode (the content of closed nodes is nevertheless
visible, which may be useful for printing)
=item C<Ctrl-keypad />
deactivate the "show all" mode
=item C<TAB>
if closed, open the node; if already opened, pass focus to the next
item (maybe the next node, or another tabindex-enabled HTML element,
such as a form control).
=item C<ARROW_UP>
move to previous displayed node
=item C<ARROW_DOWN>
move to next displayed node
=item C<ARROW_LEFT>
if open, close the node; if already closed, move to parent node
=item C<ARROW_RIGHT>
if closed, open the node; if already open, move to next subnode
lib/Alien/GvaScript/TreeNavigator.pod view on Meta::CPAN
=head4 scrollingContainer
The id of the container where the tree overflows.
Default to C<tree.ownerDocument.documentElement>.
This is used for keyboard tree navigation autoscrolling.
=head4 autoScrollPercentage
Makes sure that the selected node is visible in the central area of
its offset parent; if not, the parent is scrolled.
The percentage is the ratio between the parent height and the
margin at which scrolling must occur (default is 20%);
=head4 keymap
A keymap object (see C<Keymap.js>). If that option is given, keyboard
handlers are pushed into that keymap; otherwise a new keymap is
created.
If you supply your own keymap, make
sure that:
=over
=item *
the keymap is attached to an element that properly receives keyboard
events. The document element does, but the tree DIV element does not,
unless it contains items with activated focus (with C<tabIndex>
defined and positive).
=item *
the keymap is created with options C<preventDefault:false> and
C<stopPropagation:false> (because when the tree has no selected node,
the tree navigation handlers do not consume events and try to
propagate them further).
=back
=head4 classes
Class names for various parts of the tree structure.
This should be an inline object, with keys corresponding
to the names below, and with values specified either as
a single class name or as an array of class names.
=over
=item node
Class(es) for node elements (default is C<TN_node>).
A node should contain a label element and a
content element, and should have style
C<display:block>.
=item leaf
Class(es) for leaf elements (default is C<TN_leaf>).
A leaf should contain just a label element.
=item label
Class(es) for label elements (default is C<TN_label>).
A label should have style C<display:inline>.
=item content
Class(es) for content elements (default is C<TN_content>).
=item closed
Class(es) for marking closed nodes (default is C<TN_closed>).
=item selected
Class(es) for marking the selected node (default is C<TN_selected>).
=item mouse
Class(es) added when the mouse hovers over a node
(default is C<TN_mouse>).
=item button
Class(es) for buttons added automatically by the tree navigator
(default is C<TN_button>).
=item showall
Class(es) for the special mode in which closed nodes are nevertheless
displayed
(default is C<TN_showall>).
=back
=head3 destroy
mytreenavigator.destroy();
This method will remove all handlers assigned to tree navigator.
Call this method when the tree navigator element is removed from the DOM.
=head3 Node manipulation
All methods below take a node element as
argument, i.e. are called according to pattern:
treeNavigator.method(node);
=over
=item C<open(node)>
opens the node
=item C<close(node)>
closes the node
( run in 0.805 second using v1.01-cache-2.11-cpan-119454b85a5 )