Merge pull request #56 from Roll20/story/SD-8724

SD-8724: Beacon | Alias convert legacy macro attributes

Author: Alicekb

assets/images/writeToClipboard_dialog.png

@@ -89,7 +89,7 @@ Roll buttons are HTML elements with specific attributes that execute designated
 
 {{< details "Q: How are Custom Sheet attributes handled in Beacon?" >}}
 
-Beacon gives you the ability to transition your Custom Sheet attributes to new attributes you create in Beacon. This means that when a user updates their sheet to the new Beacon sheet, their Custom Sheet attribute can be mapped to Beacon attributes using the `convertLegacyMacroAttributes` function. Sheet developers can define how to handle Custom Sheet attribute values to ensure compatibility with existing macros.
+Beacon gives you the ability to transition your Custom Sheet attributes to new attributes you create in Beacon. This means that when a user updates their sheet to the new Beacon sheet, their Custom Sheet attribute can be mapped to Beacon attributes using the `handleFallbackAttributes` function. Sheet developers can define how to handle Custom Sheet attribute values to ensure compatibility with existing macros.
 {{< /details >}}
 
 
@@ -105,9 +105,9 @@ Tokens represent characters or objects on Roll20 Tabletop (VTT). Functions like
 {{< /details >}}
 
 
-{{< details "Q: What is the role of the convertLegacyMacroAttributesArgs type?" >}}
+{{< details "Q: What is the role of the handleFallbackAttributesArgs type?" >}}
 
-The `convertLegacyMacroAttributesArgs` type defines the arguments used for handling Custom Sheet macro attributes. It includes the attribute name, character ID, and character data needed for mapping Custom Sheet attributes to the new sheet structure.
+The `handleFallbackAttributesArgs` type defines the arguments used for handling not found/defined Custom Sheet macro attributes. It includes the attribute name, character ID, and character data needed for mapping Custom Sheet attributes to the new sheet structure.
 {{< /details >}}
 
 

content/docs/about/faq.md

@@ -32,7 +32,7 @@ A digital or printed page used to track a character's attributes, abilities, and
 ## Computed Property: 
 Properties that have both get and set methods, which can be dynamically calculated.
 
-## ConvertLegacyMacroAttributes: 
+## HandleFallbackAttributes: 
 A function to handle mapping Custom Sheet macro attributes to the new Beacon Sheet format.
 
 ## Dispatch: 

content/docs/about/glossary.md

@@ -67,9 +67,9 @@ These components are crucial for handling actions, computations, macros, and rol
   target="_blank"
 >}}
 {{< link-card
-  title="Custom Sheet Macro Attributes"
-  description="Macro attributes handle the conversion of legacy macro attributes to the new format used in the Beacon SDK. This ensures compatibility with older character sheets and macros, allowing for a smooth transition to the new system."
-  href="/beacon-docs/docs/components/custom-sheet-macro-attributes/"
+  title="Fallbacks"
+  description="Fallback methods to allow Sheet Developers to handle attributes, roll templates and actions not found/defined in the sheet. These methods can also help to ensure compatibility with older character sheets macros, roll templates and actions allowing for a smooth transition to the new system."
+  href="/beacon-docs/docs/components/fallbacks/"
   target="_blank"
 >}}
 {{< /card-grid >}}

content/docs/components/InitRelay.md

@@ -24,7 +24,7 @@ Join to get access to the Beacon SDK, the community sheet repo for Beacon sheet,
 
 The dispatch is returned by the `initRelay` and provides methods for sending commands from the character sheet back to the host. Except when specified every method below will return a promise.
 
