view release on metacpan or  search on metacpan

doc/html/TreeNavigator.html  view on Meta::CPAN

      <p>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.</p>
  <div class="TN_node" id="Tree_structure">
    <h3 class="TN_label">Tree structure</h3>
    <div class="TN_content">
      <p>A tree is a collection of <i>nodes</i>. Each node must have a <i>label</i>
element and can have a <i>content</i> element. A node may be either
<i>open</i> (its content is visible) or <i>closed</i> (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</i> : in that
case they have no content and have no open/close operations.</p>
<p>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.</p>
<p>A node's content may also by dynamic, by
specifying <code>TN:contentURL</code> with the URL as value:</p>
<pre>  &lt;div class="TN_node TN_closed" TN:contentURL="/my/url.html"&gt;
    &lt;div class="TN_label"&gt;Label for dynamic node&lt;/div&gt;
  &lt;/div&gt;</pre>

<p>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 
<code>Ctrl-R</code> key.</p>

    </div>
  </div>
  <div class="TN_node" id="HTML_tree_declaration">
    <h3 class="TN_label">HTML tree declaration</h3>
    <div class="TN_content">
      <p>The tree can be any HTML block element. It should contain one or
several block elements declared with class <code>TN_node</code> or class
<code>TN_leaf</code> -- usually these are DIV elements. Other HTML elements
may be freely interspersed with nodes, although this usually does not
make much sense for navigability.</p>
<p>Every node must in turn contain an inline element
declared with class <code>TN_label</code> -- usually this is
a SPAN element. If the node is not a leaf, it may
then contain a block element declared
with class <code>TN_content</code> -- usually this is
another DIV element. Both the label and the content
should be direct children of the node element.</p>
<p>At initialisation time, a new SPAN element is
automatically inserted before each label, in order to
add the +/- navigation buttons.</p>

    </div>
  </div>
  <div class="TN_node" id="Icons_customization">
    <h3 class="TN_label">Icons customization</h3>
    <div class="TN_content">
      <p>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 
<code>TN_button</code> class:</p>
<pre>  .TN_button { 
  background-image: url(myIconForOpenNodes.gif);   
  }
  .TN_closed .TN_button { 
  background-image: url(myIconForClosedNodes.gif); 
  }</pre>

<p>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:</p>
<ul>
<li>
<p>add an empty <code>span</code> element within the
labels that should have the icon</p>
<pre>  &lt;span class="TN_label"&gt;&lt;span class="specialNode"&gt;&lt;/span&gt;some label&lt;/span&gt;</pre>

</li>
<li>
<p>define CSS background images for selectors
<code>.specialNode</code> and  <code>.TN_closed .specialNode</code>,
as in the example above</p>
</li>
</ul>

    </div>
  </div>

    </div>
  </div>
  <div class="TN_node" id="Usage_navigation">
    <h2 class="TN_label">Usage : navigation</h2>
    <div class="TN_content">
      <p>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</i> : this is the one that receives keyboard
events. Hence if the tree has no
selected node, no keyboard events are interpreted.</p>
  <div class="TN_node" id="Mouse_events">
    <h3 class="TN_label">Mouse events</h3>
    <div class="TN_content">
      <p>Mousing over a node label adds the class
<code>TN_mouse</code> to that node; the default style for
that class is just to underline the label.</p>
<p>Clicking on a node label selects that node and
fires the <code>Ping</code> event.
Clicking on the square +/- icon on the left of the
label toggles the open/closed status of the node.</p>

    </div>
  </div>
  <div class="TN_node" id="Keyboard_events">
    <h3 class="TN_label">Keyboard events</h3>
    <div class="TN_content">
      <ul>
<li><a name="item__code_keypad____code_"></a><b><code>keypad +</code></b>
<p>open the node</p>
</li>
<li><a name="item__code_keypad____code_"></a><b><code>keypad -</code></b>
<p>close the node</p>
</li>
<li><a name="item__code_keypad____code_"></a><b><code>keypad *</code></b>
<p>open the node and all its subnodes</p>
</li>
<li><a name="item__code_keypad____code_"></a><b><code>keypad /</code></b>
<p>close the node and all its subnodes</p>
</li>
<li><a name="item__code_Ctrl_keypad____code_"></a><b><code>Ctrl-keypad *</code></b>
<p>activate "show all" mode (the content of closed nodes is nevertheless
visible, which may be useful for printing)</p>
</li>
<li><a name="item__code_Ctrl_keypad____code_"></a><b><code>Ctrl-keypad /</code></b>
<p>deactivate the "show all" mode</p>
</li>
<li><a name="item__code_TAB__code_"></a><b><code>TAB</code></b>
<p>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).</p>
</li>
<li><a name="item__code_ARROW_UP__code_"></a><b><code>ARROW_UP</code></b>

doc/html/TreeNavigator.html  view on Meta::CPAN

</li>
<li><a name="item_button"></a><b>button</b>
<p>Class(es) for buttons added automatically by the tree navigator
(default is <code>TN_button</code>).</p>
</li>
<li><a name="item_showall"></a><b>showall</b>
<p>Class(es) for the special mode in which closed nodes are nevertheless
displayed
(default is <code>TN_showall</code>).</p>
</li>
</ul>

    </div>
  </div>

    </div>
  </div>
  <div class="TN_node" id="destroy">
    <h4 class="TN_label">destroy</h4>
    <div class="TN_content">
      <pre>  mytreenavigator.destroy();</pre>

