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>

Parameters

• 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 (&27;) instead of +.

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

How to call a macro on a non-library token

You can call macros on usual tokens by using @TOKEN in the macro name. You have to specify the token with the macro as target token. The usual limits of ownership and trust should be expected here too.

This line would call macro B on token Hero:

[r: macroLink("Click me!", "B@TOKEN", "all", "", findToken("Hero"))]

UDFs and Macro Links

UDFs (user defined functions - see defineFunction()) and macro links are just two different ways of doing the same thing. They both call a macro and pass arguments. The UDF expresses it as functionName(arg0,arg1,...) while a macrolink may express it as macroLink(text, macroName, output, args, target) where args is a string prop list (ie "arg0=0; arg1=1; ..."). How the args are processed in the macro are shown as different, but they're only different in procedure, not functionality.

I could for example make a UDF call functionName(arg0) where arg0 is "arg0=0; arg1=1;" OR I could make a macroLink where the args are in a json array like macroLink(text, macroName, output, '["arg0":1,"arg1":1]', target) and then the called macro could process the arguments the same way if called from a macroLink or a UDF.

In either case, the called macro will receive macro.args with the value you sent. The arg() function will look at what's in macro.args and if it looks like a json array, then it will parse out the arguments in to the arg(0), arg(1)... variables.

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.