fuelux/_includes/js/tree.html

<!-- tree
================================================== -->
<div class="fu-docs-section">
  <h1 id="tree" class="page-header">Tree <a href="{{ site.repo }}/blob/{{ site.current_version }}/js/tree.js"><small>tree.js</small></a></h1>

  <h2 id="tree-usage">Usage</h2>
  <p>The tree provides a categorical selection interface that allows for interaction and selection of nested elements.</p>

  <div class="form-group">
    <ul class="tree" role="tree" id="treeIllustration">
      <li class="tree-branch hide" data-template="treebranch" role="treeitem" aria-expanded="false">
        <div class="tree-branch-header">
          <button type="button" class="tree-branch-name">
            <span class="glyphicon icon-caret glyphicon-play"></span>
            <span class="glyphicon icon-folder glyphicon-folder-close"></span>
            <span class="tree-label"></span>
          </button>
        </div>
        <ul class="tree-branch-children" role="group"></ul>
        <div class="tree-loader" role="alert">Loading...</div>
      </li>
      <li class="tree-item hide" data-template="treeitem" role="treeitem">
        <button type="button" class="tree-item-name">
          <span class="glyphicon icon-item fueluxicon-bullet"></span>
          <span class="tree-label"></span>
        </button>
      </li>
    </ul>
  </div>


  <h3 id="tree-usage-javascript">Via JavaScript</h3>
  <p>Call the tree control via JavaScript:</p>
{% highlight js %}
dataSource = function(parentData, callback){
  //...
};

$('#myTree').tree({ dataSource: dataSource });
{% endhighlight %}

  <h3 id="tree-usage-methods">Methods</h3>

  <dl>
    <dt id="tree-usage-methods-destroy">.tree('destroy')</dt>
    <dd>Removes all functionality, jQuery data, and the markup from the DOM. Returns string of control markup</dd>

    <dt id="tree-usage-methods-selectedItems">.tree('selectedItems')</dt>
    <dd>Returns an array containing selected items and associated data</dd>

    <dt id="tree-usage-methods-selectItem">.tree('selectItem', $('#itemId'))</dt>
    <dd>Select the passed in non-folder item in the tree.</dd>

    <dt id="tree-usage-methods-selectFolder">.tree('selectFolder', $('#itemId'))</dt>
    <dd>Select the passed in folder item in the tree.</dd>


    <dt id="tree-usage-methods-openFolder">.tree('openFolder', $('#folderId'))</dt>
    <dd>Open the targeted folder</dd>

    <dt id="tree-usage-methods-closeFolder">.tree('closeFolder', $('#folderId'))</dt>
    <dd>Close the targeted folder</dd>

    <dt id="tree-usage-methods-toggleFolder">.tree('toggleFolder', $('#folderId'))</dt>
    <dd>Toggle the targeted folder (opened or closed)</dd>

    <dt id="tree-usage-methods-closeAll">.tree('closeAll')</dt>
    <dd>Close all folders (collapse the entire tree).</dd>

    <dt id="tree-usage-methods-discloseAll">.tree('discloseAll')</dt>
    <dd>Disclose all folders (expand the entire tree).</dd>

    <dt id="tree-usage-methods-discloseVisible">.tree('discloseVisible')</dt>
    <dd>Disclose only currently visible folders (expand already displayed folders).</dd>

    <dt id="tree-usage-methods-populate">.tree('populate', $el)</dt>
    <dd><em>deprecated</em> Populate the passed in element as if it were a new copy of the instantiated tree. If you call this on an already instantiated tree, it will append all of the items to the tree again. You probably don't want to call this. It will most likely become a private function in the future.</dd>

    <dt id="tree-usage-methods-render">.tree('render')</dt>
    <dd>Calls <code>datasource</code> callback for entire tree. <em>Caution:</em> Does not remove current top-level tree nodes.</dd>

    <dt id="tree-usage-methods-render">.tree('refreshFolder', $('#folderId'))</dt>
    <dd>Removes children and calls <code>datasource</code> callback for specified folder. <em>Does not</em> update data and attributes of the specified folder.</dd>

    <dt id="tree-usage-methods-collapse">.tree('collapse')</dt>
    <dd><em>deprecated</em> Same as <a href="#tree-usage-methods-closeAll">.tree('closeAll')</a></dd>

  </dl>

  <h3 id="tree-usage-options">Options</h3>
  <p>You can pass options via data attributes or JavaScript. For data attributes, append the option name to <code>data-</code>. For example, you could use <code>data-selected=""</code>.</p>
  <div class="table-responsive">
    <table class="table table-bordered table-striped">
      <thead>
      <tr>
        <th style="width: 100px;">Name</th>
        <th style="width: 100px;">type</th>
        <th style="width: 50px;">default</th>
        <th>description</th>
      </tr>
      </thead>
      <tbody>
      <tr>
        <td>multiSelect</td>
        <td>boolean</td>
        <td>false</td>
        <td>Allows multiple tree items to be selected at once</td>
      </tr>
      <tr>
        <td>cacheItems</td>
        <td>boolean</td>
        <td>true</td>
        <td>Prevents refresh of sub-items when a user closes and reopens a folder</td>
      </tr>
      <tr>
        <td>folderSelect</td>
        <td>boolean</td>
        <td>true</td>
        <td>Enables folder selection</td>
      </tr><tr>
        <td>ignoreRedundantOpens</td>
        <td>boolean</td>
        <td>false</td>
        <td>Makes <code>openFolder()</code> behave like <code>toggleFolder()</code> instead. <em>Will be deprecated in <code>3.7.0</code> when <code>openFolder()</code> will only open the folder instead of toggling</em></td>
      </tr><tr>
        <td>disclosuresUpperLimit</td>
        <td>integer</td>
        <td>0</td>
        <td>How many times <code>discloseAll()</code> should be called before a stopping and firing an <code>exceededDisclosuresLimit.fu.tree</code> event. You can force it to continue by listening for this event, setting <code>data-ignore-disclosures-limit</code> to <code>true</code> and starting <code>discloseAll()</code> back up again. This lets you make more decisions about if/when/how/why/how many times <code>discloseAll()</code> will be started back up after it exceeds the limit.

