CompactToolbar Module

The toolbar can be configured using Manager. See Toolbar for instructions.

The CompactToolbar Module implements the compact toolbar typically found in the Handheld interface. When activated, the compact toolbar appears at the top of the map.

As of version 2.4, the Handheld interface uses the compact toolbar by default, while the Desktop and Tablet interfaces use the tabbed toolbar by default. The tabbed toolbar is implemented by the TabbedToolbar Module. It is possible to use the compact toolbar in the Desktop and Tablet interfaces.

Handheld interface, showing the compact toolbar

The compact toolbar is made up of a single toolbar group, containing buttons, tools or multitools (also known as flyouts). Buttons immediately run commands that do not require input from the user. Tools run commands that operate on a geometry that the user draws; when the user clicks a tool, the tool must wait for the user to draw the geometry before running the command. Multitools act as menus of various related tools or buttons.

In the Handheld interface, the compact toolbar has three views, all of which use the CompactToolbarViewModel:

• Compact Toolbar: The CompactToolbarView is used for the compact toolbar that, when activated, appears at the top of the screen in the Handheld interface, or below the banner in the Desktop and Tablet interfaces.

• Compact Toolbar Flyout: The CompactToolbarFlyoutView is used to display the content of multitools.

• Compact Toolbar Button: (Handheld interface only) The CompactToolbarButtonView is used for the toolbar icon that the user clicks to open the compact toolbar. The toolbar icon displays in the HeaderRegion in the Handheld interface.

Configuration Properties

Module

• isEnabled: To enable the compact toolbar, set to true. The default is false.

• transientElements: An array of elements that define context-sensitive toolbars, each of which are associated with a state, a widget, a region, and a set of toolbar items.

  As of HTML5 Viewer 2.5, each element must be associated with an application state to create context-sensitive toolbars.

  • stateName: The name of the application state that triggers the context-sensitive toolbar. For a complete list of states, see State Reference.

  • widgetId: The ID of the widget.

  • region: The name of the region to use. For the compact toolbar, this is typically set to CompactToolbarTransientRegion.

    For the context-sensitive menu to be available in the tabbed toolbar, the region must be added to the items array of a group in the toolbarGroups array.

  • items: An array of toolbar items, each of which is either a button or toggle button.

    See Properties of Buttons or Properties of Toggle Buttons for more information.

• toolbarGroups: An array of toolbarGroup items, containing a single toolbarGroup with the ID, compactToolbar.

  Unlike the tabbed toolbar, the compact toolbar cannot have multiple tabs or groups. It should only contain a single toolbar group with the ID, compactToolbar.

  Properties of Toolbar Groups

  • id: For the compact toolbar, this ID should always be compactToolbar.

  • type: The type is toolbarGroup.

  • name: This property is not used by the compact toolbar.

  • items: An array of toolbar items, each of which is either a button, toggle button, tool, or multitool.

    See Properties of Buttons, Properties of Toggle Buttons, Properties of Tools, or Properties of Multitools for more information.

Properties of Buttons

• id: A unique ID for this button.

• type: The type is button.

• iconUri: The URI for the icon that you want to appear on the button. The image must be an appropriate size to fit on the button. Valid file formats are PNG, BMP, JPG, and JPEG.

• command: The command that the button runs when the user clicks the button.

  For information on commands, see Viewer Commands and Events.

• commandParameter: The value for the command to use as its parameter, if it has a parameter. Parameters may either be simple strings or complex objects containing any number of parameters.

  For information on a particular command's parameter, see Viewer Commands and Events.

• hideOnDisable: If this property is set to true and the button's command cannot run under the current configuration or run-time conditions, the button does not show in the toolbar.

  If hideOnDisable is false and the button's command cannot run, the button shows in the toolbar, but it is grayed out.

• name: The name that you want to appear on the button. You can use a text key or the literal text.

  For example, @language-toolbar-home-sub or Home.

• tooltip: The text for the tool tip that opens when the user positions the pointer over the button. You can use a text key or the literal text.

  For example, @language-toolbar-navigation-home-tooltip or Return to the introductory page.

Properties of Toggle Buttons

• id: A unique ID for this toggleButton.

• type: The type is toggleButton.

• toggleStateName: (optional) The name of the toggle state that this toggle button affects.

• toggleOn: Configures the toggle-on button, which turns the toggle button on:

  • name: The name that you want to appear on the toggle-on button. You can use a text key or the literal text.

    For example, @language-toolbar-home-sub or Home.

  • tooltip: The text for the tool tip that opens when the user positions the pointer over the toggle-on button. You can use a text key or the literal text.

    For example, @language-toolbar-navigation-home-tooltip or Return to the introductory page.

  • iconUri: The URI for the icon that you want to appear on the toggle-on button. The image must be an appropriate size to fit on the toggle-on button. Valid file formats are PNG, BMP, JPG, and JPEG.

  • hideOnDisable: If this property is set to true and the toggle-on button's command cannot run under the current configuration or run-time conditions, the toggle-on button does not show in the toolbar.

    If hideOnDisable is false and the toggle-on button's command cannot run, the toggle-on button shows in the toolbar, but it is grayed out.

  • command: The command that the toggle-on button runs when the user clicks the toggle button to turn it on.

    For information on commands, see Viewer Commands and Events.

  • commandParameter: The value for the command to use as its parameter, if it has a parameter. Parameters may either be simple strings or complex objects containing any number of parameters.

    For information on a particular command's parameter, see Viewer Commands and Events.

