HtmlTreeMenu

A TreeMenu control that builds its entries from nested HTML lists.

Import

import { HtmlTreeMenu } from "@schukai/monster/source/components/tree-menu/html-tree-menu.mjs";

Source

View source code

Package

@schukai/monster

Since

4.62.0

Introduction

The monster-html-tree-menu renders a tree menu from nested HTML lists and matches the look and behavior of monster-tree-menu. It accepts <ul> / <li> structures and converts them into interactive entries.

Basic Usage

<monster-html-tree-menu>
  <ul>
    <li data-monster-value="root-1">Root 1
      <ul class="hidden">
        <li data-monster-value="root-1-a">Root 1 - A</li>
        <li data-monster-value="root-1-b">Root 1 - B</li>
      </ul>
    </li>
    <li data-monster-value="root-2">Root 2</li>
  </ul>
</monster-html-tree-menu>

Use data-monster-value for stable IDs; otherwise a random ID is generated.
Initial collapse is controlled via hidden or hidden class on nested lists or items.
The original list is hidden after import.

Navigation vs. Selection

If a list item contains an <a href="...">, the browser navigates. Without a link, the component treats the item as a selectable entry and fires selection events.

<li data-monster-value="docs"><a href="/docs">Docs</a></li>
<li data-monster-value="local">Local entry without page</li>

Lazy Loading

To load children on first expand, set a data-monster-endpoint on the list item. The endpoint must return HTML containing <ul>/<li> or plain <li> items.

<li data-monster-value="root-2" data-monster-endpoint="/issue-350/nodes">Root 2 (lazy)</li>

Basic HTML Tree Menu

A basic HTML tree menu rendered from nested lists. The first subtree is collapsed by marking the nested list as hidden.

Javascript

import '@schukai/monster/source/components/tree-menu/html-tree-menu.mjs';

HTML

<monster-html-tree-menu id="html-tree-menu-simple">
    <ul>
        <li data-monster-value="root-1">Root 1
            <ul class="hidden">
                <li data-monster-value="root-1-a">Root 1 - A</li>
                <li data-monster-value="root-1-b">Root 1 - B</li>
            </ul>
        </li>
        <li data-monster-value="root-2">Root 2</li>
    </ul>
</monster-html-tree-menu>

Stylesheet

/** no additional stylesheet is defined **/

Lazy Loading

This example loads the children of Root 2 on first expand using a lazy endpoint.

Javascript

import '@schukai/monster/source/components/tree-menu/html-tree-menu.mjs';

const menu = document.querySelector('#html-tree-menu-lazy');

menu.setOption('lazy.enabled', true);
menu.setOption('lazy.attribute', 'data-monster-endpoint');
menu.setOption('lazy.fetchOptions', { method: 'GET' });

HTML

<monster-html-tree-menu id="html-tree-menu-lazy">
    <ul>
        <li data-monster-value="root-1">Root 1</li>
        <li data-monster-value="root-2" data-monster-endpoint="/issue-350/nodes">Root 2 (lazy)</li>
    </ul>
</monster-html-tree-menu>

Stylesheet

/** no additional stylesheet is defined **/

Component Design

The HTML tree menu shares the same stylesheet as monster-tree-menu. Selected entries use the same rule:

[data-monster-role=entry].selected:not([data-monster-state=open])

Exported Parts

control: Wrapper around the rendered entries.
entries: Container for the generated entry list.
entry-label: Label part inside each entry.

monster-html-tree-menu::part(entry-label) {
    font-weight: 600;
}

HTML Structure

<monster-html-tree-menu></monster-html-tree-menu>

JavaScript Initialization

const element = document.createElement('monster-html-tree-menu');
document.body.appendChild(element);

Exported

HtmlTreeMenu

Derived from

CustomElement

Options

The Options listed in this section are defined directly within the class. This class is derived from several parent classes, including the CustomElement class. Therefore, it inherits Options from these parent classes. If you cannot find a specific Options in this list, we recommend consulting the documentation of the CustomElement.

