view release on metacpan or  search on metacpan

lib/Alien/GvaScript/TreeNavigator.pod  view on Meta::CPAN

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

The tree can be any HTML block element. It should contain one or
several block elements declared with class C<TN_node> or class
C<TN_leaf> -- usually these are DIV elements. Other HTML elements
may be freely interspersed with nodes, although this usually does not
make much sense for navigability.


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,

lib/Alien/GvaScript/TreeNavigator.pod  view on Meta::CPAN

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

=item C<openAtLevel(elem, level)>

walks down the tree and opens all subnodes of C<elem> until level
C<level>; closes nodes underneath

=item C<openEnclosingNodes(elem)>

walks up the DOM, starting at C<elem> (which might by any element on
the page), and opens all nodes found on the way

=item C<select(node, prevent_autoscroll)>

If there was a selected node, unselect it; then select the argument
node. The argument can be C<null>, in which case the tree no longer
has any selected node. 

The second argument C<prevent_autoscroll> is optional; if true,
no autoscroll will be performed.


=item C<scrollTo(node)>

Positions the node in the middle of the screen

=item C<flash(node, duration, color)>


Changes the background color of I<node> to I<color> for I<duration>
milliseconds.  Duration and color are optional and default to 200 ms
and 'red' (unless otherwise specified in the options to the
C<treeNavigator> constructor).

=item C<isClosed(node)>

Returns true if the node is closed

=item C<isVisible(node)>

Returns true if the node is visible
(i.e. does not have C<display:none>).

=back

=head3 Walking the tree

=over

=item C<nextSibling(node)>

Returns the next sibling tree node (i.e. next HTML sibling element
having class C<TN_node>; this is I<not> equivalent to
C<node.nextSibling>).


=item C<previousSibling(node)>

Returns the previous sibling tree node.

=item C<parentNode(node)>

Returns the parent tree node.

=item C<firstSubNode(node)>

Returns the first subnode within that node's content. If no argument
is given, returns the first node of the tree.

=item C<lastSubNode(node)>

Returns the last subnode within that node's content.  If no argument
is given, returns the last node of the tree.

=item C<lastVisibleSubNode(node)>

Returns the last visible subnode (recursively) of the argument
node. If no argument is given, returns the last visible subnode of the
tree.

=item C<label(node)>

Returns the label of that node, i.e. the first HTML child element
having class C<TN_label>.

=item C<content(node)>

Returns the content of that node, i.e. the last HTML child element
having class C<TN_content>.