• toggleOff: Configures the toggle-off button, which turns the toggle button off:

  • name: The name that you want to appear on the toggle-off button. You can use a text key or the literal text.

    For example, @language-toolbar-markup-clear or Clear markup.

  • tooltip: The text for the tool tip that opens when the user positions the pointer over the toggle-off button. You can use a text key or the literal text.

    For example, @language-toolbar-markup-clear-tooltip or Clear all drawings from the map.

  • iconUri: The URI for the icon that you want to appear on the toggle-off button. The image must be an appropriate size to fit on the toggle-off button. Valid file formats are PNG, BMP, JPG, and JPEG.

  • hideOnDisable: If this property is set to true and the toggle-off button's command cannot run under the current configuration or run-time conditions, the toggle-off button does not show in the toolbar.

    If hideOnDisable is false and the toggle-off button's command cannot run, the toggle-off button shows in the toolbar, but it is grayed out.

  • command: The command that the toggle-off button runs when the user clicks the toggle button to turn it off.

    For information on commands, see Viewer Commands and Events.

  • commandParameter: The value for the command to use as its parameter, if it has a parameter. Parameters may either be simple strings or complex objects containing any number of parameters.

    For information on a particular command's parameter, see Viewer Commands and Events.

Properties of Tools

• id: A unique ID for this tool.

• type: The type is tool.

• iconUri: The URI for the icon that you want to appear on the tool. The image must be an appropriate size to fit on the tool. Valid file formats are PNG, BMP, JPG, and JPEG.

• command: The command that the tool runs after the user has drawn the geometry for the command to operate on.

  For information on commands, see .

• drawMode: The type of geometry the user draws, upon which the tool operates.

• name: The name that you want to appear on the tool. You can use a text key or the literal text.

  For example, @language-toolbar-tasks-identify or Identify.

• tooltip: The text for the tool tip that opens when the user positions the pointer over the tool. You can use a text key or the literal text.

  For example, @language-toolbar-identify-point-tooltip or Find out about a location on the map.

• hideOnDisable: If this property is set to true and the tool's command cannot run, the tool does not show in the toolbar.

  If hideOnDisable is false and the tool's command cannot run, the tool shows in the toolbar, but it is grayed out.

• isSticky: When set to true, the tool remains selected after the user has used it. To deselect the tool, the user must click the tool a second time, or click a different tool. This allows the user to use a tool repeatedly without having to reselect it each time.

  If you do not want a tool to remain selected after it is used, set isSticky to false.

• statusText: The status message to display when the tool is activated, often containing instructions for the user. You can use a text key or the literal text.

  For example, @language-toolbar-identify-point-desc or Click or tap a location on the map to learn what’s there.

Properties of Multitools

• id: A unique ID for this multitool.

• type: The type is flyout.

• name: The name that you want to appear on the multitool.

  You can use a text key or the literal text. For example, @language-toolbar-markup-drawing-tools or Draw.

• items: An array of items, each of which is either a button, toggle button, or tool.

• layout: To display large icons for each tool, set this property to Large. Otherwise, set the property to Small. The default is Large.

  This property is not used by the compact toolbar.

Views

• CompactToolbarView: No configuration properties

• CompactToolbarFlyoutView: No configuration properties

• CompactToolbarButtonView: (Handheld interface only) No configuration properties

View Models

• CompactToolbarViewModel:

  • toggleCommandDisablesView: (Handheld interface only) To deactivate the CompactToolbarView when the user hides the toolbar, set to true. The default is true.

    Do not change this property for the Handheld interface or add this property to the Desktop or Tablet interfaces. Doing so may cause the toolbar to behave unexpectedly or stop working altogether.

  • toolbarVisibleTools: (Desktop and Tablet interfaces) The number of tools to display at once. We recommend a minimum of 3 and a maximum of 9. If this property is missing or its value is 0, all tools will be displayed. The default is 4.

  • toolbarOpenByDefault: To open the toolbar when the viewer starts, set to true. The default is false.

  • toolbarGroupRefs: An array of IDs of the configured groups that you want to appear in the toolbar. In the case of the compact toolbar, the only group should be compactToolbar.

    Hide the group by removing its ID from the toolbarGroupRefs list. Add the group back by adding its ID back to the toolbarGroupRefs list.

• CompactToolbarTransientViewModel: No configuration properties

See Also...

TabbedToolbar Module