-#### update
+## update
 ```javascript
 dispatch.update({
   options: { overwrite?: boolean }
@@ -35,7 +35,7 @@ The `update` method sends character changes to the host (Roll20 Tabletop or Roll
 
 The partial character passed in here must contain the character's id, and can contain any combination of the attributes, bio, and gmNotes properties. When updating a character’s attributes, only include those attributes that have changed.
 
-#### updateCharacter
+## updateCharacter
 ```javascript
 dispatch.updateCharacter({
   character: Partial<Character>
@@ -45,7 +45,7 @@ Like the `update` method, `updateCharacter` sends character changes to the host
 
 However, this method takes a full set of character attributes as the character argument, and automatically computes the diff with existing character attributes, so that only changed attributes are sent to the data store.
 
-#### roll
+## roll
 ```javascript
 dispatch.roll({
   rolls: { [rollName: string]: string } // Ex. {attack: '1d20+4', damage: `3d6+2`}
@@ -58,7 +58,7 @@ If messageId is omitted, the roll will be associated with a new chat message and
 
 The method returns a promise that resolves with an object containing the messageId and the RollResult (see Types). The roll result is returned in the same format as in the non-beacon dice rolls computed roll system.
 
-#### post
+## post
 ```javascript
 dispatch.post({
   characterId: string,
@@ -78,7 +78,7 @@ The secret option is ignored unless whisper is also set, toggling to true will c
 
 Like roll, messageId can be provided to update an existing chat message, but if omitted the method will generate a new messageId and post a new chat message.  The method returns the messageId.
 
-#### query
+## query
 ```javascript
 dispatch.query(options: Swal2Options): {
   isConfirmed: boolean,
@@ -102,7 +102,7 @@ The `query` method takes an options object and uses them to display a [SweetAler
 
 `titleText, text, iconColor, input, width, padding, background, position, grow, timer, timerProgressBar, showConfirmButton, showDenyButton, showCancelButton, ariaLabel, confirmButtonText, denyButtonText, cancelButtonText, confirmButtonAriaLabel, confirmButtonColor, cancelButtonAriaLabel, cancelButtonColor, denyButtonAriaLabel, denyButtonColor, reverseButtons, showCloseButton, closeButtonAriaLabel, returnInputValueOnDeny, imageUrl, imageWidth, imageHeight, imageAlt, inputLabel, inputPlaceholder, inputValue, inputOptions, inputPlaceholder, inputAutoTrim, inputAttributes, validationMessage, progressSteps, currentProgressStep, progressStepsDistance.`
 
-#### Perform
+## Perform
 ```javascript
 dispatch.perform({
   characterId: string,
@@ -112,7 +112,7 @@ dispatch.perform({
 ```
 `perform` executes the specified action on behalf of the character (designated by the character id), passing in args to the action method. This method can perform actions on behalf of any character, even a character that the sheet does not have data for.
 
-#### getComputed
+## getComputed
 ```javascript
 dispatch.getComputed({
   characterId: string,
@@ -132,7 +132,7 @@ dispatch.setComputed({
 ```
 `getComputed` and `setComputed` are both nearly identical in how they are called, taking a character id and a property with the name of the computed property you wish to get or set, and an array of string args. Both methods return a promise that resolves with the computed value.
 
-#### compendiumRequest
+## compendiumRequest
 ```javascript
 dispatch.compendiumRequest({ 
   query: string
@@ -144,7 +144,7 @@ dispatch.compendiumRequest({
 ```
 `compendiumRequest` executes an AJAX request to the compendium service’s graphQL endpoint. It takes in a graphQL query string written according to the Compendium service’s schema. The query string does not need to include the ruleSystem shortName as this is set automatically according to the campaign override or sheet.json value in the Roll20 Tabletop.
 
-#### debouncedCompendiumRequest
+## debouncedCompendiumRequest
 ```javascript
 dispatch.debouncedCompendiumRequest({ 
   query: string
@@ -154,7 +154,7 @@ dispatch.debouncedCompendiumRequest({
 ```
 Like `compendiumRequest`, except that calls to this method are automatically debounced (at 100ms) and grouped together into a single request to the compendium service. Note that this method will only return the requested data, it does not return errors or extensions.
 
-#### getTokens
+## getTokens
 ```javascript
 dispatch.getTokens({
   characterId: string
@@ -168,7 +168,7 @@ dispatch.getTokens({
 ```
 `getTokens` requires a character id string and returns information about tokens on the user’s current page. The return value contains two arrays of tokens. The tokens array contains all tokens on the current page that represent the character whose id was provided to the method. The selected array contains any tokens that are currently selected, regardless of which character they represent. The returned token objects contain all of the token attributes available to the API, you can find documentation here and here.
 
-#### addToTracker
+## addToTracker
 ```javascript
 dispatch.addToTracker({
   tokenId?: string,
@@ -182,7 +182,7 @@ dispatch.addToTracker({
 ```
 `addToTracker` adds or updates a single item in the turn tracker. Passing in a tokenId will add the specified token to the tracker, while passing in custom with a name and an optional image url (img) will add a custom item, not connected to any character or token. A round calculation string can be added via the optional formula parameter. value is the initiative number for the item.
 
-#### addMacrosToHost
+## addMacrosToHost
 ```javascript
 dispatch.addMacrosToHost({
   macro: {
@@ -206,7 +206,7 @@ Passing in a `location` will add it either to the player's macroBar, the charact
 
 [See Actions page for examples on the usuage of `addMacrosToHost`](/beacon-docs/docs/components/actions)
 
-#### getCharacterMacros
+## getCharacterMacros
 ```javascript
 dispatch.getCharacterMacros({
   args: {
@@ -224,7 +224,7 @@ dispatch.getCharacterMacros({
 ```
 `getCharacterMacros` gets a specific character’s macros. The `ids` returned from this list can be used in conjuction with `addMacrosToHost` update their locations. In jumpgate games, character macros can also be found in the `Advanced Tools -> Characters Macros` tab.
 
-#### setContainerSize
+## setContainerSize
 ```javascript
 dispatch.setContainerSize({
   args: { 
@@ -235,7 +235,7 @@ dispatch.setContainerSize({
 ```
 `setContainerSize` updates the size of the container which holds the sheet shared settings. Returns a promise that can be awaited. This can be used in conjunction with something like the ResizeSensor event listener from npm: css-element-queries to automatically resize the container on the host.
 
-#### updateTokensByCharacter
+## updateTokensByCharacter
 ```javascript
 dispatch.updateTokensByCharacter({
   args: { 
@@ -246,7 +246,7 @@ dispatch.updateTokensByCharacter({
 ```
 `updateTokensByCharacter` updates a particular character’s default token as well as all existing tokens representing that character. Returns a promise that can be awaited.
 
-#### updateTokensByIds
+## updateTokensByIds
 ```javascript
 dispatch.updateTokensByIds({
   args: { 
@@ -257,7 +257,7 @@ dispatch.updateTokensByIds({
 ```
 `updateTokensByIds` updates a single or several tokens. Returns a promise that can be awaited.
 
-#### autoLinkText
+## autoLinkText
 ```javascript
 dispatch.autoLinkText({
   args: { 
@@ -267,7 +267,7 @@ dispatch.autoLinkText({
 ```
 `autoLinkText` goes through the text to find handout names between square brackets and converts them into links with the handoutID. For example in a game with a handout named `Dragon`, passing in the text string of `this is a [Dragon]` to autoLinkText returns something similar to this is a `<a href="https://journal.roll20.net/8je02j0kd02k">Dragon</a>`.  
 
-#### openDialogFromLink
+## openDialogFromLink
 ```javascript
 dispatch.openDialogFromLink({
   args: { 
@@ -278,4 +278,16 @@ dispatch.openDialogFromLink({
 `openDialogFromLink` opens the supplied urlString through the Roll20 Tabletop. 
  - If the url is for a handout, it will open the corresponding handout in the campaign. This will also check if the user opening the link has access to the handout.  
  - If the url is for a compendium, it will open a pop up to the compendium page, it will also check to ensure the user has access to view the page.
- - If the url is for an external page, a confirmation pop up will display to warn the user that the link is for an external site and open a new tab in their main window if confirmed.
+ - If the url is for an external page, a confirmation pop up will display to warn the user that the link is for an external site and open a new tab in their main window if confirmed.
+
+## writeToClipboard
+```javascript
+dispatch.writeToClipboard(text)
+```
+`writeToClipboard` allows writing text such as macro commands or roll templates from the sheet to the player's OS clipboard. 
+
+This command will trigger a dialog model to pop up in the host, the dialog will include a warning urging the player to fully understand what their copying to their clipboard; The dialog will also include a preview of the text.
+
+Clicking `allow` will copy the text to the player's clipboard, while clicking `deny` will prevent it and log `"user refused copy action"`
+
+![writeToClipboard_dialog](images/writeToClipboard_dialog.png)

content/docs/components/dispatch.md

@@ -0,0 +1,123 @@
+---
+title: "Fallbacks"
+description: ""
+summary: ""
+date: 2024-01-00T16:12:37+02:00
+lastmod: 2023-09-07T16:12:37+02:00
+draft: false
+weight: 180
+toc: true
+sidebar:
+  collapsed: true
+seo:
+  title: "" # custom title (optional)
+  description: "" # custom description (recommended)
+  canonical: "" # custom canonical URL (optional)
+  noindex: false # false (default) or true
+---
+
+{{< callout context="tip" title="Join the Closed Beta" icon="outline/rocket" >}}
+The Beacon SDK is currently in closed Beta. Please complete the [form](https://forms.gle/XXnj1SbfmYnUq8Hu9) to sign up for the closed beta.
+
+Join to get access to the Beacon SDK, the community sheet repo for Beacon sheet, the community sheet developers in discord, and the new sheet developer Roll20 permissions.
+{{< /callout >}}
+
+When utilizing Macros, Roll Templates, or Actions within the Roll20 Tabletop or Roll20 Characters (both refered to as host throughout this page), there are instances where a older Custom Sheet macros might need to be employed for a Beacon sheet. 
+
+This scenario commonly arises when transitioning from an existing older Custom Sheet to a Beacon sheet. During such transitions, it's possible that the attributes called from the older Custom Sheet macros, roll templates or actions may not align with the structure of attributes in the Beacon Sheet.
+
+## handleFallbackAttributes
+
+{{< callout context="danger" icon="outline/alert-square" >}}
+  In older Beacon SDK versions, this function was previously named `convertLegacyMacroAttributes`.
+{{< /callout >}}
+
+The `handleFallbackAttributes` method allows us to determine the mapping strategy for older Custom Sheet attributes to the new Beacon Sheet.
+
+```typescript
+initRelay({
+  handleFallbackAttributes: (messages:  {
+    attribute: string,
+    characterId: string,
+    character: Character
+  }) => {}: string | number | null,
+}): Promise<Dispatch>
+``` 
+
+
+This method is defined during the initial SDK initialization process and is invoked by the host when it attempts to parse a macro and encounters a failure in locating an attribute's value during an macro's execution.
+
+Beacon Sheet actions will typically search through the defined computed properties before resorting to the `handleFallbackAttributes` method.
+
+Returning a `null` value from this method will display the following error message to the user: `Unable to find attribute with the name ${attribute}`
+
+The method's purpose is to return a value that will be substituted in the macro. However, it grants us the autonomy to devise the preferred approach for handling older Custom Sheet attribute values. 
+
+## handleFallbackRollTemplates
+
+{{< callout context="danger" icon="outline/alert-square" >}}
+  In older Beacon SDK versions, this function was previously named `handleLegacyRollTemplates`.
+{{< /callout >}}
+
+Since Beacon sheets no longer require or use roll templates as previously defined in older custom sheets, there will be times where an older Custom Sheet roll template might need to be handled by a Beacon Sheet.
+
+This scenario commonly arises when transitioning from an existing older Custom Sheet to a Beacon sheet. During such transitions, it's possible that an older Custom Sheet roll template might need to be called or handled.
+
+We can use the `handleFallbackRollTemplates` to determine how to handle these cases.
+
+```typescript
+initRelay({
+  handleFallbackRollTemplates: (message: { 
+    templateName: string, // name of the template that triggered this method
+    properties: Record<string, any>, // a list of the values and formulas for rolls and macro in the template
+    // along with values for other properties in the template
+    dispatch: Dispatch, 
+    playerid: string ,
+    originalInput: string // the original text input for the entire roll template string
+  }) => {}: any,
+}): Promise<Dispatch>
+``` 
+
+The properites object will also include a plainText key for roll template arguments not inside the curly brace syntax. 
+
+```typescript
+{
+  //... other arguments
+  properties: {
+    attack: { value: 12, formula: '1d20' },
+    damage: { value: 5, formula: '2d6' },
+    foo: { value: 'bar' },
+    name: {
+      formula: "@{Helga|name}"
+      value: "Helga"
+    },
+    plainText: ['apicallback', 'apple=red'],
+    something: { 
+      value: "I went to get tacos"
+    },
+    ............
+  }
+}
+```
+
+## handleFallbackActions
+
+There might be times when an action isn't found in the Beacon Sheet's action list.
+
+This scenario commonly arises when transitioning from an existing older Custom Sheet to a Beacon sheet. During such transitions, it's possible that an older action name might need to be handled in the Beacon Sheet.
+
+`handleFallbackActions` can be used to handle these scenarios or as a general fallback for actions.
+
+```typescript
+initRelay({
+  handleFallbackActions: (message: { 
+    command: string, // The action command/name
+    characterId: string, 
+    args: Record<string, any>, // Arguments passed into action 
+    character: Character ,
+    dispatch: Dispatch
+  }) => {}: any,
+}): Promise<Dispatch>
+```
+
+This method doesn't return annything.