-
-
Notifications
You must be signed in to change notification settings - Fork 22
Core Changes for System Module Developers
The following method previously deprecated have now been removed:
-
doGetActionHandler: Use
getActionHandler -
doGetRollHandler: Use
getRollHandler -
doRegisterSettings: Use
registerSettings -
doRegisterDefaultFlags: Use
registerDefaults
The encodedValue or button value is still available and passed to the handleActionClick and handleActionHover method, however its use is deprecated in favour of the two methods described.
Two new properties (onClick and onHover) can be set against the action object passed to the ActonHandler.addActions method. These properties expect a function and, if set, are called when an action is clicked or hovered instead of calling the RollHandler.handleActionClick or RollHandler.handleActionHover methods.
These properties enable all action handling including events to be handled within the ActionHandler instead of using a separate RollHandler instance.
const actions = [];
actions.push({
id: "toggleCombat",
name: token.inCombat ? "Remove from Combat" : "Add to Combat",
onClick: async () => {
const token = Utils.getFirstControlledToken();
await token.document.toggleCombatant();
}
})
this.addActions(actions, group);The tooltip property on the action object now expects an object, though a string is still handled. When passing an object, the following properties are handled:
-
content: The content of the tooltip. -
class: A CSS class to apply to the tooltip. -
direction: The direction to display the tooltip: UP, DOWN, LEFT, RIGHT, CENTER
const actions = [];
const tooltip = {
content: "<div><h3>Prone</h3><ul><li>A prone creature's only movement option is to crawl, unless it stands up and thereby ends the condition.</li><li>The creature has disadvantage on attack rolls.</li><li>An attack roll against the creature has advantage if the attacker is within 5 feet of the creature. Otherwise, the attack roll has disadvantage.</li></ul></div>",
class: "tah-system-tooltip",
direction: "LEFT"
}
actions.push({
id: "prone",
name: "Prone",
tooltip
});
this.addActions(actions, group);If using a RollHandler instance to handle action click and hover events, the associated action is now made available using this.action within a RollHandler instance. For example, instead of decoding the action's encodedValue, you could instead pass the component parts into the action's system object and access these directly using this.action.system.
const { actionId, actionType } = this.action.system;
switch(actionType) {
case "weapon":
this.useItem(event, actor, actionId);
break;
}
useItem(event, actor, actionId) {
const item = coreModule.api.Utils.getItem(actor, actionId);
item.use({ event, legacy: false });
} The following properties are available in both the ActionHandler and RollHandler instances:
-
actor: The actor object for the controlled token. -
actorsAn array of actor objects for the controlled tokens. -
token: The token object for the controlled token. -
tokens: An array of token objects for the controlled tokens. -
isRightClick: A boolean indicating whether the action was right-clicked. -
isAlt: A boolean indicating whether the ALT key was pressed when the action was clicked. -
isCtrl: A boolean indicating whether the CTRL key was pressed when the action was clicked. -
isShift: A boolean indicating whether the SHIFT key was pressed when the action was clicked. -
isHover: A boolean indicating whether the action was hovered over: true or hovered off: false.
Added a system object to the action and group objects to enable additional properties to be stored within those objects.
Use the 'registerStyles' method to add HUD styles. Your styles will be added to Token Action HUD Core's 'Style' module setting. The method requires an object to be returned in the following format:
{
myFirstStyle: {
class: 'tah-style-my-first-style', // The class to add to the first DIV element
file: 'tah-dnd5e-my-first-style', // The filename without the .css extension
moduleId: 'token-action-hud-dnd5e', // The TAH system module ID
name: 'My First Style' // The name to display in the setting drop-down list
},
mySecondStyle: {
class: 'tah-style-my-second-style',
file: 'tah-dnd5e-my-second-style',
moduleId: 'token-action-hud-dnd5e',
name: 'My Second Style'
},
}Groups under the top-level group can now be assigned a custom width by passing a settings.customWidth property in the groupData parameter of the addGroup method. Users can also set a custom width directly via the dialog available by right-clicking the group title while the HUD is unlocked.
A tokenActionHudCoreAddActionHandlerExtenders hook has been added to allow developers to extend the action handler outside of TAH Core and TAH system module code. For example, a module to add a custom group and actions to the HUD of a particular system. The hook passes the ActionHandler class, which contains the addActionHandlerExtender method. TAH system module developers can continue to use this method inside their ActionHandler.getActionHandler override method.
The 'Open Item Sheet on Right-Click' core module setting has been removed as it forced TAH system modules to either adhere to the setting or ignore it to use the right-click for other purposes. If you retain the functionality, you may wish to add a module setting to replicate the removed core setting to allow users to continue to disable it as before. The RollHandler.isRenderItem method still exists, but it no longer checks for this setting and now only checks for a right-click and that no modifier keys (alt, ctrl, shift) are pressed. The RollHandler.renderItem method (renamed from doRenderItem) can still be used to render the item sheet.
Replaces the addFurtherActionHandler method, but otherwise remains the same.
Replaces the ActionListExtender class.
Replaces the extendActionList method, but otherwise remains the same.
Replaces the doRenderItem method. Will return true if the item was rendered.
Replaces the doHandleActionEvent method, but otherwise remains the same. This method is called when an action is either left-clicked or right-clicked.
A new override method called when an action is hovered over (mouseover) or away (mouseleave). Use the event.type to determine the state.
A new override method called when a group is right-clicked while the HUD is locked.
Replaces the doGetActionHandler method, but otherwise remains the same.
Replaces the doGetRollHandler method, but otherwise remains the same.
Replaces the doRegisterDefaultFlags method, but otherwise remains the same.
Replaces the doRegisterSettings method, but otherwise remains the same.
The methods previously deprecated in 1.4 have been removed: ActionHandler.addActionsToActionList, Actionhandler.addSubcategoryInfo, ActionHandler.addSubcategoryToActionList, ActionHandler.sortItems, ActionHandler.sortItemsByName.
The 'categories' and 'subcategories' objects returned in the doRegisterDefaultFlags method and previously deprecated in 1.4 have been removed.
Added the Utils.getModuleVersion(moduleId) method to return a module's version. For example: Utils.getModuleVersion('token-action-hud-core').
Added the getStatusEffect(actor, statusId) method to return the first matching effect from an actor based on the status id. For example: Utils.getStatusEffect(this.actor, 'dead'). Works for Foundry VTT V10 and V11.
A defaultSelected property can be included to the group object when using the ActionHandler.addGroup method to set whether the group is selected by default. Default is true. This is useful when adding derived group where you want some groups to be available to add from the dialog but not added when its defined parent group is initially added.
A tooltip can be included for actions using the new tooltip property. For example:
const tooltip = `<h3>Longsword</h3><p>Longswords can be one‑edged or two‑edged swords. Their blades are heavy and they're between 3 and 4 feet in length.</p>`
const action = { id, name, encodedValue, tooltip }Tooltips uses Foundry VTT's core tooltip functionality. Two CSS classes are available to provide custom CSS to the tooltips: tah-tooltip for V11 and tah-tooltip-wrapper for V10 support. tah-tooltip is added to Foundry VTT's #tooltip element, whereas tah-tooltip-wrapper is nested under the #tooltip element.
The 'Tooltip Display' module setting allows users to display the tooltip as passed by the TAH system module (Full Tooltip), the action name (Name Only) or no tooltips. Other user control over the tooltip, such as whether to display additional information, should be set by the TAH system module as the formation of tooltips is likely to differ between systems.
A getModifier(value) method has been added to Token Action HUD Core's Utils. The method accepts a positive or negative number and will return a string for a typical display of the modifier with a + added. For example:
const modifier = coreModule.api.Utils.getModifier(10)
// '+10'References to 'categories' and 'subcategories' are replaced by 'groups'.
Actor and user data relating to the HUD is now saved into json files instead of the actor and user flags. Existing data is migrated when the user first opens the world. No action should be required, however the update from TAH Core 1.3 to 1.4 should be thoroughly tested to avoid unforeseen issues with the migration.
The doRegisterDefaultFlags method now expects { layout: [...], groups: [...] } to be returned, instead of { categories: [...], subcategories: [...] }. Additionally, the subcategories property in the layout must be renamed to groups.
DEFAULTS = {
layout: [
{
nestId: 'inventory',
id: 'inventory',
name: coreModule.api.Utils.i18n('DND5E.Inventory'),
groups: [
{ ...groups.weapons, nestId: 'inventory_weapons' },
{ ...groups.equipment, nestId: 'inventory_equipment' },
{ ...groups.consumables, nestId: 'inventory_consumables' },
{ ...groups.tools, nestId: 'inventory_tools' },
{ ...groups.containers, nestId: 'inventory_containers' },
{ ...groups.loot, nestId: 'inventory_loot' }
]
},
{ ... },
{ ... },
],
groups: [...]
}The hasDerivedSubcategories property is no longer required.
The CategoryManager class has been removed and all of its methods dropped or merged into the ActionHandler class. Most methods have been renamed.
Replaces the addSubcategoryToActionList method. Note that the parameters have been swapped around.
addGroup(groupData, parentGroupData, update)
Replaces the addSubcategoryInfo method, but otherwise remains the same.
addGroupInfo(groupData)
A removeGroup method has been added to the ActionHandler class to remove groups from the HUD based on id to remove all groups or nestId to remove a specific group.
-
removeGroup(groupData)- groupData: Object.
{ id, nestId }
- groupData: Object.
An updateGroup method has been added to the ActionHandler class to update existing groups in the HUD.
-
updateGroup(groupData, parentGroupData)- groupData: Object. The group data.
- parentGroupData: Object. Optional. The parent group data.
Replaces the addActionsToActionList method, but otherwise remains the same.
addActions(actionsData, groupData)
Replaces ActionHandler#sortItems.
Replaces ActionHandler.sortItemsByName.
A tokenActionHudCoreHudUpdated hook has been added to allow TAH system modules to run code after the HUD has updated.
The advancedCategoryOptions object within the group object has been renamed to settings.
A new property style has been added to the settings object within the group object with a value of list or tab. This property determines whether a group is displayed in the tab or list format.
The core CSS style is now added as a HTML class to the HUD's first DIV element. The classes are:
- tah-style-custom
- tah-style-dorako-ui
- tah-style-foundry-vtt
- tah-style-high-contrast
- tah-style-pathfinder
The addSubcategoryToActionList method can now be used to update existing subcategories by passing true as the third parameter, e.g., addSubcategoryToActionList(parentSubcategoryData, subcategoryData, true).
actor and token variables are now available in the core ActionHandler and RollHandler classes. actorId and tokenId no longer need to be included in the action's encodedValue, instead the system module's RollHandler can use this.actor and this.token, e.g., CoreUtils.getItem(this.actor, actionId).
The buildSystemActions method called by Token Action HUD Core no longer passes the character parameter. subcategoryIds is still passed. Instead, the character data can now be accessed from the core ActionHandler itself: this.actor, this.token, this.characterName.
Action objects can include a listName property to display a different name in the dialog lists, e.g., { id: 'gO2Dz4cALMnDMHQi', name: 'Hempen Rope (50 ft.)', listName: 'Item: Hempen Rope (50 ft.)' }
The doRenderItem function now only requires the actor object and item id, e.g., this.doRenderItem(actor, itemId).
The getImage function now accepts an image URL in place of an entity object, e.g., getImage('icons/sundries/survival/rope-wrapped-brown.webp')
Token Action HUD Core now calls the tokenActionHudCoreApiReady hook, which passes the core module object. TAH Core classes can be extended by wrapping the extending classes with this hook and referencing the TAH Core class within the passed core module object, like so:
export let ActionHandler = null
Hooks.once('tokenActionHudCoreApiReady', async (coreModule) => {
ActionHandler = class ActionHandler extends coreModule.api.ActionHandler {
// TAH SYSTEM MODULE CLASS CODE HERE
}
})The SystemManager#doRegisterDefaultFlags method now requires the object for default categories and subcategories to be returned. The setFlag is now handled by the core registerDefaultFlags method, which calls doRegisterDefaultFlags. Here's an example where DEFAULTS is the object of default categories and subcategories:
async doRegisterDefaultFlags () {
const defaults = {
categories: [
{
nestId: 'inventory',
id: 'inventory',
name: game.i18n.localize('DND5E.Inventory'),
subcategories: [
{
nestId: 'inventory_weapons',
id: 'weapons',
name: game.i18n.localize('ITEM.TypeWeaponPl'),
type: 'system',
hasDerivedSubcategories: false
}
// FURTHER SUBCATEGORIES HERE
]
}
// FURTHER CATEGORIES HERE
],
subcategories: [
{ id: 'weapons', name: game.i18n.localize('ITEM.TypeWeaponPl'), type: 'system', hasDerivedSubcategories: false }
// FURTHER SUBCATEGORIES HERE
]
}
return defaults
}