<p>This method will remove all handlers assigned to tree navigator.
Call this method when the tree navigator element is removed from the DOM.</p>

    </div>
  </div>
  <div class="TN_node" id="Node_manipulation">
    <h4 class="TN_label">Node manipulation</h4>
    <div class="TN_content">
      <p>All methods below take a node element as
argument, i.e. are called according to pattern:</p>
<pre>  treeNavigator.method(node);</pre>

<ul>
<li><a name="item__code_open_node___code_"></a><b><code>open(node)</code></b>
<p>opens the node</p>
</li>
<li><a name="item__code_close_node___code_"></a><b><code>close(node)</code></b>
<p>closes the node</p>
</li>
<li><a name="item__code_openAtLevel_elem__level___code_"></a><b><code>openAtLevel(elem, level)</code></b>
<p>walks down the tree and opens all subnodes of <code>elem</code> until level
<code>level</code>; closes nodes underneath</p>
</li>
<li><a name="item__code_openEnclosingNodes_elem___code_"></a><b><code>openEnclosingNodes(elem)</code></b>
<p>walks up the DOM, starting at <code>elem</code> (which might by any element on
the page), and opens all nodes found on the way</p>
</li>
<li><a name="item__code_select_node__prevent_autoscroll___code_"></a><b><code>select(node, prevent_autoscroll)</code></b>
<p>If there was a selected node, unselect it; then select the argument
node. The argument can be <code>null</code>, in which case the tree no longer
has any selected node.</p>
<p>The second argument <code>prevent_autoscroll</code> is optional; if true,
no autoscroll will be performed.</p>
</li>
<li><a name="item__code_scrollTo_node___code_"></a><b><code>scrollTo(node)</code></b>
<p>Positions the node in the middle of the screen</p>
</li>
<li><a name="item__code_flash_node__duration__color___code_"></a><b><code>flash(node, duration, color)</code></b>
<p>Changes the background color of <i>node</i> to <i>color</i> for <i>duration</i>
milliseconds.  Duration and color are optional and default to 200 ms
and 'red' (unless otherwise specified in the options to the
<code>treeNavigator</code> constructor).</p>
</li>
<li><a name="item__code_isClosed_node___code_"></a><b><code>isClosed(node)</code></b>
<p>Returns true if the node is closed</p>
</li>
<li><a name="item__code_isVisible_node___code_"></a><b><code>isVisible(node)</code></b>
<p>Returns true if the node is visible
(i.e. does not have <code>display:none</code>).</p>
</li>
</ul>

    </div>
  </div>
  <div class="TN_node" id="Walking_the_tree">
    <h4 class="TN_label">Walking the tree</h4>
    <div class="TN_content">
      <ul>
<li><a name="item__code_nextSibling_node___code_"></a><b><code>nextSibling(node)</code></b>
<p>Returns the next sibling tree node (i.e. next HTML sibling element
having class <code>TN_node</code>; this is <i>not</i> equivalent to
<code>node.nextSibling</code>).</p>
</li>
<li><a name="item__code_previousSibling_node___code_"></a><b><code>previousSibling(node)</code></b>
<p>Returns the previous sibling tree node.</p>
</li>
<li><a name="item__code_parentNode_node___code_"></a><b><code>parentNode(node)</code></b>
<p>Returns the parent tree node.</p>
</li>
<li><a name="item__code_firstSubNode_node___code_"></a><b><code>firstSubNode(node)</code></b>
<p>Returns the first subnode within that node's content. If no argument
is given, returns the first node of the tree.</p>
</li>
<li><a name="item__code_lastSubNode_node___code_"></a><b><code>lastSubNode(node)</code></b>
<p>Returns the last subnode within that node's content.  If no argument
is given, returns the last node of the tree.</p>
</li>
<li><a name="item__code_lastVisibleSubNode_node___code_"></a><b><code>lastVisibleSubNode(node)</code></b>
<p>Returns the last visible subnode (recursively) of the argument
node. If no argument is given, returns the last visible subnode of the
tree.</p>
</li>
<li><a name="item__code_label_node___code_"></a><b><code>label(node)</code></b>
<p>Returns the label of that node, i.e. the first HTML child element
having class <code>TN_label</code>.</p>
</li>
<li><a name="item__code_content_node___code_"></a><b><code>content(node)</code></b>
<p>Returns the content of that node, i.e. the last HTML child element
having class <code>TN_content</code>.</p>
</li>
<li><a name="item__code_nextDisplayedNode_node___code_"></a><b><code>nextDisplayedNode(node)</code></b>
<p>Returns the next tree node in page display order (i.e. next visible
node down the page).</p>
</li>
<li><a name="item__code_previousDisplayedNode_node___code_"></a><b><code>previousDisplayedNode(node)</code></b>
<p>Returns the previous tree node in page display order (i.e. previous
visible node up the page).</p>
</li>
<li><a name="item__code_enclosingNode_elem___code_"></a><b><code>enclosingNode(elem)</code></b>