API: Register a Tab

[kgar]

This post is to discuss a structure for the API function(s) for registering tabs.

Why?

Tidy 5e Sheets have numerous features surrounding registered tabs, such as Tab Selection, Tab Ordering, and Default Tabs per Actor Type. To create a better user experience, having modules register their tabs will put power in the hands of the users when it comes to deciding which tabs to actually include on which sheets.

This rewritten version of Tidy 5e Sheets runs on svelte, so I do not have auto-magic jquery support for adding tabs and having them just work. Granted, I could mimic how the stock tab system works, but that would also tie my hands when it comes to providing various sheet layouts. I do not wish to be bound to the HTML structure and data-attribute requirements of the default sheets. So, these tabs may have different classes/selectors now or in the future as the sheets evolve. Providing a single way to register tabs is critical so that 1) module devs aren't having to scramble if the sheets' structure changes and 2) I am not having to tie my hands regarding evolving the sheets and offering additional layouts.

These sheets do not innately use the jquery listeners, so API support will be important for that also.

Use Cases / Ideas

• A module has a tab of content to add to the sheet.

Draft of API call(s)

// tbd
Hooks.once('tidy5e-sheet.ready', () => {
  const api = game.modules.get('tidy5e-sheet').api;
  api.registerActorTab(...);
  api.registerItemTab(...);
});

Goals

• ⭐ Provide a very easy / mostly seamless option for quick adoption that is compatible with the default sheets
• Provide more advanced options for those that want to tap into more Tidy features
• Support handlebars template submissions
• Support svelte component submissions
• Support imperative HTML submissions
• Support jquery event listening and form submissions (I'm doing everything else in svelte, so I don't talk with jquery much at all)
• Support optional inclusion of a tab in the runtime default set of tabs
• Support automatic inclusion of a tab in the Tab Selection and Default Tabs UIs
• Provide the full, current context data of the dnd5e actor sheet for the module consumer's reference
• Provide CSS that targets the default sheet item tables but within Tidy sheets, so that modules can use item tables that agree with the default sheets in terms of style and can seamlessly be reused in Tidy without issue.
• Provide API options for actually using Tidy 5e sheet svelte-based tables
  • Direct access to components for svelte modules
  • Object/class-based args for non-svelte modules, so that Tidy can read the data and render svelte tables with all the additional present and future (custom column selection?) functionality.
• Support option for a sheet tab to be included by default, so that it appears in the "Default Tab Selection" UI as one of the defaults, and when "Use Default" is clicked, this tab will be included when resetting.
• Support inclusion of actor tabs by actor type, for all actors, or for an array of actor types
• Support inclusion of item tabs by item type, for all items, or for an array of item types

Questions

• What will need to be done so that user-submitted tab contents have base Tidy styles without any effort?
• Create a set of CSS styles that target the structure and selector setup of the default sheet tables and apply tidy-ified styles to them. This is intended to be a low-effort, non-perfectionist shim to make tab contents mostly look like they belong and, more importantly, adhere to the layout/flex setup of the default tables, if modules utilize the default sheet table classes.
• Review various module dev tab contents under the lens of a tidy5e sheet container and determine what minimal adjustments at the top level of Tidy's core SCSS are needed.

Beta Test Rollout

Once there are solid options for Handlebars and HTML-based tab registration paths, I'll prepare a release. After that, I will do CSS work and bugfixing/changes.

I will be testing locally with modules mentioned by the Tidy 5e sheet community members so I can get a feel for what needs to be done.

When the API can be settled upon, I will start working on API documentation generation for this repo, as well as a type definitions npm package for convenience.

I Don't Own the Module ID Yet - How to Test the API anyway

Tip

Have both the original and the rewritten sheet modules installed and active.

Right now, original Tidy 5e and the rewrite can be compared side-by-side. This is meant to be a convenience for users so they do not have to uninstall/reinstall sheets to test out the rewrite. This presents a problem with providing an API directly on the module namespace 'tidy5e-sheet'. As a result, I am doing the following:

const tidy5eModule = FoundryAdapter.getModule(CONSTANTS.MODULE_ID); // "tidy5e-sheet-kgar"
tidy5eModule.api = getApi();

// TODO: Remove after taking over the live module ID
const prodTidy5eModule = FoundryAdapter.getModule('tidy5e-sheet');
if (prodTidy5eModule) {
  prodTidy5eModule.api = tidy5eModule.api;
}

So, you can opt to call my alpha/beta-testing module ID, but if you have the original sheets and the rewrite sheets both installed and turned on, you can just call the original sheets' module ID and use the API for the rewrite. It's weird, but I'm doing this for the users' convenience while I'm still in this alpha/beta period with the rewrite.

My recommendation is to program against the original module ID ("tidy5e-sheet") with the two modules installed/active. That way, when it's time to take over the module ID, your module won't have to make any changes.

Documentation and Type Definitions

When the API comes together, I will be working on publishing type definitions as a standalone NPM/etc. package and providing generated API documentation on this repo.

[kgar]

So, I'm thinking about a polymorphic way of doing this with tab registration classes. Something like:

const tidyApi = game
  .modules
  .get('tidy5e-sheet')
  ?.api;

if (!tidyApi) {
  return;
}

const myTab = new HandlebarsTab({
  // Look for either a template path or a template string; either should be permissible; if you provide both, I take the string
  templatePath: "path/to/template.hbs",
  template: "<h2>Alternatively, just provide the Handlebars template directly? By the way, what's this app ID? {{appId}}</h2>",
  // title: Localization keys also work
  title: "My Tab Title",
  // makeDefault: Makes this tab appear as a default tab in Tidy config settings
  makeDefault: true,
  // useCoreSheetListeners: not required, defaults to true for handlebars tabs, provides the stock Actor sheet functionality; e.g., expanding/collapsing item row previews
  useCoreSheetListeners: true,
  // onRender: optional, lets you do extra stuff to your tab contents at render time
  onRender: (tabContentElement, context, force) => console.log('Do whatever I want with my tab contents', tabContentElement),
  // ...?
});

tidyApi.registerActorTab(myTab);

[kgar]

Continuing the polymorphic approach, now with raw HTML:

const tidyApi = game
  .modules
  .get('tidy5e-sheet')
  ?.api;

if (!tidyApi) {
  return;
}

const myTab = new HtmlTab({
  // Look for either an HTML file path or a template string; either should be permissible; if you provide both, I take the string
  htmlPath: "path/to/file.html",
  html: `
    <h2>Check out my HTML, yo! Ok, what is my app ID? <span class="app-id"></span></h2>
    <p>This is a tab for actor <span class="actor-id"></span></p>
  `,
  // title: Localization keys also work
  title: "My Tab Title",
  // makeDefault: Makes this tab appear as a default tab in Tidy config settings
  makeDefault: true,
  // useCoreSheetListeners: not required, defaults to true for handlebars tabs, provides the stock Actor sheet functionality; e.g., expanding/collapsing item row previews
  useCoreSheetListeners: true,
  // onRender: optional, lets you do extra stuff to your tab contents at render time
  onRender: (tabContentElement, context, force) => {
    tabContentElement.querySelector('.app-id').textContent = context.appId;
    tabContentElement.querySelector('.actor-id').textContent = context.actor.id;
  },
  // ...?
});

// We use the same registerActorTab, now with the HTML tab class instance
tidyApi.registerActorTab(myTab);

[kgar]

Yep, great talk, gang 😎
Closing discussion. There are some neat ideas in the checklist up above, but I think taking it slower and seeing what people need is going to be the best start.