@open-pioneer/toc

This package provides a UI component that displays the map content to the user and allows them to control it.

Unavailable operational layers are marked with an icon and will be deactivated for selection. If a layer was configured as initially visible, it remains visible.

Usage

To integrate the TOC (table of contents) in your app, insert the following snippet (and reference a map):

<Toc
    map={map}
/> /* instead of passing the map, the `DefaultMapProvider` can alternatively be used */
Copy

Tools

Additional tools are available for operational layers. To show the toolset menu, set the showTools property to true.

<Toc map={map} showTools={true} />
Copy

The default tools provided by the TOC are:

• A button to hide all layers (sets visibility to false, enabled by default)
• A button to collapse all groups (enabled by default if groups are collapsible)

These tools can be configured by using the toolsConfig property.

Basemaps

By default, the TOC shows the basemap switcher as an embedded element.

To hide the basemap switcher, set the showBasemapSwitcher property to false:

<Toc map={map} showBasemapSwitcher={false} />
Copy

To configure the embedded basemap switcher, use the basemapSwitcherProps property:

<Toc
    map={map}
    basemapSwitcherProps={{
        allowSelectingEmptyBasemap: true
    }}
/>
Copy

Layer IDs as CSS classes on list items

List items for individual operational layers receive the layer's id as an additional CSS class (layer-${id}).

For example, given a layer with the ID test-geojson, the TOC's list item for that layer is rendered as:

<li class="toc-layer-item layer-test-geojson ...">
    <!-- -->
</li>
Copy

NOTE: Non-alphanumeric characters present in the layer's ID are removed from the class name. Whitespace is replaced with a single -.

NOTE: List items are not guaranteed to be rendered as li. Only the CSS class name is guaranteed.

Automatic parent layer visibility

When showing a layer via the TOC component (e.g. by clicking the checkbox next to its name), all parent layers of that layer will also be made visible by default.

This can be disabled by configuring autoShowParents={false} on the TOC component.

// Default: true
<Toc autoShowParents={false} />
Copy

Collapsible groups

The TOC renders the hierarchy of layers as a tree structure of nested lists ("groups"). Groups can be made collapsible through user action by setting the collapsibleGroups property to true. If enabled, a toggle button appears next to parent nodes by which the user can expand or collapse the group.

<Toc
    map={map}
    collapsibleGroups={true}
    initiallyCollapsed={true} // Whether groups are collapsed by default. Defaults to false.
/>
Copy

Hide certain layers in Toc

Layers that are marked as internal are not considered by the Toc.

//internal layer will not be displayed in the Toc
const internalLayer = new SimpleLayer({
    id: "layer1",
    title: "layer 1",
    olLayer: myOlLayer,
    internal: true
});
Copy

The layer's internal state also affects other UI widgets (e.g. Legend). If the layer should be hidden specifically in the Toc (but not in other widgets) the listMode attribute can be used to hide the layer item.

//use listMode to hide the layer specifically in Toc
const hiddenLayer = new SimpleLayer({
    id: "layer1",
    title: "layer 1",
    olLayer: myOlLayer,
    attributes: {
        toc: {
            listMode: "hide"
        }
    }
});
Copy

Valid values for listMode are:

• "show" layer item is displayed in Toc
• "hide" layer item is not rendered in Toc
• "hide-children" layer item for the layer itself is displayed in Toc but no layer items for child layers (e.g. sublayers of a group) are rendered

The listMode always has precedence over the layer's internal property. For example, if the listMode is "show" the layer item is displayed even if internal is true.

Using the Toc API to manipulate Toc Items programmatically

The Toc API allows programmatic access to the Toc.

Currently, the Toc API allows accessing the individual Toc items.
Toc items can be expanded/collapsed and provide access to the corresponding DOM element.

import { Toc, TocApi, TocReadyEvent } from "@open-pioneer/toc";
import { Button } from "@chakra-ui/react";

const tocApi = useRef<TocApi>(undefined);

// Expand or collapse group layer with the Toc API
function toggleTocItem(layerId: string) {
    if (!tocApi.current) {
        return; // toc not ready yet
    }

    const layerItem = tocApi.current.getItemByLayerId(layerId);
    if (!layerItem) {
        return; // item not found
    }

    console.log("Current html element", layerItem.htmlElement); // access DOM element (e.g. for scrolling)
    const newState = !layerItem.isExpanded;
    layerItem.setExpanded(newState);
}

<Toc
    // get API object from ready event and store it somewhere
    onReady={(e) => { tocApi.current = e.api; }}

    // don't use the API object after the toc has been destroyed
    onDisposed={() => { tocApi.current = undefined; }}
/>

<Button onClick={() => toggleTocItem("myGroupLayer")}>Toggle group layer</Button>
Copy

License

Apache-2.0 (see LICENSE file)