toolset

Registered tool components can be arranged by toolsets. An app can contain multiple toolsets. Each toolset configuration defines which tools are included.

Usage

No configuration is needed. Default values are applied.

A toolset is basically a container for tools. It may also contain sub-toolsets, for example for drop-down menus and sub-menus. Different styles are available for a tool (window, drop-down, drawer, ...).

Each component that provides the ct.tools.Tool interface and defines a tool role toolset is injected to the ToolsetManager component automatically. Based on the ID of the injected tool the ToolsetManager assigns the tool to the toolset that defines the corresponding ID. After the tool is displayed, it is rendered as a tool button displaying its icon and/or title. If no toolset configuration is provided a default toolset is registered that contains all available tools.

Use Cases

How to configure a toolset

The following app.json file excerpt shows a toolset sample configuration using the ToolsetManager component:

"toolset" : {
    "ToolsetManager": {
        // each array entry defines a toolset and references the containing tools by their ids
        "toolsets": [
            {
                "id": "default_tools",
                "title": "My Default Tools",
                "tools": ["parametermanager", "measurement-2d", "locateme"],
                "container": "map",

                // the following properties are optional
                "windowType": "floating",
                "window": {
                    // allow closing the toolset window
                    "closable": true
                },
                "position": {
                    "rel_l": 150,
                    "rel_t": 250
                }
            }
        ]
    }
}

Providing default tooltipPositions for all tools in a toolset

Configuring the tooltipPositions property on a toolset provides that value as a default value for all tools in that toolset. If a tool has an explicit tooltipPositions value, that value takes precedence. The order of values in the array determines the sequence of positions relative to the tool in which the tooltip tries to render, depending on the available space.

Sample for app.json:

{
    "toolset": {
        "ToolsetManager": {
            "toolsets": [
                {
                    "id": "mapview_tools",
                    "tools": [
                        "locateMeTool",
                        "zoomInTool",
                        "zoomOutTool",
                        "compassTool",
                        "restoreInitialViewTool",
                        "viewmodeSwitcherTool"
                    ],
                    "registerWidget": {
                        "widgetRole": "mapview_tools"
                    },
                    "container": "ignore",
                    "windowType": "container",
                    "cssClass": "muted",
                    "tooltipPositions": [
                        "before",
                        "above",
                        "below",
                        "after"
                    ]
                }
            ]
        }
    }
}

Toolset types

There are multiple types of toolsets available in map.apps. The following snippets are samples of how to configure the different types through the app.json file's toolset section.

floating toolset

A floating toolset generates a movable toolset window with a title bar. This is the default type.

{
    "id": "my_toolset",
    "title": "My Toolset",
    "tools": ["myTool1", "myTool2"],
    "container": "map",
    "windowType": "floating",
    "position": {
        "rel_l": 150,
        "rel_t": 250
    }
}

fixed toolset

A fixed toolset is similar to the floating toolset without the ability of being able to be moved.

{
    "id": "my_toolset",
    "title": "My Toolset",
    "tools": ["myTool1", "myTool2"],
    "container": "map",
    "windowType": "fixed",
    "position": {
        "rel_l": 150,
        "rel_t": 250
    }
}

A dropdown toolset generates a drop-down button showing the title and containing all assigned tools.

{
    "id": "my_toolset",
    "title": "My Toolset",
    "tools": ["myTool1", "myTool2"],
    "container": "map",
    "windowType": "dropdown",
    "position": {
        "rel_l": 150,
        "rel_t": 250
    }
}

collapsed toolsets (left_collapsed, right_collapsed, top_collapsed, bottom_collapsed)

A collapsed toolset is reduced to a single button. When being clicked it uncollapses to the configured direction, for example a left_collapsed toolset opens to the right.

