Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

Types of Interface Tools

Open
  • Is something wrong?
#287 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
5/5
Estimated time
Over a week
Newbie friendliness
25/100
Issue type
Feature
Clarity
Needs clarification
Activity status
Stale
Tech stack
javascript
Domain
frontend

Research direction

No implementation file or test is named. Start by reviewing the existing Project.tools and interface implementation, then compare the related discussions in #160 and #107. Done would require an agreed tool type/location schema and event behavior before implementation can be scoped.

Written by the indexing model from the issue text.

Description

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.
Dominant language
JavaScript
Stars
2
Forks
3
No merged PRs in 30d

Getting set up

This project ships no dev container, Dockerfile or contributing guide, so setting up is up to you: start from its README, and see our first-contribution guide for the general steps.

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from CenterForDigitalHumanities/TPEN-interfaces

All issues in CenterForDigitalHumanities/TPEN-interfaces

Similar issues

More JavaScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.