Basic

Introducing

API provides a set of functions for advanced work with the tree: add/remove tree node, searching, changing state and so on.

It is divided into 2 parts for several reasons:

• for reducing the weight of the component

• a separate API has more features that are not very often needed in the work

Connection

The connection of the API is very easy. The component has a property onReady. It calls right after componentDidMount call. The API object is passed as the first argument to the onReady function.

class AwesomeComponent extends React.PureComponent {
    treeApi = null
    
    handleTreeReady = (treeApi) => {
        this.treeApi = treeApi
    }
    
    render() {
        return <EyzyTree 
            data={data}
            onReady={this.handleTreeReady}
        />
    }
}

Methods

Most methods accept a Query argument. Full description: Query

find

• Description: Finds nodes by specified Query

• Arguments:

  • query: Query

• Returns:

  • TreeNode

  • null if node is not found

• Usage:

const awesomeNode = this.treeApi.find({text: 'Awesome Node'})

findAll

• Description: Similar to find method. But it returns all found nodes.

• Arguments:

  • query: Query

• Returns:

  • Array<TreeNode>

• Usage:

const expandedNodes = this.treeApi.findAll({expanded: true})

selected

• Description: Returns selected nodes. Simple.

• Returns: Result can be different depends on mode (multiple or single). See Component props

  • Single mode: TreeNode or null

  • Multiple mode: array of TreeNode. It will be always an array.

• Usage:

Single mode:

const selectedNode = this.treeApi.selected()

this.setState({
    selectedNodeText: selectedNode ? selectedNode.text : 'Please select a node'
})

Multiple mode:

For a tree in multi-selection mode the selected method returns always an array. It does not matter if the selected nodes or not.

<EyzyTree 
    data={data}
    multiple={true}
/>

const selectedNodes = this.treeApi.selected()

this.setState({
    selectedNames: selectedNodes.map(node => node.text).join(', ')
})

checked

• Description: For checkable mode the library will combine checked nodes into an array. There are different ways to select "checked" nodes by using valueConsistsOf argument.

  • ALL (default) it will gather all "checked" nodes

  • BRANCH if node has children and it is checked (and all of the children nodes are checked) then all children nodes will be excluded from the result

  • LEAF returns nodes which doesn't has children nodes

  • WITH_INDETERMINATE the same as ALLplus indeterminate nodes

• Arguments:

  • valueConsistsOf: 'ALL' | 'BRANCH' | 'LEAF' | 'WITH_INDETERMINATE'

  • showDisabled: boolean (default false)

• Returns:

  • Array<TreeNode>

• Usage:

const checkedBranches = this.treeApi.checked('BRANCH')

set

It is not recommended to use this method.

• Description: Set any property to node. This method use find method from the API. So it will apply changes only for the first match.

• Arguments:

  • criteria Find criteria

  • propName: node of a property (ex: expanded, disabled and so on)

  • propValue

• Returns:

  • boolean

• Usage:

this.treeApi.set({expanded: false}, 'expanded', true)

To apply changes for all matches use next snippet:

const checkedNodes = this.treeApi.findAll({checked: true})

checkedNodes.forEach(node => {
    this.treeApi.set(node.id, 'checked', true)
})

data

You can store here whatever you want.

• Description: It is getter/setter for the data property of the node.

• Arguments:

  • query: Query

  • key: string | object

  • value : any (not required)

• Returns:

  • undefined

  • data object

  • TreeNode

• Usage:

// tree data
const data = [
    { text: 'Item 1', data: { isSuper: true } },
    { text: 'Item 2' },
    { text: 'Item 3' }
]

// it will find the first item (!)
this.treeApi.data(/Item/, 'isSuper', false)
// or
// data is instead extended by shallow merge
// node.data will be { isSuper: false, isSuper2: false }
this.treeApi.data(/Item/, { isSuper2: false })

This method has different return results