<pre>
    $tree.one('exceededDisclosuresLimit.fu.tree', function () {
        $tree.data('ignore-disclosures-limit', true);
        $tree.tree('discloseAll');
    });
</pre>
<code>disclusuresUpperLimit</code> defaults to <code>0</code>, so by default this trigger will never fire. The true hard the upper limit is the browser's ability to load new items (i.e. it will keep loading until the browser falls over and dies). On the Fuel UX <code>index.html</code> testing page, the point at which the page became super slow (enough to seem almost unresponsive) was <code>4</code>, meaning 256 folders had been opened, and 1024 were attempting to open.</td>
      </tr>
      </tbody>
    </table>
  </div><!-- ./fu-table-responsive -->

  <h3 id="tree-usage-datasource">Required Data Source</h3>
  <p>The tree control requires an array of objects in order to create a tree. To determine what tree nodes to create, the tree control uses a callback function named <code>datasource</code> that returns an object with an array named <code>data</code> within it. Items in <codd>data</codd> will be created when a branch is opened. All tree nodes <i>must be loaded</i> into the control one folder (branch) at a time. However, one can store the entire tree from a single network request, and use the datasource function to parse this combined object and not make additional network requests. The following are reserved keys within each item object.</p>

  <div class="table-responsive">
    <table class="table table-bordered table-striped">
      <thead>
      <tr>
        <th style="width: 125px;">Key</th>
        <th style="width: 100px;">Type</th>
        <th>Description</th>
      </tr>
      </thead>
      <tbody>
      <tr>
        <td>text</td>
        <td>string</td>
        <td><i>Required.</i> Text of tree node. *Please note: text replaces and deprecates name</td>
      </tr>
      <tr>
        <td>type</td>
        <td>string</td>
        <td><i>Required.</i> Options are <code>folder</code> or <code>item</code>.</td>
      </tr>
      <tr>
        <td>attr</td>
        <td>object</td>
        <td>Unless it is a reserved key in this table, child keys will be added as attributes to <code>.tree-item</code> or <code>.tree-branch</code>.</td>
      </tr>
      <tr>
        <td>attr.cssClass</td>
        <td>string</td>
        <td>CSS classes that will be added to <code>.tree-item</code> or <code>.tree-branch</code></td>
      </tr>
      <tr>
        <td>attr.data-icon</td>
        <td>string</td>
        <td>CSS classes that will be added to <code>.icon-item</code></td>
      </tr>
      <tr>
        <td>attr.id</td>
        <td>string</td>
        <td>Adds <code>id</code> to <code>.tree-item</code> or <code>.tree-branch</code> and adds ARIA support with <code>aria-labelledby</code>.</td>
      </tr>
      <tr>
        <td>attr.hasChildren</td>
        <td>boolean</td>
        <td>Set to false to hide the chevron next to folders. Defaults to true.</td>
      </tr>
      </tbody>
    </table>
  </div><!-- ./fu-table-responsive -->

  <h3 id="tree-usage-events">Events</h3>
  <div class="table-responsive">
    <table class="table table-bordered table-striped">
      <thead>
      <tr>
        <th style="width: 150px;">Event Type</th>
        <th>Description</th>
      </tr>
      </thead>
      <tbody>
        <tr>
          <td>selected.fu.tree</td>
          <td>Fires when a user selects an item or folder. Returns an object containing an array of the selected items' jQuery data and the jQuery data of the triggering item. <code>{ selected: [array], target: [object] }</code></td>
        </tr>
        <tr>
          <td>deselected.fu.tree</td>
          <td>Fires when a user deselects an item or folder. Returns an object containing an array of the selected items' jQuery data and the jQuery data of the triggering item. <code>{ selected: [array], target: [object] }</code></td>
        </tr>
        <tr>
          <td>loaded.fu.tree</td>
          <td>Fires when sub-content has been is loaded. Returns the jQuery element of the folder loaded.</td>
        </tr>
        <tr>
          <td>updated.fu.tree</td>
          <td>Fires after <code>selected.fu.tree</code> and <code>deselected.fu.tree</code> events. Returns an object containing an array of selected items' jQuery data, the triggering jQuery element and the event type. <code>{ selected: [array], item: [object], eventType: [string] }</code></td>
        </tr>
        <tr>
          <td>disclosedFolder.fu.tree</td>
          <td>Fires when a user opens a folder. Returns an object containing the jQuery data of the opened folder.</td>
        </tr>
        <tr>
          <td>refreshedFolder.fu.tree</td>
          <td>Fires when a user refreshes a folder. Returns an object containing the jQuery data of the opened folder.</td>
        </tr>
        <tr>
          <td>closed.fu.tree</td>
          <td>Fires when a user closes a folder. Returns an object containing the jQuery data of the closed folder.</td>
        </tr>
        <tr>
          <td>closedAll.fu.tree</td>
          <td>Fires when all folders have finished closing. Returns an object containing an array of closed folders' jQuery data and the tree's jQuery element. The <code>length</code> of <code>reportedClosed</code> will provide the number of folders closed. <code>{ reportedClosed: [array], tree: [$element] }</code></td>
        </tr>
        <tr>
          <td>disclosedVisible.fu.tree</td>
          <td>Fires when all visible folders have disclosed/opened. Returns an object containing an array of disclosed folders' jQuery data and the tree's jQuery element. The <code>length</code> of <code>reportedOpened</code> will provide the number of folders opened. <code>{ reportedOpened: [array], tree: [$element] }</code></td>
        </tr>
        <tr>
          <td>exceededDisclosuresLimit.fu.tree</td>
          <td>Fires when tree halts disclosing due to hitting discloserLimit cap. Returns an object containing <code>{ disclosures: [number], tree: [$element] }</code></td>
        </tr>
        <tr>
          <td>disclosedAll.fu.tree</td>
          <td>Fires when all folders have disclosed. <em>It will not fire if tree stops disclosing due to hitting discloserLimit cap.</em> Returns an object containing <code>{ disclosures: [number], tree: [$element] }</code></td>
        </tr>

      </tbody>
    </table>
  </div><!-- ./fu-table-responsive -->
  <p>All tree events are triggered from the <code>.tree</code> classed element.</p>
{% highlight js %}
$('#myTree').on('selected.fu.tree', function (event, data) {
  // do something with data: { selected: [array], target: [object] }
})
{% endhighlight %}

  <h2 id="tree-examples">Examples</h2>

  <p>Tree provides a categorical element selection. Use it to create a file system interface. Wrap the wrapper tree containers with <code>.fuelux .tree</code></p>

  <div class="form-group">
    <label class="control-label">Folders selectable</label>
    <p>Please note the location of <code>.glyphicon-play</code> <em>outside</em> <code>.tree-branch-name</code>. The control
      allows folders to be selected by default unless the <code>folderSelect</code> option is set to <code>false</code>,
      which then requires slightly different markup ("Items selectable only," shown further below)</p>
    <div class="form-group">

      <ul class="tree tree-folder-select" role="tree" id="myTreeSelectableFolder">
        <li class="tree-branch hide" data-template="treebranch" role="treeitem" aria-expanded="false">
          <div class="tree-branch-header">
            <button type="button" class="glyphicon icon-caret glyphicon-play"><span class="sr-only">Open</span></button>
            <button type="button" class="tree-branch-name">
              <span class="glyphicon icon-folder glyphicon-folder-close"></span>
              <span class="tree-label"></span>
            </button>
          </div>
          <ul class="tree-branch-children" role="group"></ul>
          <div class="tree-loader" role="alert">Loading...</div>
        </li>
        <li class="tree-item hide" data-template="treeitem" role="treeitem">
          <button type="button" class="tree-item-name">
            <span class="glyphicon icon-item fueluxicon-bullet"></span>
            <span class="tree-label"></span>
          </button>
        </li>
      </ul>

    </div>
  </div>

