Home

Martin@MBP edited this page Dec 4, 2016 · 46 revisions

An introduction to Fancytree.

Main Features

  • Lazy loading and very efficient and performant handling of large data sets
  • Keyboard navigation
  • (Hierarchical) selection and checkboxes
  • Table view (gridview)
  • Drag and drop
  • Persistence of expansion, selection and active state
  • Inline editing
  • Themable (comes with WinXP, Win7, Win8, OS X Lion, and Glyph samples)
  • The tree behaves like a single form control, i.e. it is 'tabbable' (example)
  • Rich object oriented API
  • Extensible modular design
  • and more... see the list of available extensions

Try the Demos

Have a look at the Example Browser to play with live demos. Click the View source link at the bottom of every page to see what's going on.

Getting Started

Requirements:

  • jQuery 1.7+ (1.11+ recommended)
  • jQuery UI 1.8.6+ (1.11+ recommended)
    If a custom download is used, at least the follwing components should be included:
    'UI Core',
    'Effects': 'Effects Core', 'Blind Effect'
    The dnd extension also requires 'Interactions': 'Draggable', 'Droppable'

There are several ways to get the latest Fancytree release:

  1. If you use bower, a simple $ bower install fancytree will download the latest stable release.
  2. If you use npm Registry, a simple $ npm install jquery.fancytree will download the latest stable release.
  3. Include a CDN link to jsdelivr, cdnjs, or UNPKG on your page.
  4. Open a release from the release list and download the complete source tree with documentation, tests, etc. by clicking Source code (zip). You will find the production library and CSS files in the dist/ folder.
  5. You can also click Download ZIP at the project page to get the latest development snapshot. Note that the dist/ folder still contains the latest released version. You have to run npm install and grunt build to create current minified files in the build/ folder (see here for details).

Currently we deliver

fancytree/
├─ demo/                                 Example browser
├─ src/                                  Current development code ('nightly build')
├─ test/                                 Unit tests and triage
└─ dist/                                 Latest released version:
   ├─ jquery.fancytree.js                  Core library (no extensions)
   ├─ jquery.fancytree.min.js              Same as above, minified
   ├─ jquery.fancytree-all.js              Library with most extensions (uncompressed)
   ├─ jquery.fancytree-all.min.js          Library with most extensions, minified 
   │                                         and with AMD support. This is what you 
   │                                         would use for production 
   │                                         (maybe removing unwanted extensions)
   ├─ skin-common.less                     Shared CSS, used by stock themes
   ├─ src/                                 This folder contains all single extensions
   ├─ skin-NAME/                           CSS styles for the stock theme NAME
   └─ skin-custom-1/                       Starting point for a custom theme

See HowtoContribute for details on how to install Fancytree for debugging and contributing.

Understand the Core Concepts

This is not required for standard use cases, but you might want to come back to read about the Main Concepts later on.

Embed Fancytree on Your Web Page

The most simple way to create a tree is like that:

<head>
  [...]
  <!-- Include jQuery and jQuery UI -->
  <script src="//code.jquery.com/jquery-1.12.1.min.js"></script>
  <script src="//code.jquery.com/ui/1.11.4/jquery-ui.min.js"></script>
  <!-- Include Fancytree skin and library -->
  <link href="fancytree/skin-win8/ui.fancytree.min.css" rel="stylesheet">
  <script src="fancytree/jquery.fancytree-all.min.js"></script>
  <!-- Initialize the tree when page is loaded -->
  <script type="text/javascript">
    $(function(){
      // Create the tree inside the <div id="tree"> element.
      $("#tree").fancytree({ ... });
    });
  </script>
</head>
<body>
  [...]
  <!-- Define where the tree should appear -->
  <div id="tree">...</div>
  [...]
</body>
</html>

Configure Options

Additional options are passed to Fancytree during initialization:

$("#tree").fancytree({
  source: {
    url: "ajax-tree-plain.json"
  },
  checkbox: true,
  [...]
});

Options can also be set after initialization using this syntax:

$("#tree").fancytree("option", "checkbox", true);

For more information see also the complete list of available options and the Option Configurator.

Define the Tree Data

There are several ways to define the actual node structure:

  1. Use the source option to pass a data structure, i.e. an array of nested objects:

      source: [
        {title: "Node 1", key: "1"},
        {title: "Folder 2", key: "2", folder: true, children: [
          {title: "Node 2.1", key: "3"},
          {title: "Node 2.2", key: "4"}
        ]}
      ],
      ...

    See also the complete list of data properties.

  2. Use the source option to load the data via ajax.

      source: {
        url: "/getTreeData",
        cache: false
      },
      ...

    The ajax service is expected to return valid JSON data:

    [{"title": "Node 1", "key": "1"},
     {"title": "Folder 2", "key": "2", "folder": true, "children": [
        {"title": "Node 2.1", "key": "3"},
        {"title": "Node 2.2", "key": "4"}
      ]}
    ]
  3. Define a <ul>/<li> markup structure inside the tree's <div> tag.

    $("#tree").fancytree();
    <div id="tree">
      <ul id="treeData" style="display: none;">
        <li id="1">Node 1
        <li id="2" class="folder">Folder 2
          <ul>
            <li id="3">Node 2.1
            <li id="4">Node 2.2
          </ul>
      </ul>
    </div>
      ...

For more information see also TutorialLoadData and the online demo.

Event Handling

Functionality can be added (and modified) by defining event handlers (i.e. callback functions).

Every event handler is passed a data argument, that contains information about the event target.

  $("#tree").fancytree({
    ...
    activate: function(event, data){
      // A node was activated: display its title:
      var node = data.node;
      $("#echoActive").text(node.title)
    },
    beforeSelect: function(event, data){
      // A node is about to be selected: prevent this, for folder-nodes:
      if( data.node.isFolder() ){
        return false;
      }
    }
  });

An alternative way to define event handlers is to bind them later to an initialized tree. Note that the event name must be converted to lower case and prefixed with 'fancytree':

  $("#tree").on("fancytreebeforeselect", function(event, data){
    ...
  });

For more information see also TutorialEvents, the online demo, the complete list of available events, and a description of the 'data' object.

Lazy Loading

Fancytree supports loading nodes on demand, i.e. only load data when a node is expanded for the first time.

In order to enable this, we can mark nodes as lazy.

  $("#tree").fancytree({
    // Initial node data that sets 'lazy' flag on some leaf nodes
    source: [
      {title: "Child 1", key: "1", lazy: true},
      {title: "Folder 2", key: "2", folder: true, lazy: true}
    ],
    lazyLoad: function(event, data) {
      var node = data.node;
      // Issue an ajax request to load child nodes
      data.result = {
        url: "/getBranchData",
        data: {key: node.key}
      }
    }
  });

For more information see TutorialLoadData.

API Access

Fancytree exposes an extensive, object oriented interface to query and manipulate the data model:

  var tree = $("#tree").fancytree("getTree"),
      activeNode = tree.getActiveNode();

  // Sort children of active node:
  activeNode.sortChildren();
  // Expand all tree nodes
  tree.visit(function(node){
    node.setExpanded(true);
  });
  // Append a new child node
  activeNode.addChildren({
    title: "Document using a custom icon",
    icon: "customdoc1.gif"
  });

For more information see TutorialApi.

Selection and Checkboxes

See the online demo.

Theming

Some skins are part of the distribution (Win-XP, Windows 7, Windows 8, OS X Lion, ...). Use the Skin combobox on the online demo, to try them out.

Some more info here.

Extensions

Fancytree is extensible using extensions. The standard distribution already contains some extra functionality in this way, such as table-support, inline editing, filtering, etc.

Read more about