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
}
}
dropdown
toolset
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
}
}
menubar
toolset
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"
}
menu
toolset
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.