Skip to content

mynameistechno/finderjs

Repository files navigation

npm version Build Status Code Climate Test Coverage

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 simplest 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