{
    "id": "my_toolset",
    "title": "My Toolset",
    "tools": ["myTool1", "myTool2"],
    "container": "map",
    // optional property to define what happens with toolset after clicking a tool. Default value is false
    "collapseAfterToolClick": false,
    "windowType": "left_collapsed",
    "position": {
        "rel_l": 150,
        "rel_t": 250
    }
}
{
    "id": "my_toolset",
    "title": "My Toolset",
    "tools": ["myTool1", "myTool2"],
    "container": "map",
    "windowType": "right_collapsed",
    "position": {
        "rel_l": 150,
        "rel_t": 250
    }
}
{
    "id": "my_toolset",
    "title": "My Toolset",
    "tools": ["myTool1", "myTool2"],
    "container": "map",
    "windowType": "top_collapsed",
    "position": {
        "rel_l": 150,
        "rel_t": 250
    }
}
{
    "id": "my_toolset",
    "title": "My Toolset",
    "tools": ["myTool1", "myTool2"],
    "container": "map",
    "windowType": "bottom_collapsed",
    "position": {
        "rel_l": 150,
        "rel_t": 250
    }
}

tooltip_dialog toolset

A tooltip_dialog toolset generates a menu button. When being clicked it opens a dialog around the buttons position containing all assigned tools.

{
    "id": "my_toolset",
    "title": "My Toolset",
    "tools": ["myTool1", "myTool2"],
    "container": "map",
    "windowType": "tooltip_dialog",
    "position": {
        "rel_l": 150,
        "rel_t": 250
    }
}

drawer toolsets

A drawer toolset creates a button that opens a drawer from the left (drawer_left) or right (drawer_right).

{
    "id": "my_toolset",
    "title": "My Toolset",
    "tools": ["myTool1", "myTool2"],
    "container": "map",
    "windowType": "drawer_left",
    // optional background color opacity
    "backgroundOpacity": 0.7,
    // optional width of the drawer
    "drawerSize": 350,
    // optional icon shown in front of the title
    "iconClass":"icon-house",
    // optional footer text shown at the bottom of the drawer
    "footerText":"\u00A9 2017 My Awesome Company",
    "position": {
        "rel_l": 150,
        "rel_t": 250
    }
}

A menubar toolset generates a menubar. It may contain tools and menubaritems.

{
    "id": "my_toolset",
    "tools": ["myTool1", "myTool2", "mySubMenu"],
    "container": "map",
    "position": {
        "rel_l": 150,
        "rel_t": 250
    },
    "windowType": "menubar"
}, {
    "id": "mySubMenu",
    "title": "My Sub-Menu",
    "tools": ["myTool3", "myTool4"],
    "container": "ignore",
    "registerTool": true,
    "windowType": "menubaritem"
}

A menu toolset is similar to the menubar but generates a vertical menu. It may contain tools and menuitems.

{
    "id": "my_toolset",
    "tools": ["myTool1", "myTool2", "mySubMenu"],
    "container": "map",
    "position": {
        "rel_l": 150,
        "rel_t": 250
    },
    "windowType": "menu"
}, {
    "id": "mySubMenu",
    "title": "My Sub-Menu",
    "tools": ["myTool3", "myTool4"],
    "container": "ignore",
    "registerTool": true,
    "windowType": "menuitem"
}

Further toolset properties

Further properties can be used with the toolset definition

Handler Description
tooltip Creates a tooltip for the toolset (not supported by all types)
tooltipPositions An array of tooltip positions (e.g. ["before", "above", "below", "after"]). When present, this is passed to tools that do not provide their own tooltipPositions.
cssClass Assign a CSS class to a toolset for customization.
Some predefined classes can be used:
showToolLabels shows labels next to the icons - not for menu & menubar
dockingBarStyle applies the same styling for toolset as for windowDockingBar. Works best for toolsets inside the footer bar.
notitle hides the title of a window toolset.
max_horizontal Number of tools in a row (not supported by all types)

Using tools in other toolsets

To activate a toolset by clicking a tool in another toolset, register the toolset as a tool itself.

To register a tool for a toolset, add the following property to the toolset definition:

"registerTool": true

To define tool properties such as an icon class or a tooltip, assign an object to the property:

