Tree

Form integration of the Tree component.

NOTE

The Tree component has already been covered in this part of the documentation. Here we'll only look at the specifics of the form component. For the base usage of tree, please refer to its documentation.

Basic usage

A bt-form-tree works for the most part just like a bt-tree. It adds a checkbox for each level to make it selectable. Selecting a level will select all the sub levels. Here is an example:

As you can see, there are two differences from a normal Tree:

Like any other form component, it expects either a form control (control="..") or a variable (v-model="..") to hold the value.
A nodes-value prop is used to define the name of the property to use as value for the form control.

Node value

By default, if nodes-value is not defined, so the original object describing the node is used as value. For example:

As you can see, a new value-identifier prop has been added. This is because the form control now receive an array of objects as value because no value is defined for nodes-value.

In our example, we preselect the node Node 1.1.2 by doing:

public selected: any[] = [{id: 4}];

But {id: 4} is not the same object as the one declared in content ({id: 4, label: 'Node 1.1.2'}).

This could work though, because the tree does compare the objects deeply, so if we add the label it would work:

public selected: any[] = [{id: 4, label: 'Node 1.1.2'}];

Both objects must be strictly equal though, which is unpractical. And more importantly, it can be very slow if you have many big objects.

That's why value-identifier exists. You are not forced to use it, but it's a better practice. Its role is to uniquely identify each node with a

Primitive

value that can be easily compared by the tree.

TIP

Like all these kind of props, value-identifier can take a function that will be called for each node, and that must return the value to use for comparison:

<bt-form-tree [...] :value-identifier="(n) => n.id"></bt-form-tree>

Excluding values

In our previous example, you can see that the whole object is used as a value. Even the children, if the node has some.

What if we only want nodes with no children to contribute to the form's value?

You can control this behavior via nodes-value. If you say for example, that the property to use as value is value, if a node has no value attribute defined, nothing will be added to the form control when selected. Here is an example:

But as you can see, if we want the label as value like we do above, we have to copy this new value attribute, so we can differentiate the nodes. Annoying.

You can workaround this issue by giving a function to nodes-value and test if the node has children. If not, returning undefined will prevent the tree from adding a value for this node.

It works the same, but we only have one label in our tree 🙂.

Props

Method	Description	Default
v-model	Bidirectional binding for the value of the control.	`undefined`
value	The original value given by the end-user through the html element.	`undefined`
label	The label of the field. Overridden by the `default` slot.	`null`
placeholder	A placeholder value to show when there is no value selected.	`null`
help	A help text to show to the user. Overridden by the `help` slot.	`null`
floating-errors	If `true` the errors will appear as an icon on the right side of the input that shows a popover. This value is overridden to `true` internally if the control is in a group to preserve layout integrity.	`true`
floating-help	If `true` the help text will appear as an icon on the right side of the input that shows a popover. This value is overridden to `true` internally if the control is in a group to preserve layout integrity.	`false`
required	If `true`, a little asterisk extra is shown, indicating to the user that the field is mandatory.	`false`
disabled	For external control of the `disabled` state of the control.	`false`
busy	For external control of the `busy` state of the control.	`false`
debug	If `true`, show the debug overlay.	`false`
tab-index	HTML tab index (for keyboard navigation).	`0`
autofocus	If `true`, the control will try to gain focus when mounted.	`false`
nodes-value	Defines how to resolve the nodes' value. Can be: the name of the property to use when the input is an object, a function that takes the raw input and returns the value to use, `null` to use the original value of the node.	`null`
value-identifier	Define the name of the property (or get the value if a function) to use as identifier for the value. Required if the value is not a primitive because a primitive is required to preselect items of the tree from the value of the `FormControl`.	`null`

Slots

Name Description

Name	Description
default or label	Defines the label of the field. This slot takes priority over the `label` prop. Props: none
help	Defines the help text of the field. This slot takes priority over the `help` prop. Props: none
node	Slot that is rendered for each node of the tree. Props: node : the actual Node instance for the node. toggle : a function you can call to inverse the collapsed state of the node. expand : a function you can call to show the children of the node. collapse : a function you can call to hide the children of the node. remove : a function you can call to remove the node and its children from the tree.

default or label

Defines the label of the field. This slot takes priority over the label prop.

Props: none

help

Defines the help text of the field. This slot takes priority over the help prop.

Props: none

node

Slot that is rendered for each node of the tree.

Props:

node
: the actual Node instance for the node.
toggle
: a function you can call to inverse the collapsed state of the node.
expand
: a function you can call to show the children of the node.
collapse
: a function you can call to hide the children of the node.
remove
: a function you can call to remove the node and its children from the tree.

Theming

Below the list of all CSS variables and selectors available to customize the appearance of the component. If you're not familiar on how the theming works, please refer to the VueThemes documentation.

Variables

Variable	Default	Comment
fontFamily	`var(--bt-font-family-base)`	-
fontSize	`var(--bt-font-size-base)`	-
fontWeight	`var(--bt-font-weight-normal)`	-
textColor	`var(--bt-text-color-base)`	-
helpTextColor	`var(--bt-text-color-light)`	-
helpFontSize	`var(--bt-font-size-sm)`	-
errorTextColor	`var(--bt-color-red-500)`	-
errorFontSize	`var(--bt-font-size-sm)`	-
disabledOpacity	`0.5`	-
addonBackgroundColor	`var(--bt-color-gray-50)`	-
addonTextColor	`var(--bt-text-color-light)`	-

Selectors

Name	Comment
root	The root container.
label	The container of the label.
help	The container of the help text.
inputGroup	A container that only include the form field.
input	The actual form control.
item	The individual container of each node.
itemsWrapper	The container a single level of the tree.
itemTitle	Title of a node.
itemAddon	The icon that appear on the left of a node.

Examples:

cssSelectors: {
    item: {
        background: '...'
    },
    'item:hover': {
        background: '...'
    }
}

# Tree

# Basic usage

# Node value

# Excluding values

# Props

# Slots

# Theming

# Variables

# Selectors