TerraExplorer Add-Ons

TerraExplorer add-ons allow external developers to:

§ Expand TerraExplorer capabilities with new HTML tools

§ Customize the ribbon by adding new ribbon commands that activate the new tools

§ Customize the user interface by changing the Start page and configuring Start settings

To add a tool to the TerraExplorer application, create an XML file named "tool.xml" that defines the tool and its location on the ribbon, and then save it in a folder placed under the tool’s folder. If you want to distribute a new tool, you should zip both the actual tool as well as the tool’s .xml (defining the tool and the location of the new tool on the ribbon) into a TEZ zip file for distribution to TerraExplorer users. See "Distributing Add-ons" for more information.

Note: If a TEZ named setup.tez is placed next to the TerraExplorer installation file during installation, it will automatically be installed.

The XML document must be contained within <Tool>…</Tool> opening and closing tags. Using the <Tool> tag’s attributes and child elements, you can configure the tool through definition of the following parameters:

§ Tool Path

§ Tool’s User Interface

§ Tool Settings

§ Ribbon Customization

Tool Path

The most basic XML file must include a path to the HTML tool as well as a unique ID and caption. The HTML tool must be located in the same folder as the Tool.xml file.

</Tool>

User Interface

A tool can be created with a user interface or as a hidden tool. Tools created with a user interface can be docked in the lower left panel or set to float in a designated position on the screen.

To determine the user interface:

§ Set the required child element under the <Container> element:

· <Panel> - Dock the tool window in the lower left panel.

· <Popup> - Create a popup tool window whose size and location are set by the <Popup> element’s attributes.

· <Hidden> - Create a hidden tool.

<Toolcaption="Data Analysis" id="ACO009" Path="MyToolFolder\MyTool.html">

<Panel/>

</Container>

</Tool>

Creating a Tool Docked in Left Panel

<Toolcaption="Data Analysis" id="ACO009" Path="MyToolFolder\MyTool.html">

<Popupx="30" y="60" width="300" height="200" ShowCaption="1"/>

</Container>

</Tool>

Creating a Popup Tool

<Toolcaption="Data Analysis" id="ACO009" Path="MyToolFolder\MyTool.html">

<Hidden/>

</Container>

</Tool>

Creating a Hidden Tool

Tool Settings

To define when a tool should run:

§ Set the <Tool> element’s attributes:

· AutoStart - Automatically launch the tool when opening a FLY project.

· RunOnce - Set the tool to run only once.

· ShowOnVersionTypes - Define which of the applications in the TerraExplorer family should display this custom tool command.

· NeedProject – Enable the tool command in the ribbon only if a project is currently open in TerraExplorer.

· UseEdge – Opens the tool in the Microsoft Edge browser.

<Toolcaption="Data Analysis" id="ACO009" Path="MyToolFolder\MyTool.html" NeedProject="0" ShowOnVersionTypes="3" RunOnce="1" AutoStart="1">

</Container>

</Tool>

Ribbon Customization

§ Create a ribbon command

§ Define properties of the ribbon command

§ Create a drop-down menu for the command

§ Define properties of the command’s drop-down menu

Create a ribbon command

To add a <Ribbon> element:

§ Set the <Ribbon> element’s Show attribute to 1.

</Tool>

Define properties of the ribbon command

To determine basic properties of the ribbon command:

§ Set the following values:

· Tool Name – To set the name of the tool as it should be displayed on the ribbon command and on the tool window, set the <Tool> element’s caption attribute.

· Ribbon Tab – To set the ribbon tab in which the new ribbon command should be placed, set the <Category> child element under the <Ribbon> element.

· Ribbon Group – To set the ribbon group in which the new ribbon command should be placed, set the <Panel> child element under the <Ribbon> element.

· Command Tooltip – To set the tooltip that is displayed when placing the mouse cursor over the ribbon command, set the <ToolTip> child element under the <Ribbon> element.

· Command Icon – To set an icon for the new ribbon command, set the <Icon> child element under the <Tool> element.

<Toolcaption="Data Analysis" id="ACO009" Path="MyToolFolder\MyTool.html" NeedProject="0" >

</Ribbon>

</Tool>

Create a drop-down menu for the command

Custom ribbon buttons can be created with drop-down menus that enable you to group several tools under one button, allowing better organization of customized tools and minimizing ribbon clutter.

To create a drop-down menu:

1. Set the <Submenu> child element under the <Ribbon> element.

2. For each of the drop-down menu options, create an <Item> child element under the <Submenu> element:

a. Uniquely identify the command that is being added to the drop-down menu by setting the <Item> element’s id attribute.

b. Define the path to the HTML page opened by the option by setting the <Item> element’s Path attribute.

c. Set the name of the option as it should be displayed in the drop-down menu by setting the <Item> element’s Caption attribute.

3. If you want to create a sub-command icon and tooltip, set the <Tooltip> and <Icon> child elements under the <Item> element.

<Toolcaption="Data Analysis" id="ACO009" Path="MyToolFolder\MyTool.html" >

</Item>

</Submenu>

</Ribbon>

</Tool>

Define additional properties of the command’s drop-down menu

The tool’s ribbon command can be set to only open a drop-down menu, or alternatively, set with dual functionality, where clicking the bottom half of the button opens a drop-down menu with sub-options, while clicking the upper half activates the "main" tool option, which will also be listed first in the drop-down menu.

To determine button functionality:

§ Set the value of the <Ribbon>’s splitButton attribute:

· splitButton = "0" - Button only opens a drop-down menu.

· splitButton = "1" (Default) Button is split into two halves with the functionality described above.

To format the drop-down menu:

§ Use the <Submenu> child elements:

· <Separator> - Creates horizontal divider lines in the drop-down menu.

· <GroupTitle> - Creates headings in the drop-down menu.

<Toolcaption="Data Analysis" id="ACO009" Path="MyToolFolder\MyTool.html">

<GroupTitle>MyGroup1</GroupTitle>

</Item>

</Item>

<GroupTitle>MyGroup2</GroupTitle>

</Item>

</Submenu>

</Ribbon>

</Tool>