"registerTool": {
    "iconClass": "icon-house",
    "tooltip": "My Tooltip"
}

Reference an existing tool for show/hide of a toolset

The property activationTool enables the connection of a toolset to an existing tool. The toolset is only shown if the referenced tool is activated.

"activationTool": 'a-tool-id'

How to place a toolset directly into an attach point

Toolsets can also be registered directly as a widget for being placed at an arbitrary position in the layout-template.

Therefore register the toolset with a custom widgetRole in the app.json file:


"toolset": {
    "ToolsetManager": {
        "toolsets": [
            {
                "id": "my_toolset",
                "title": "My Toolset",
                "tools": ["myTool1", "myTool2"],
                "container": "ignore",
                "windowType": "container",
                "registerWidget": {
                    "widgetRole": "my_toolset_widget"
                }
            }
            ...
        ]
    }
}

Additionally it must be assigned to the corresponding attach-point provided by the layout-template bundle used. Therefore use the following sample for the app.json file:

"templates": {
    "TemplateModel": {
        "_templates": [{
            "name": "seasons",
            "widgets": [{
                "widgetRole": "my_toolset_widget",
                "attachTo": "map_topright"
            }]
        }]
    }
}

How to create a custom tool

Developers can create custom tools. Tools are defined in the manifest.json file of a bundle. Each tool is defined as a component and must provide a unique ID.

All tools implement the basic tool class: ct/tools/Tool. This class provides certain attributes and functions to control the tool behavior. All of them are described in the JavaScript documentation. To provide a custom tool, configure a custom component. Each tool has to provide the ct.tools.Tool interface to be recognized by the tool system.

Sample manifest.json:

{
    "name": "MyCustomTool",
    "impl": "ct/tools/Tool",
    "provides": ["ct.tools.Tool"],
    "propertiesConstructor": true,
    "properties": {
        "id": "myCustomTool1",
        "title": "My Title",
        "tooltip": "My Tooltip",
        "toolRole": "toolset",

        //optional css class
        "iconClass": "myCustomIcon",
        "togglable": true,
        "activateHandler": "myActivateAction",
        "deactivateHandler": "myDeactivateAction",

        //optional property. If omitted, the default value ["above", "below", "after", "before"] is used
        "tooltipPositions": ["below","before","after","above"]
    },
    "references": [{
          "name": "handlerScope",
          // component providing myActivateAction and myDeactivateAction functions
          "providing": "ct.bundles.some.CustomController"
    }]
}

The preceding code sample describes how to set up a custom tool and provide it as a button in a toolset. The given sample creates a toggleable tool, which is a tool button that can be activated and deactivated. Defining a handlerScope is crucial for resolving the correct handler method that is associated with the tool's action(s). The preceding sample binds the handler scope to <CustomController> that itself contains the functions myActivateAction and myDeactivateAction. These functions are called when the tool is being pressed and released.

Tools can be styled by means of CSS; each tool has a default style class that is prefixed by ctToolIcon_<toolId> (here ctToolIcon_myCustomTool1) by default. To add further CSS classes, use the iconClass property.

Supported handlers that can be used for a tool definition:

Handler Description
clickHandler Handler for tool click
dblClickHandler Handler for tool double click
beforeActivateHandler Handler is called before the onActivate event is fired
activateHandler Handler is called if the tool is activated
beforeDeactivateHandler Handler is called before the onDeactivate event is fired
deactivateHandler Handler is called if the tool is deactivated
enabledHandler Handler is called if the tool becomes enabled
disabledHandler Handler is called if the tool becomes disabled
showHandler Handler is called if the tool becomes visible
hideHandler Handler is called if the tool becomes hidden
processStartHandler Handler is called if the tool starts a processing task
processEndHandler Handler is called if the tool ends a processing task
activationConditionHandler Handler function to check a condition before activating a toggleable tool.

The function has to return true if the condition is fulfilled and false if not.

To combine tools with certain rules, see the toolrules bundle definition.