Types of Interface Tools

The use of Tools might rely on the `Project.tools` array, but there must be an understanding of what we are looking for.

Elsewhere (#160) we talk about how to arrange these for the user and (#107) how to organize the data for these.

In general, tools have a *type* and a *location*. The Type will describe where the tool is described and what it can do. The Type is not recorded in the Tool data but helps distinguish where different tools may be found.

Type | Defined In | Description
--- | --- |---
Integrated | Interface Component | Only one version of this tool is allowed and if it is toggled off and on, it will be in the interface options directly, for the entire Project.
Project | Project.tools[] | These Tools are added by default, through custom interactions, or in Project Management by the User. Stored in the Project.tools stack, each item contains all the information an interface may need to implement it. It's inclusion in Project.tools[] *allows* for inclusion anywhere but does *not require* it.
?User | User.options | There are no Tools designed or applied to a User but if it were included, it would have to be on the User object directly to not appear in public User data or be shared with other collaborators. If an interface needs variety within a Tool, using Roles to change what renders makes more sense.

The Location of each Tool may be included in the Tool's description. It is intended to suggest the type of interactions the tool is built for but might not fit all scenarios. While interfaces may use this same pattern, the Locations below relate only to Project.tools[] items.

Location | Description | Events | Parameters
--- | --- | --- |---
Linked | This Tool is implemented completely separately from the rest of the platform. Selecting this Tool should navigate to the url defined. | All standard TPEN Events, if implemented. As it is a standalone document, the core tool is not listening. | As defined, Tool will receive things like "projectID", "pageID", "lineID" etc.
Pane | Often a splitscreen layout, these tools take over a large division of the screen. The width may be adjustable or fixed and the content may be iFrame or a Web Component. | TPEN Events are only available for Web Components, but hashchange can be watched in iFrames to pass some information. | In an iFrame, hashchange may define requested parameters.
Sidebar | Usually a fixed small margin tool, containing a Web Component. | All TPEN Events and dispatcher | none
Drawers | A floating tool that comes in over top of content. It may be free or docked to a side. | none
Dialog | Without changing location, interrupt the current work and complete the interaction with the tool before continuing. | TPEN Events and a specific show/dismiss event. | none

## Suggested Schema

Tools that have this sort of description will be best understood by the TPEN platform.

Property | Type | Value
--- | --- | ---
label | String | The name of the Tool for display. It will be limited to [32] characters and normalized to a-Z with spaces.
toolName | String | lowercase single-word a-z for use in tool events
custom | Object | configuration of tool or record of state
url | URL (absolute or full) | location of the tool document for iframe.src or the link to open
location | enum | as above: suggested interaction location for tool

**Events**

Each tool will be shown or hidden through events that can be handled within the tool, by the interface, or both. Tool-specific events will use the `toolName` to customize the call. Events are passed through the TPEN.eventDispatcher.

Name | Payload | Announced/Expected behavior
--- | --- | ---
tool-*toolName*-show | params | The container containing this tool will be visible and the tool itself should unhide if needed.
tool-*toolName*-loaded | none | Asynchronous tools may wish to announce when they have loaded and are ready for interaction.
tool-*toolName*-hide | none | The tool itself should hide or dismiss if visible.
tool-*toolName*-resize | dims | The container containing this tool has been resized and might indicate a need to alter the layout of the tool.
tool-*toolName*-action | per action | The tool is firing some action that the interface may want to know about.
tool-*toolName*-reset | none | The interface wants to reset this tool to its initial state, clearing any in session changes.
tools-dismiss | none | All tools should be hidden and cleared.
tools-poll | none | Request that all tools fire their loaded event, if present.