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);

Parameter	Type	Description
container	Element	Container element for finder
data	Array|Function	Data source can be an array or function
options	Object	Configure classNames, item rendering, etc

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:

Event	Description
item-selected	An item was selected (clicked or keyboard arrow)
leaf-selected	A leaf node was selected
interior-selected	An interior node was selected
create-column	Append a column to the container
column-created	A column was appended to the container
navigate	Navigate the finder by going up, down, right, or left
go-to	Specify a path to programmatically "go to". Accepts a string or array, e.g. path/file.txt or ['path', 'file.txt']

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

Option	Type	Description
className	Object	Override the default classnames by populating this object
labelKey	string	Override the data key used to render labels. Defaults to label.
childKey	string	Override the data key used to populate children. Defaults to children.
createItemContent	Function	Define how each item is rendered. The first parameter passed in is the config object and the second is the item object that is currently being iterated on. It should return an HTML Element.
defaultPath	string or array	Specify path to preselect on load. E.g. path/file.txt or ['path', 'file.txt'].

Project commands

Command	Description
npm install	Install dependencies into node_modules/
make build	Build finderjs and example
make install	Clears node_modules and installs
make clean	Remove build and coverage data
make lint	Lint files
make test	Run tests
make cover	Run coverage tests
make watch in=<file> out=<file>	Watchify a file