// tree data
const data = [
    { text: 'Item 1', data: { isSuper: true } },
    { text: 'Item 2' },
    { text: 'Item 3' }
]

// return a value: value
this.treeApi.data(/Item/, 'isSuper')

// get full data object: { isSuper: true, isSuper2: 'string' }
this.treeApi.data(/Item/)

// setter: return TreeNode
this.treeApi.data(/Item/, { isSuper2: false })

// setter: return TreeNode
this.treeApi.data(/Item/, 'isSuper2', 'string')

addClass

• Description: It will add classNames for the node. This class will be added to the node with the class .node-content (check Node's structure)

• Arguments:

  • query: Query

  • Array<className>: string[]

• Returns:

  • TreeNode if node is found

  • null if node is not found

• Usage:

this.treeApi.addClass(/excess/, ['excess-node', 'you-can', 'pass', 'many', 'names'])

removeClass

• Description: The same behavior as addClass method, but it removes classNames

• Arguments:

  • query: Query

  • Array<className>: string[]

• Returns:

  • TreeNode if node is found

  • null if node is not found

• Usage:

this.treeApi.removeClass(/excess/, ['excess-node', 'you-can', 'pass', 'many', 'names'])

hasClass

• Description: Checks if a node has a className

• Arguments:

  • query: Query

  • className: string

• Returns:

  • boolean

• Usage:

const hasClass = this.treeApi.hasClass(/excess/, 'highligted')

append

• Description: Inserts nodes to the end of the matched node

• Arguments:

  • query: Query

  • nodes: string | object | Promise

  • opts: Insertion options

• Returns:

  • Promiselike<TreeNode[]> added nodes (always an array)

  • null if node is not found

• Usage:

const appendedNodes = this.treeApi.append(
    'Item 1', // find criteria
    ['Item 1.1.', 'Item 1.2'], // nodes can be as string
    true // expand node with text 'Item 1' (if node was found)
)

this.treeApi.append(
    { selected: true },
    [
        { text: 'Selected children 1', disabled: true },
        { text: 'Selected children 2' }        
    ]
)

// it also can be a function, but it must return a Promise
this.treeApi.append(
    'Selected children 2',
    (node) => {
        // node.text === 'Selected children 2'
        return fetch(`/api?childName=${node.text}`)
            .then(response => response.json())
    }
)

prepend

• Description: This method is similar to append. But nodes inserting to the beginning of children list. (well ... you know, as well as jQuery :) )

• Example:

// tree structure
/**
item 1
item 2
 item 2.1
 item 2.2
item 3
*/

this.treeApi.append('item 2', [
 'item 2.3', 'item 2.4', { text: 'item 2.5', checked: true }
])

// will be:
/**
item 1
 item 2.3    << new node
 item 2.4    << new node
 item 2.5    << new node
 item 2.1
 item 2.2
item 2
item 3
*/

before

• Description: This method is similar to append. But nodes inserting before matched node.

• Example:

// tree structure
/**
item 1
item 2
item 3
*/

this.treeApi.before(/item 2/, 'item n')

// will be:
/**
item 1
item n <<<<<<< -- added node
item 2
item 3
*/

after

• Description: This method is similar to append. But nodes inserting after matched node.

// tree structure
/**
item 1
item 2
item 3
*/

this.treeApi.before(/item 2/, 'item n')

// will be:
/**
item 1
item 2
item n <<<<<<< -- added node
item 3
*/

remove

• Description: It removes matched node.

• Arguments:

  • query: Query

• Returns:

  • TreeNode removed node

  • null if node is not found

• Usage:

const removedNode = this.treeApi.remove(/bad node/)

if (removedNode) {
    alert(`Congrat... node(${removedNode.id} has removed!`)
}

uncheckAll

• Description: Set for all checked nodes unchecked states

unselectAll

• Description: Removes selection for all selected nodes

toArray

• Description: Returns list of nodes.