ExtFilter

About Fancytree filter extension.

• Status: production
• example

Allow to dimm or hide nodes based on a matching expression.

Note: This plugin might not work as expected if the node titles contain HTML markup.

Options

Note: Some of these options can be overriden in the options argument of filterNodes() / filterBranches().

• autoApply, type: {boolean}, default: true
  Re-apply last filter if lazy data is loaded.

• autoExpand, type: {boolean}, default: false
  Temporarily expand matching node parents while filter is active.

• counter, type: {boolean}, default: true
  Show a badge with number of matching child nodes near parent icons.

• fuzzy, type: {boolean}, default: false
  Match single characters in order, e.g. 'fb' will match 'FooBar'.

• hideExpandedCounter, type: {boolean}, default: true
  Hide counter badge, when parent is expanded.

• hideExpanders, type: {boolean}, default: false
  Hide hideExpanders expanders if all child nodes are hidden by filter.

• highlight, type: {boolean}, default: true
  Highlight matches by wrapping inside tags.
  Note that this only works if filter is passed as a string, but not when a custom matcher callback is used.

• leavesOnly, type: {boolean}, default: false
  Match end nodes only.

• mode, type: {string: 'dimm' | 'hide'}, default: 'dimm'
  Defines if unmatched nodes are grayed out or hidden.

• nodata, type: {boolean|string|object|function}, default: true
  Display a status node if the filtered tree would be empty.
  A string will be used as title, but also a NodeData object or a callback is accepted.
  This option is ignored if mode is 'dimm'.

Events

(n.a.)

Methods

• {void} tree.clearFilter()
  Reset the filter.

• {integer} tree.filterBranches(filter, opts)
  Dimm or hide unmatched branches. Matching nodes are displayed together with all descendants.
  Note: another way to achieve this behavior is to use tree.filterNodes() and return "branch" in response of the matcher-callback
  filter: {function | string}
opts {object}, default: Use global filter options.

• {integer} tree.filterNodes(filter, opts)
  Dimm or hide unmatched nodes.
  filter: {function | string}
opts {object}, default: Use global filter options.

• {integer} tree.updateFilter() @since 2.38
  Re-apply the current filter. This method can be called after modifying operations (e.g. addNodes()).

Example

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

  <script src="//code.jquery.com/jquery-3.6.0.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.filter.js"></script>

$("#tree").fancytree({
  extensions: ["filter"],
  filter: {  // override default settings
    counter: false, // No counter badges
    mode: "hide"  // "dimm": Grayout unmatched nodes, "hide": remove unmatched nodes
  },
  ...
});
// Case insensitive search for titles containing 'foo':
$.ui.fancytree.getTree("#tree").filterNodes("foo");

// Pass additional options in order to override the default behavior:
$.ui.fancytree.getTree("#tree").filterNodes("foo", {autoExpand: true, leavesOnly: true});

For more complex searches, we can pass a compare function instead of a string. The matcher callback should return a truthy value in order to display a node.

var rex = new RegExp("foo", "i");

$.ui.fancytree.getTree("#tree").filterNodes(function(node) {
  return rex.test(node.title);
});

$.ui.fancytree.getTree("#tree").filterNodes(function(node) {
  return node.data.customFlag === true;
});

We can match whole branches too, i.e. matching nodes include all descendants:

$.ui.fancytree.getTree("#tree").filterBranches(function(node) {
  return node.key === "abc";
});

The matcher callback can return the special values "skip" and "branch". This allows to mix branch-mode and simple-mode:

var rex = new RegExp("foo", "i");

$.ui.fancytree.getTree("#tree").filterNodes(function(node) {
  var match = rex.test(node.title);

  if( match && node.isFolder() ) {
    return "branch";  // match the whole 'Foo' branch, if it's a folder
  } else if( node.data.ignoreMe ) {
    return "skip";  // don't match anythin inside this branch
  } else {
    return match;  // otherwise match the nodes only
  }
});

Recipes

[Howto] Highlight matches for custom filters

Automatic highlighting only works for string arguments. If a custom matcher callback is used, Fancytree cannot figure out what part caused a match, but we can set 'node.titleWithHighlight' explicitly to a string that contains <mark> tags:

tree.filterNodes(function(node) {
  if( rex.test(node.title) ) {
    node.titleWithHighlight = "<mark>" + node.title + "</mark>";
    return true;
  }
}
});

Another example found here.

[Howto] Customize Match Styling

Highlight markers can be styled like this:

.fancytree-ext-filter span.fancytree-title mark {
  background-color: #E09090;
}