macroLink

macroLink() Function

• Introduced in version 1.3b48

Creates the HTML for a link which will run the specified macro when clicked on in a frame, dialog, or the chat window. Additionally, if you send the link to the chat window, it will automatically be executed by any recipients as soon as they receive it. This can be useful for popping up or updating frames or dialogs for your players. To auto-execute in the chat window, it must not be hidden by roll options like [h:], but may be hidden by being contained within an HTML comment.

Some notes on the auto execution

• If you refer to a macro on a lib token it will automatically execute, however if you refer to a macro on the campaign panel, the macro is NOT automatically executed when sent to the chat.
• It will also not work if the owner of the lib:token is not an (online) GM, though as a general practice its best not to set ownership of lib:tokens at all.
• To prevent the macro from automatically executing you can turn off the 'auto execute' in the edit panel of the macro that you're linking to.

Usage

macroLink(text, macroName)

macroLink(text, macroName, output)

macroLink(text, macroName, output, args)

macroLink(text, macroName, output, args, target)

The string generated by the macroLink function follows this format:

<a href="macro://macroName/output/target?args">text</a>

• text is the text to display for the link.
• macroName is the name of the macro to run when the link is clicked. The macroName is in the same format that is used for [macro(...): ...] e.g. Test@Lib:test
• output contains who the output of the macro should go to, values are (defaults to none)
  • self - Display only to person who clicked on the link.
  • gm - Display to GM.
  • all - everyone (acts like a /say)
  • none - discard any output.
  • gm-self - Display to GM and the person executing the link.
  • list - Displays to a list of players. When the output is set to "list" then the macro link expects the args parameter to be a JSON Object, that contains a field called mlOutputList which is a JSON Array containing the players to send the output to.
• args Any arguments to be passed to the macro when it is called.
• target Which tokens to run the macro on. Target can be one or more of the following separated by commas (defaults to impersonated)
  • impersonated - the impersonated Token
  • selected - the selected Tokens
  • Token Id - the id of a Token.

Examples

To create a link that will call a macro called Test on the Library Token named Lib:Test that says "Click on me!" and displays the output to the GM.

[r: macroLink("Click on me!", "Test@Lib:Test", "gm", "count=6", "impersonated")]

produces this output:

<a href="macro://Test@Lib:Test/gm/impersonated?count=6;">Click on me!</a>

Sending to multiple players and the GM in 1.3b55

[h: outputTo = '["Fred", "Barney", "gm"]']
[h: args = json.set("{}", "mlOutputList", outputTo)]
[r: macroLink("Click on me!", "Test@Lib:Test", "list", args)]

Updating a character sheet frame without displaying the link:

Took 4 points of damage.<!-- [r: macroLink("Update Character Sheet", "Update Character Sheet@Lib:Test")] -->

An example of a longer custom macrolink:
This is a link that is user created to send several variables to the AttackMacro. Each variable must be separated by a & sign. Spaces within text must be replaced with a + sign. Plus sign can't be sent, you might want to use the html code for plus sign instead of +.

<a href="macro://AttackMacro@Lib:Test/all/impersonated?Count=6&DiceToRoll=1d6plus4&Text=Hello+there+Im+attacking+you;">Click me</a>

See Also

macroLinkText()

Version Changes

• 1.3b55 - Added gm-self and list output options.
• 1.3b56 - Links created using this function will no longer show a tooltip when displayed in a dialog or frame.