NEWTON CHECKBOX TREE
Overview
Newton Checkbox Tree component renders a tree of items that contain configurable checkboxes, icons, labels and events. The component is extensible and customizable at the global and individual node level. The style used within the component is implemented with IBM Carbon Design System framework.
The build, test, serve, package and deploy tasks use modern tooling and practices with Parcel, Jest, Enzyme, Storybook and Babel. All of the tasks are extrememly simple to execute which allows for excellent development environment.
This component is part of the Newton Component family. Eventually it will be moved into the Newton Common Component library.
Development
Setup Local Environment
Quick overview for getting your local development environment setup for development, browsing and publishing. Below are all of the commands needed to build, test, run and publish the component.
Clone Repository
git clone https://git.rocketsoftware.com/scm/nwtn/newton-common-components.git
Commands
CLEAN
clean
- Deletes dist, demo, build, cache and storybook foldersclean:dist
- Deletes dist folderclean:demo
- Deletes demo folderclean:build
- Deletes build folderclean:cache
- Deletes cache folderclean:storybook
- Deletes storybook folder
DEMO
demo:start
- Run demo in the browserdemo:build
- Bundle demo applicationdemo:publish
- Deploy demo to gh-pages branch
BUILD
build
- Transpile scss and javascript for productionbuild:css
- Transpile scss to css for productionbuild:commonjs
- Transpile javascript to commonjs for productionbuild:esmodules
- Transpile javascript to esmodule for production
EXAMPLES
start:dev
- Run demo in the browser with original sourcestart:prod
- Run demo in the browser with production bundlestart:examples:*
- Run specified demo in the browser. Replace the * with the name of the demo.
TESTS
test
- Run teststest:details
- Run tests with detailstest:coverage
- Run tests with code coveragetest:snapshot:cleanup
- Remove old outdated snapshots prior to running tests
STORYBOOK
storybook
- Run storybook stories in browserstorybook:build
- Build storybook stories
ANALYZE
analyze:build
- Bundle source map for analyzeranalyze:view
- View application depenendency tree and bundle size
How To Use
Install Library
Add the component to your React application with npm or yarn.
Using yarn:
yarn add newton-checkbox-tree
Using npm:
npm install newton-checkbox-tree --save
Note – This library makes use of Font Awesome styles and expects them to be loaded in the browser.
Include Stylesheet
For your convenience, the library's styles can be consumed utilizing one of the following files:
newton-checkbox-tree/dist/css/newton-checkbox-tree.css
newton-checkbox-tree/dist/scss/newton-checkbox-tree.scss
Either include one of these files in your stylesheets or utilize a CSS loader:
;;
Render Component
A quick usage example is included below. Note that the newton-checkbox-tree component is controlled. In other words, it is stateless. You must update its checked
and expanded
properties whenever a change occurs.
import React from 'react';import CheckboxTree from 'newton-checkbox-tree';import 'newton-checkbox-tree/dist/scss/newton-checkbox-tree.scss';const nodes =id: '12345'label: 'users'category: 'table'children:id: '1000' label: 'name' category: 'field'id: '1001' label: 'address' category: 'field';Componentstate =checked:expanded:;{return<CheckboxTree=====/>;}
All node objects must have a unique id
. This id is serialized into the checked
and expanded
arrays and is also used for performance optimizations.
Change Default Icons
By default, newton-checkbox-tree uses Font Awesome for the various icons that appear in the tree. To change the defaults, simply pass in the icons
property and override the defaults. Note that you can override as many or as little icons as you like:
<CheckboxTree...=/>
If you are using the react-fontawesome
library, you can also directly substitute those icons:
import FontAwesomeIcon from '@fortawesome/react-fontawesome'...<CheckboxTree...=/>
Component Properties
Property | Type | Description | Default |
---|---|---|---|
nodes |
array | Required. Specifies the tree nodes and their children. | |
checked |
array | An array of checked node values. | [] |
disabled |
bool | If true, the component will be disabled and nodes cannot be checked. | false |
expandDisabled |
bool | If true, the ability to expand nodes will be disabled. | false |
expandOnClick |
bool | If true, nodes will be expanded by clicking on labels. Requires a non-empty onClick function. |
false |
icons |
object | An object containing the mappings for the various icons and their components. See Changing the Default Icons. | { ... } |
id |
string | A string to be used for the HTML ID of the rendered tree and its nodes. | null |
expanded |
array | An array of expanded node values. | [] |
lang |
object | An object containing the language mappings for the various text elements. | { ... } |
name |
string | Optional name for the hidden <input> element. |
undefined |
nameAsArray |
bool | If true, the hidden <input> will encode its values as an array rather than a joined string. |
false |
nativeCheckboxes |
bool | If true, native browser checkboxes will be used instead of pseudo-checkbox icons. | false |
noCascade |
bool | If true, toggling a parent node will not cascade its check state to its children. | false |
onCheck |
function | onCheck handler: function(checked, targetNode) {} |
() => {} |
onClick |
function | onClick handler: function(targetNode) {} . If set, onClick will be called when a node's label has been clicked. |
() => {} |
onExpand |
function | onExpand handler: function(expanded, targetNode) {} |
() => {} |
onlyLeafCheckboxes |
bool | If true, checkboxes will only be shown for leaf nodes. | false |
optimisticToggle |
bool | If true, toggling a partially-checked node will select all children. If false, it will deselect. | true |
showExpandAll |
bool | If true, buttons for expanding and collapsing all parent nodes will appear in the tree. | false |
showNodeIcon |
bool | If true, each node will show a parent or leaf icon. | true |
showNodeTitle |
bool | If true, the label of each node will become the title of the resulting DOM node. Overridden by node.title . |
false |
onCheck
and onExpand
onCheck and onExpand events must be implemented in your React component in order to update newton checkbox tree checked and expanded state. Clicking the checkbox or clicking the expand icon will not update the components state due to the fact that its a stateless component.
Node Properties
Individual nodes within the nodes
property can have the following structure:
Property | Type | Description | Default |
---|---|---|---|
id |
mixed | Required. The node's unique id. | |
label |
mixed | Required. The node's label. | |
category |
string | The node's category. | null |
children |
array | An array of child nodes. | null |
className |
string | A className to add to the node. | null |
disabled |
bool | Whether the node should be disabled. | false |
icon |
mixed | A custom icon for the node. | null |
showCheckbox |
bool | Whether the node should show a checkbox. | true |
showIcon |
bool | Whether the node should show an icon. | true |
title |
string | A custom title attribute for the node. |
null |