{% highlight html %}
<ul class="tree tree-folder-select" role="tree" id="myTree">
  <li class="tree-branch hide" data-template="treebranch" role="treeitem" aria-expanded="false">
    <div class="tree-branch-header">
      <button type="button" class="glyphicon icon-caret glyphicon-play"><span class="sr-only">Open</span></button>
      <button type="button" class="tree-branch-name">
        <span class="glyphicon icon-folder glyphicon-folder-close"></span>
        <span class="tree-label"></span>
      </button>
    </div>
    <ul class="tree-branch-children" role="group"></ul>
    <div class="tree-loader" role="alert">Loading...</div>
  </li>
  <li class="tree-item hide" data-template="treeitem" role="treeitem">
    <button type="button" class="tree-item-name">
      <span class="glyphicon icon-item fueluxicon-bullet"></span>
      <span class="tree-label"></span>
    </button>
  </li>
</ul>
{% endhighlight %}


  <div class="form-group">
    <label class="control-label">Items selectable only</label>
    <p>Please note the location of <code>.glyphicon-play</code> <em>inside</em> <code>.tree-branch-name</code>. This markup
    is used if the <code>folderSelect</code> option is set to <code>false</code>.</p>
    <div class="form-group">

      <ul class="tree" role="tree" id="myTree">
        <li class="tree-branch hide" data-template="treebranch" role="treeitem" aria-expanded="false">
          <div class="tree-branch-header">
            <button type="button" class="tree-branch-name">
              <span class="glyphicon icon-caret glyphicon-play"></span>
              <span class="glyphicon icon-folder glyphicon-folder-close"></span>
              <span class="tree-label"></span>
            </button>
          </div>
          <ul class="tree-branch-children" role="group"></ul>
          <div class="tree-loader" role="alert">Loading...</div>
        </li>
        <li class="tree-item hide" data-template="treeitem" role="treeitem">
          <button type="button" class="tree-item-name">
            <span class="glyphicon icon-item fueluxicon-bullet"></span>
            <span class="tree-label"></span>
          </button>
        </li>
      </ul>

    </div>
  </div>
  {% highlight html %}
  <ul class="tree" role="tree" id="myTree">
    <li class="tree-branch hide" data-template="treebranch" role="treeitem" aria-expanded="false">
      <div class="tree-branch-header">
        <button type="button" class="tree-branch-name">
          <span class="glyphicon icon-caret glyphicon-play"></span>
          <span class="glyphicon icon-folder glyphicon-folder-close"></span>
          <span class="tree-label"></span>
        </button>
      </div>
      <ul class="tree-branch-children" role="group"></ul>
      <div class="tree-loader" role="alert">Loading...</div>
    </li>
    <li class="tree-item hide" data-template="treeitem" role="treeitem">
      <button type="button" class="tree-item-name">
        <span class="glyphicon icon-item fueluxicon-bullet"></span>
        <span class="tree-label"></span>
      </button>
    </li>
  </ul>
  {% endhighlight %}

</div>