ExtClones

About Fancytree 'clones' extension.

• Status: production
• example

Support linked nodes, i.e. multiple tree nodes representing the same data instance.

Fancytree requires that node.key values are unique throughout the whole tree. If we want to display a hierarchy of articles and a single article may appear under different product categories, we need these unique keys to distinguish which node was clicked or should be selected. This implies that we cannot use the key to hold the article number.
Another common use case are trees that are used to display a net, i.e. map a graph onto a hierarchy, because nodes may be reached via multiple paths.

We call nodes with more than one occurrence 'clones'.
Note that there is nothing like a master or original node: all clones are equal (think hard links).

The ext-clones plugin introduces a new field node.refKey to store the common data ids (e.g. article numbers). It also adds bookkeeping to keep track of the dependencies when node are added or removed, which leads to faster lookup of nodes by key and shared ref-ids.

Because in these linked-nodes scenarios the value of node.key is often meaningless to the server, it's ok to leave this field undefined. ext-clones tries to calculate unique, yet reproducible default values in this case. (Random generator or sequence would not work, when persistent state is stored.)

Note: node.key and node.refKey must not be modified directly! Use the provided methods instead (like setRefKey(), reRegister(), changeRefKey()).

Options

• highlightActiveClones, type: {boolean}, optional, default: true
  Set 'fancytree-active-clone' class on active node and its peers if node has clones. (You will typically add some custom CSS, see example.)

• highlightClones, type: {boolean}, optional, default: false
  Set 'fancytree-clone' class on any node that has at least one clone. (You will typically add some custom CSS, see example.)

Events

• n.a.

Methods

• {void} tree.changeRefKey(oldRefKey, newRefKey)
  Replace a refKey with a new one.
  {string} oldRefKey
  {string} newRefKey

• {FancytreeNode[]} node.getCloneList()
  Return a list of clone-nodes or null.
  {boolean} [includeSelf=false]

• {FancytreeNode[]} tree.getNodesByRef(refKey, rootNode)
  Return all nodes with a given refKey (null if not found).
  {string} refKey
  {FancytreeNode} [rootNode] optionally restrict results to descendants of this node

• {boolean} node.isClone()
  Return true if this node has at least another clone with same refKey.

• {boolean} node.reRegister(key, refKey)
  Update key and/or refKey for an existing node.
  {string} key
  {string} refKey

• {boolean} node.setRefKey(refKey)
  Define a refKey for an existing node.
  {string} refKey

Example

In addition to jQuery, jQuery UI, and Fancytree, include jquery.fancytree.clones.js:

  <script src="//code.jquery.com/jquery-3.4.1.min.js"></script>
  <link href="skin-win8/ui.fancytree.css" rel="stylesheet">
  <script src="js/jquery-ui-dependencies/jquery.fancytree.ui-deps.js"></script>
  <script src="js/jquery.fancytree.js"></script>
  <script src="js/jquery.fancytree.clones.js"></script>

$("#tree").fancytree({
  extensions: ["clones"],
  clones: {
  },
  ...
});

Recipes

[Howto] ...