macroLinkText: Difference between revisions

From RPTools Wiki
Jump to navigation Jump to search
VisualWikitext
(Updated for new features in b55.)
No edit summary
 
(12 intermediate revisions by 7 users not shown)
Line 3: Line 3:
|version=1.3b48
|version=1.3b48
|description=
|description=
Creates the text that would appear in a HTML tag for a link which will run the specified macro when clicked on. This is useful for callbacks in {{func|dialog}}s or {{func|frame}}s. If you just want to send a click-able link to someone use {{func|macroLink}}.
Creates the text that would appear in a HTML tag for a link which will run the specified macro when clicked on. This is useful for callbacks in {{roll|dialog}} or {{roll|frame}}. If you just want to send a click-able link to someone use {{func|macroLink}}.


|usage=
|usage=
<source lang="mtmacro" line>
<syntaxhighlight lang="mtmacro" line>
macroLinkText(macroName)
macroLinkText(macroName)
</source>
</syntaxhighlight>
<source lang="mtmacro" line>
<syntaxhighlight lang="mtmacro" line>
macroLinkText(macroName, output)
macroLinkText(macroName, output)
</source>
</syntaxhighlight>
<source lang="mtmacro" line>
<syntaxhighlight lang="mtmacro" line>
macroLinkText(macroName, output, args)
macroLinkText(macroName, output, args)
</source>
</syntaxhighlight>
<source lang="mtmacro" line>
<syntaxhighlight lang="mtmacro" line>
macroLinkText(macroName, output, args, target)
macroLinkText(macroName, output, args, target)
</source>
</syntaxhighlight>
'''Parameters'''
'''Parameters'''
{{param|macroName|The name of the macro to run when the link is clicked.  The {{code|macroName}} is in the standard macro reference format (e.g. {{code|Macro@Lib:Token}})}}
{{param|macroName|The name of the macro to run when the link is clicked.  The {{code|macroName}} is in the standard macro reference format (e.g. {{code|Macro@Lib:Token}})}}
Line 25: Line 25:
** {{code|all}} - Everyone (acts like a {{code|/say}})
** {{code|all}} - Everyone (acts like a {{code|/say}})
** {{code|none}} - Discard any output.
** {{code|none}} - Discard any output.
** ''gm-self'' - Display to GM and the person executing the link.
** {{code|gm-self}} - Display to GM and the person executing the link.
** ''list'' - Displays to a list of players. When ''output'' is {{code|list}} then the macro link expects the argument to be a [[JSON Object]], that contains a field called {{code|mlOutputList}} which is a [[JSON Array]] containing the players to send the output to.
** {{code|list}} - Displays to a list of players. When the {{code|output}} parameter is {{code|"list"}} then the macro link expects the {{code|args}} parameter to be a [[JSON Object]], that contains a field called {{code|mlOutputList}} which is a [[JSON Array]] containing the players to send the output to.
{{param|args|Any arguments to be passed to the macro when it is called.}}
{{param|args|Any arguments to be passed to the macro when it is called.}}
{{param|target|Which tokens to run the macro on. Target can be one or more of the following separated by commas (defaults to {{code|impersonated}}):}}
{{param|target|Which tokens to run the macro on. Target can be one or more of the following separated by commas (defaults to {{code|impersonated}}):}}
** {{code|impersonated}} - The impersonated [[Token]].
** {{code|impersonated}} - The impersonated [[Token]].
** {{code|selected}} - The selected [[Token]]/s.
** {{code|selected}} - The selected [[Token]]/s.
** [[Token ID]] - The {{code|id}} of a [[Token]].
** [[Glossary#T|Token ID]] - The {{code|id}} of a [[Token]].


|examples=
|examples=
To create the text that would go inside a form element as the {{code|action}} attribute, and that will call a macro named {{code|Test}} on the [[Library Token]] named {{code|Lib:Test}}:
To create the text that would go inside a form element as the {{code|action}} attribute, and that will call a macro named {{code|Test}} on the [[Library Token]] named {{code|Lib:Test}}:
<source lang="mtmacro" line>
<syntaxhighlight lang="mtmacro" line>
[r: macroLinkText("Test@Lib:Test","", "gm")]
[r: macroLinkText("Test@Lib:Test","", "gm")]
</source>
</syntaxhighlight>
Returns: {{code|macro://Test@Lib:Test/gm/impersonated?}}
Returns: {{code|macro://Test@Lib:Test/gm/impersonated?}}


To create the text that would go inside a form element as the {{code|action}} attribute and call the {{code|AddWeapon}} on the [[Library Token]] named {{code|Lib:PC}} which will act upon the [[Current Token]]:
To create the text that would go inside a form element as the {{code|action}} attribute and call the {{code|AddWeapon}} on the [[Library Token]] named {{code|Lib:PC}} which will act upon the [[Current Token]]:
<source lang="mtmacro" line>
<syntaxhighlight lang="mtmacro" line>
[r:macroLinkText('AddWeapon@Lib:PC', 'none', '', currentToken())]
[r:macroLinkText('AddWeapon@Lib:PC', 'none', '', currentToken())]
</source>
</syntaxhighlight>
Returns: {{code|macro://AddWeapon@Lib:PC/none/#ID#?}} where {{code|#ID#}} is the {{code|id}} of the [[Current Token]].
Returns: {{code|macro://AddWeapon@Lib:PC/none/#ID#?}} where {{code|#ID#}} is the {{code|id}} of the [[Current Token]].


Sending to multiple players and the GM in 1.3b55
Sending to multiple players and the GM in 1.3b55
<source lang="mtmacro" lines>
<syntaxhighlight lang="mtmacro" line>
[h: outputTo = '["Fred", "Barney", "gm"]']
[h: outputTo = '["Fred", "Barney", "gm"]']
[h: args = json.set("{}", "mlOutputList")]
[h: args = json.set("{}", "mlOutputList", outputTo)]
[r: macroLinkText("Click on me!", "Test@Lib:Test", "list", args)]
[r: macroLinkText("Test@Lib:Test", "list", args)]
</source>
</syntaxhighlight>
|changes=
 
* '''1.3b55''' - added {{code|gm-self}} and {{code|list}} output options.
Correctly modifying the colour of the link, works both in the chat box and in forms:
<syntaxhighlight lang="mtmacro" line>
[r: strformat('<a style="color:red" href="%s">Click Me</a>', macroLinkText("Test@Lib:Test"))]
</syntaxhighlight>
 
Opening an overlay with arguments to the GM panel macro {{code|loadGMOverlay}} for all connected GMs using {{func|execLink}}.
 
* This is a very useful pattern to load an overlay for all players or GMs with a library token using {{code|onCampaignLoad}}.  
* In this example, the hypothetical overlay function can take text and background color arguments in a [[String_Property_List|String Property List]].
 
<syntaxhighlight lang="mtmacro" line>
[h: link = macroLinkText("loadGMOverlay@GM", "none", "text=white;background=black")]
[h: execLink(link, 0, "gm")]
</syntaxhighlight>
 
 
|also=
|also=
{{func|macroLink}}
{{func|macroLink}}
{{func|execLink}}
|changes=
{{change|1.3b55|Added {{code|gm-self}} and {{code|list}} output options.}}
{{change|1.3b56|Links created using this function will no longer show a tooltip when displayed in a dialog or frame.}}


}}
}}
[[Category:Miscellaneous Function]]
[[Category:Miscellaneous Function]]

Latest revision as of 23:59, 20 April 2023

macroLinkText() Function

• Introduced in version 1.3b48
Creates the text that would appear in a HTML tag for a link which will run the specified macro when clicked on. This is useful for callbacks in [dialog():] or [frame():]. If you just want to send a click-able link to someone use macroLink().

Usage

macroLinkText(macroName)
macroLinkText(macroName, output)
macroLinkText(macroName, output, args)
macroLinkText(macroName, output, args, target)

Parameters

  • macroName - The name of the macro to run when the link is clicked. The macroName is in the standard macro reference format (e.g. Macro@Lib:Token)
  • output - 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 parameter is "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):

Examples

To create the text that would go inside a form element as the action attribute, and that will call a macro named Test on the Library Token named Lib:Test: 
[r: macroLinkText("Test@Lib:Test","", "gm")]

Returns: macro://Test@Lib:Test/gm/impersonated?

To create the text that would go inside a form element as the action attribute and call the AddWeapon on the Library Token named Lib:PC which will act upon the Current Token: 

[r:macroLinkText('AddWeapon@Lib:PC', 'none', '', currentToken())]

Returns: macro://AddWeapon@Lib:PC/none/#ID#? where #ID# is the id of the Current Token.

Sending to multiple players and the GM in 1.3b55 

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

Correctly modifying the colour of the link, works both in the chat box and in forms: 

[r: strformat('<a style="color:red" href="%s">Click Me</a>', macroLinkText("Test@Lib:Test"))]

Opening an overlay with arguments to the GM panel macro loadGMOverlay for all connected GMs using execLink().

  • This is a very useful pattern to load an overlay for all players or GMs with a library token using onCampaignLoad.
  • In this example, the hypothetical overlay function can take text and background color arguments in a String Property List.
[h: link = macroLinkText("loadGMOverlay@GM", "none", "text=white;background=black")] 
[h: execLink(link, 0, "gm")]

See Also

macroLink() execLink()

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.
Retrieved from "https://wiki.rptools.info/index.php?title=macroLinkText&oldid=35286"