finderjs v1.3.0

finderjs

Finder-like UI component for viewing hierarchical content in columns.

Demo:

http://mynameistechno.github.io/finderjs/

React

The engineering team at AndcultureCode has written a React wrapper for finderjs! Check it out:

https://github.com/AndcultureCode/react-finderjs

Installation

npm install finderjs

Usage

Use it as a CommonJS module, as a standalone script, or as a jQuery plugin. Roll your own CSS or feel free to use the styling in example/finderjs.css, which leverages flexbox.

In its simpelst form:

var f = finder(container, data, options);

Data

The hierarchical data is represented with nested arrays. A data source can be an array or a function that executes a callback with the data (an array). This is handy for asynchronous data, such as a remote web service.

Source is an array

Each item in the array itself should be an object. When the data source is an array, each object that doesn't contain a children property is considered a leaf node. When a leaf node is selected, the leaf-selected event will be emitted. When present, the value of the children property should be an array. When a node has children and it is selected, it will use the children to populate the next column.

var container = document.getElementById('container');
var data = [
  {
    label: 'Item 1',
    children: [
      {
        label: 'Item 1A',
        children: [
          {
            label: 'Item 1A1'
          }
        ]
      },
      {
        label: 'Item 1B'
      }
    ]
  }
];
var options = {};

var f = finder(container, data, options);

f.on('leaf-selected', function(item) {
  console.log('Leaf selected', item);
});

See this example for more details.

Source is a function

When the data source is a function there is no need for the children property. This function will be called on every selection and will pass along the selected item. A callback is provided and should be called only if there are children for a new column.

var container = document.getElementById('container');
var options = {};

/**
 * This function will be called on load and on every selection.
 * @param  {Object}   parent - item that was selected
 * @param  {Object}   cfg    - config object
 * @param  {Function} callback - call this with the data (Array)
 */
function remoteSource(parent, cfg, callback) {
  var children = [...];

  if (children.length) {
    callback(children);
  }
}

var f = finder(container, remoteSource, options);

See this example for more details.

Notes

If an object has a url property it will be treated slightly differently: the anchor tag that wraps the item will have the href attribute assigned to it. Upon selection of this item the browser will be redirected to the provided URL.

Events

finder will return an EventEmitter which allows you to listen to (and emit) the following events:

Note that for historical reasons, leaf-selected and interior-selected receive the node object from the data model, while item-selected receives the DOM elements for the column and item selected.

See the examples for more details.

Options

Project commands