Option

Type

Default

Description

templates

object

Template definitions

templates.main

string

undefined

Main template

object

classes

classes.control

string

monster-theme-primary-1

the class for the control element

classes.label

string

monster-theme-primary-1

the class for the label element

object

lazy

lazy.enabled

boolean

true

enables lazy loading by endpoint

lazy.attribute

string

data-monster-endpoint

lazy.fetchOptions

object

undefined

fetch options for lazy requests

object

features

features.selectParents

boolean

false

children

object

actions

actions.open

function

the action to open an entry (entry, index, event)

actions.close

function

the action to close an entry (entry, index, event)

actions.select

function

undefined

the action to select an entry (entry, index, event)

actions.onexpand

function

the action to expand an entry (entry, index, event)

actions.oncollapse

function

the action to collapse an entry (entry, index, event)

actions.onselect

function

the action to select an entry (entry, index, event)

actions.onnavigate

function

the action to navigate (entry, index, event)

actions.onlazyload

function

the action before lazy load (entry, index, event)

actions.onlazyloaded

function

the action after lazy load (entry, index, event)

actions.onlazyerror

function

the action on lazy error (entry, index, event)

since
deprecated

Properties and Attributes

The Properties and Attributes listed in this section are defined directly within the class. This class is derived from several parent classes, including the CustomElement class and ultimately from HTMLElement. Therefore, it inherits Properties and Attributes from these parent classes. If you cannot find a specific Properties and Attributes in this list, we recommend consulting the documentation of the CustomElement.

data-monster-options: Sets the configuration options for the collapse component when used as an HTML attribute.
data-monster-option-[name]: Sets the value of the configuration option [name] for the collapse component when used as an HTML attribute.

Methods

The methods listed in this section are defined directly within the class. This class is derived from several parent classes, including the CustomElement class and ultimately from HTMLElement. Therefore, it inherits methods from these parent classes. If you cannot find a specific method in this list, we recommend consulting the documentation of the CustomElement.

Behavioral methods

closeEntry(value)

Parameters

value {string}: value

Returns

{void}

Close a node by value.

hideEntry(value)

Parameters

value {string}: value

Returns

{void}

Hide a node by value.

openEntry(value)

Parameters

value {string}: value

Returns

{void}

Open a node by value.

removeEntry(value)

Parameters

value {string}: value

Returns

{void}

Remove a node by value.

showEntry(value)

Parameters

value {string}: value

Returns

{void}

Show a node by value.

State query methods

findEntry(value)

Parameters

value {string}: value

Returns

{Object|null}

Find an entry by value.

Static methods

[instanceSymbol]()

Returns

{symbol}

This method is called by the instanceof operator.

getCSSStyleSheet()

Returns

{CSSStyleSheet[]}

getTag()

Returns

{string}

Lifecycle methods

Lifecycle methods are called by the environment and are usually not intended to be called directly.

[assembleMethodSymbol]()

Returns

{void}

Other methods

collapseEntry(value)

Parameters

value {string}: value

Returns

{void}

Collapse a node and all its descendants by value.

expandEntry(value)

Parameters

value {string}: value

Returns

{void}

Expand a node and all its descendants by value.

insertEntry(entry,)

Parameters

entry {object}: entry
undefined {string|null}: parentValue

Returns

{void}

Insert a node.

insertEntryAfter(entry,referenceValue)

Parameters

entry {object}: entry
referenceValue {string}: referenceValue

Returns

{void}

Insert a node after a reference entry.

insertEntryBefore(entry,referenceValue)

Parameters

entry {object}: entry
referenceValue {string}: referenceValue

Returns

{void}

Insert a node before a reference entry.

selectEntry(value)

Parameters

value {string}: value

Returns

{void}

Select an entry by value.

Events

The component emits the following events:

entries-imported

For more information on how to handle events, see the mdn documentation.

The current width of the area is too small to display the content correctly.