Character Vault
Any Concept / Any System
Compendium
Your System Come To Life
Roll20 for Android
Streamlined for your Tablet
Roll20 for iPad
Streamlined for your Tablet

Personal tools

Difference between revisions of "Button"

From Roll20 Wiki

Jump to: navigation, search
m (make "Styling button" a section, Add Roll button examples)
m (Change Tabs)
 
(54 intermediate revisions by 6 users not shown)
Line 1: Line 1:
''Main Article:'' '''[[Building Character Sheets]]'''
+
{{revdate}}{{BCS}}
 +
This page is about creating/editing [[Building Character Sheets|Custom Character Sheets]]''(Pro feature)'', and how to use <code><button></code> HTML element.
  
This page is about the <code><button></code> and it's known options for usage in creating [[Building Character Sheets|Custom Character Sheets]](Pro feature).
+
{{NavSheetDoc}}The <code><button></code> have three roll20-specific types that can be used in character sheets; <code>type="roll"</code>, <code>type="action"</code>, <code>type="compendium"</code>.
  
The <code><button></code> have three roll20-specific types that can be used in character sheets; <code>type="roll"</code>, <code>type="action"</code>, <code>type="compendium"</code>.
+
This guide gives a rundown of how each type is used, together with some examples on how to implement common things. More examples could be added under the appropriate section.
 +
{{orange| These tips & examples are made to work with [[Legacy Sheet]], so need adjustments to work with newer [[CSE]]-sheets. See the [[Character Sheet Enhancement]]-page for more info. [[User:1223200|1223200]] ([[User talk:1223200|talk]]) 16:12, 15 April 2021 (UTC)}}
  
== Roll Button ==
+
=General=
Example:
+
  
<code><button type="roll" value="/roll 1d20 + @{Bluff}" name="roll_BluffCheck"></button></code>
+
The code for the Example Buttons displayed at the top of this page:
  
* the <code>type</code>-attribute must be set to <code>roll</code>
+
<pre data-language="html" style="overflow:auto;white-space:pre-wrap;">
* the roll macro is defined in the <code>value</code>-attribute.
+
<button type="roll" name="roll_exampleroll1" value="/roll d20 + 4" ></button>
* the optional <code>name</code>-attribute allows the roll to be referenced in external Macros and Abilities. The name must be prefixed with <code>roll_</code> for this to work, and each roll button should have a unique name. Buttons in repeating sections automatically gain a unique prefix/suffix in their name.
+
<button type="roll" name="roll_exampleroll2" value="/roll d20 + 4">Roll Button</button>
 +
<button type="action" name="act_exampleaction" >Action Button</button>
 +
<button type="compendium" name="act_actionexample" >Compendium Button</button>
 +
</pre>
 +
 
 +
[[File:Custom-sheet-button-examples.png|center|thumbnail|550px|Examples of default [[#Roll Button|Roll Button]], [[#Action Button|Action Button]], and [[#Compendium Button|Compendium Button]]  ]]
 +
 
 +
== Roll Button ==
 +
The common use for buttons in Roll20 is for making a roll button. By default, roll buttons show a d20 icon, and if any text is added to be displayed on the button, it is shown after the d20 icon.  
 +
 
 +
Example:
 +
<pre data-language="html" style="overflow:auto;white-space:pre-wrap;">
 +
<button type="roll" value="/roll 1d20 + @{Bluff}" name="roll_BluffCheck">Roll Bluff</button>
 +
</pre>
  
 +
* '''<code>type</code>'''-attribute must be set to <code>roll</code>
 +
* '''<code>value</code>'''-attribute defines the the roll macro
 +
* '''<code>name</code>'''-attribute allows the roll to be referenced in external [[Macros]]&{{Text Chat}} as well as dragged to the [[Macro Quickbar]]. The name '''must''' be prefixed with <code>roll_</code> for it to work, and each roll button should have a unique name.
 +
** Buttons names in [[Repeating_Sections|repeating sections]] gain a unique prefix in their name based on their RowID and the rep section's name, placing the <code>name</code> last.
 +
** if you have multiple buttons with the same name, and you call the button name, Roll20 seems to call the last button in the HTML.
 +
** if button has no name, it cant be dragged to quickbar nor referenced in the chat.
 +
* ''(optional)'' add text to the Roll Button. in the above example, the button will show the d20 icon and the text "Roll Bluff". If left empty, the button only shows the default d20 icon. See the example image on this page.
  
 
To call a named roll button in the chat, it works similarly like calling a defined Ability macro from the [[Journal#Attributes_.26_Abilities_Tab |A & A tab]], e.g.  <code>%{Bob|BluffCheck}</code>. This will call the "BluffCheck" button of the character named "Bob".
 
To call a named roll button in the chat, it works similarly like calling a defined Ability macro from the [[Journal#Attributes_.26_Abilities_Tab |A & A tab]], e.g.  <code>%{Bob|BluffCheck}</code>. This will call the "BluffCheck" button of the character named "Bob".
  
 
===Roll Macro===
 
===Roll Macro===
To construct more advanced rolls, you should check the [[Macros]] and the [[Dice Reference]] pages.
+
{{NavMacroDocs}}
 +
Details on creating more advanced roll macros, check '''[[Complete Guide to Macros & Rolls‎]]'''.
  
 
The roll macro is placed in the <code>value</code> field.
 
The roll macro is placed in the <code>value</code> field.
Line 24: Line 46:
 
<code><button type="roll" '''value="/roll 1d20 + @{Bluff}"''' name="roll_BluffCheck"></button></code>
 
<code><button type="roll" '''value="/roll 1d20 + @{Bluff}"''' name="roll_BluffCheck"></button></code>
  
For creating more advanced rolls, you can choose to have parts of the macro defined in an attribute(and more easily edited by the player or [[Sheetworkers|sheetworkers]], such as:
 
  
<code><button type="roll" value="&{template:default} {{name=Magic attack (@{character_name}) }} {{Roll=[[@{intelligence}d6 + @{mana}d6 ]]}}" name="roll_Magic1"></button></code>
+
For creating more advanced rolls, you can choose to have parts of the macro defined in an attribute(and more easily edited by the player or [[Sheetworkers|sheetworkers]], or use [[Roll Templates]]:
 +
<pre data-language="html"  style="overflow:auto;white-space:pre-wrap;">
 +
<button type="roll" value="&{template:default} {{name=Magic attack (@{character_name}) }} {{Roll=[[@{intelligence}d6 + @{mana}d6 ]]}}" name="roll_Magic1"></button>
 +
</pre>
 +
 
 +
{{orange| Don't add line-breaks to to your roll macro or it might break the entire roll. Leave the whole <code><button></code>-element on a single row.}}
  
  
 
See also:
 
See also:
* [[Macros#Drop-Down_Prompts_for_Roll_Queries|Roll Queries]] - How to use Roll Queries in your buttons
 
 
* [[Select Attributes for Sheet Roll]] - An advanced technique for a dynamic roll button
 
* [[Select Attributes for Sheet Roll]] - An advanced technique for a dynamic roll button
 +
 +
===Roll Query, with Toggle===
 +
In your roll macro you can include an option [[Macros#Drop-Down_Prompts_for_Roll_Queries|roll query]], that gives a popup asking if you want to add some modifier, either through a simple text field, or a dropdown. However, some users of the sheet might not always use it, so an option to turn on/off this popup is a good idea.
 +
 +
Here is a simple way you can have an optional element in your rolls that can be toggled with a simple checkbox.
 +
 +
<pre data-language="html" style="overflow:auto;white-space:pre-wrap;">
 +
<span>Modifier popup for rolls?<input type="checkbox" name="attr_rollmod" value="?{Modifiers?|0}"></span>
 +
<input type="number" name="attr_composure" value="1" >
 +
<button type="roll" name="roll_composure" value="&{template:default} {{name=Composure check}} {{result=[[(@{composure} + @{rollmod})d6]]}}"></button>
 +
<input type="number" name="attr_reaction" value="1" >
 +
<button type="roll" name="roll_reaction" value="&{template:default} {{name=Reaction check}} {{result=[[(@{reaction} + @{rollmod})d6]]}}"></button>
 +
</pre>
 +
 +
You can then use the checkbox's <code>rollmod</code>-attribute in multiple buttons at the same time, which means you can toggle the roll query on the whole sheet at the same time.
 +
 +
If you want to have more options, you can replace the checkbox with an <code><select></code> like this:
 +
 +
<pre data-language="html" style="overflow:auto;white-space:pre-wrap;">
 +
<select name="attr_rollmod">
 +
  <option value="0" checked>Nothing</option>
 +
  <option value="?{Modifier?|0}">Ask for Roll Modifier</option>
 +
  <option value="@{level}">Add level to roll</option>
 +
</select>
 +
</pre>
  
 
===Initiative===
 
===Initiative===
[[Macros#Rolling_For_Initiative]]
+
More info: [[Macros#Rolling_For_Initiative]] & [[Turn Tracker]]
  
To send a roll result directly to the [[Turn Tracker]], first, select the Token you wish to roll for initiative, use make a roll that has the <code>&{tracker}</code> in it.
+
To send a roll result directly to the [[Turn Tracker]], first, select the [[Token]] you wish to roll for initiative, use make a roll that has the <code>&{tracker}</code> in it.
  
Example:
+
Examples:
 +
<pre data-language="html" style="overflow:auto;white-space:pre-wrap;">
 +
<button type="roll" name="roll_init" value="/roll 1d10 + 2 &{tracker}"></button>
 +
<button type="roll" name="roll_init2" value="/roll 1d20 + ?{Modifier?|0} &{tracker}">Init</button>
 +
<button type="roll" name="roll_initiative" value="&{template:default} {{name=Initiative}} {{Roll=[[d10+@{wis_mod} &{tracker}]]}}"></button>
 +
</pre>
 +
<code></code>
  
<code>/roll 1d20 + 5 &{tracker}</code>
+
===Roll Template===
 +
''Main Article:'' '''[[Roll Templates]]'''
  
<code><nowiki> &{template:default} {{name=Initiative}} {{Roll=[[d10+@{wis_mod}]]}} &{tracker}</nowiki></code>
+
With your roll buttons, you can make simple rolls like <code>/roll d20 + @{bluff}}</code>, but in many cases you might want to make use of [[Roll Templates]] to create better output of your rolls. Roll Templates can also be used to create pseudo-conditional behavior, such as showing a roll section only if you roll a critical success on a previous section.
 +
 
 +
<pre data-language="html" style="overflow:auto;white-space:pre-wrap;">
 +
<button type="roll" name="roll_attack" value="&{template:default} {{name=Attack}} {{To Hit=[[1d20+@{str}]]}} {{Damage=[[2d8+2]]}}">
 +
</pre>
 +
 
 +
There exist a [[Roll_Templates#Default|Default]] roll template that can be accessed in any sheet, but it's a much better idea to at least use [[Roll_Templates#Jakob.27s_Better_Default_Rolltemplate|Jakob's Better Default Rolltemplate]] which is just a cleaner version of the default template, and is at least a start for creating your own.
 +
 
 +
To include Jacob's roll template to your sheet, simply copy the HTML code and save it at the end of your sheet's HTML-file, and do the same for the CSS code. You similarly copy other sheet's roll template to your sheet to enable their use.
 +
 
 +
===Token Action===
 +
You can force a roll button to appear as a [[Token Action|token action]] on an attached [[token]], by adding <code>class="tokenaction"</code> to the button.
 +
 
 +
<pre data-language="html" style="overflow:auto;white-space:pre-wrap;">
 +
<button type="roll" class="tokenaction" name="roll_initiative" value="&{template:default} {{name=Initiative}} {{Roll=[[d10+@{wis_mod} &{tracker}]]}}"></button>
 +
</pre>
 +
 
 +
'''Caution:''' Token actions will have a fixed location in the order, and users have no ability to control whether those token actions appear or not, and they cannot not be renamed. These are fine to use in custom sheet in your own games, but few or no community sheets have them built in due to this annoyance.
 +
 
 +
===[[Roll Table]]===
 +
You can use [[Roll Tables]] in your roll buttons to create custom rolls, but for it to work, the game needs to have the used roll tables created separately. and made available to the players, for the rolls to work.
 +
 
 +
<pre data-language="html" style="overflow:auto;white-space:pre-wrap;">
 +
<button type="roll" name="roll_fumble" value="/roll 2t[fumble]"></button>
 +
</pre>
  
 
===API===
 
===API===
 +
See [[Complete_Guide_to_Macros_%26_Rolls#API|API-section]] from the [[Complete Guide to Macros & Rolls]] for more examples of general use.
 +
 
Instead of using just normal macros in your rolls, you can choose to include API commands(require for that API to be installed in a game to work.
 
Instead of using just normal macros in your rolls, you can choose to include API commands(require for that API to be installed in a game to work.
  
Depending on how the API you want to incorporate works, you might be able to mix normal macros and API commands in the same button, like using the stat-editing APi to automatically remove an arrow when you roll an corresponding attack.
+
Depending on how the API you want to incorporate works, you might be able to mix normal macros and API commands in the same button, like using the stat-editing API to automatically remove an arrow when you roll an corresponding attack.
  
 
If you use these in sheet that will be published on Roll20 GitHub, you need to make API-based rolls optional.
 
If you use these in sheet that will be published on Roll20 GitHub, you need to make API-based rolls optional.
Line 53: Line 136:
 
Star Wars FFG and the Genesys sheet are two examples of sheet that uses custom API for rolling their dice, as the default Roll20 macros can't handle the custom things required.
 
Star Wars FFG and the Genesys sheet are two examples of sheet that uses custom API for rolling their dice, as the default Roll20 macros can't handle the custom things required.
  
 +
[[Script:ChatSetAttr]] can be combined with normal macros to edit stats while a roll is made, and even make the changes depend on the results for  the roll.
 +
 +
There exists a number of API scripts for ammo & spelslot tracking that can be configured to trigger when a roll is made, which means the button itself doesn't have to be edited to accommodate the API as an option, but they can run completely independently.
  
 
'''Wild Die Example'''
 
'''Wild Die Example'''
Line 60: Line 146:
 
Button to roll <code>5d6+2</code> according with the [https://en.wikipedia.org/wiki/D6_System#Wild_die Wild Die] method(and have the highest rolled normal dice be removed from the result if you roll a fumble on your wild die):
 
Button to roll <code>5d6+2</code> according with the [https://en.wikipedia.org/wiki/D6_System#Wild_die Wild Die] method(and have the highest rolled normal dice be removed from the result if you roll a fumble on your wild die):
  
 +
<pre data-language="html" style="margin-bottom: 5px;overflow:auto;">
 
<button type="roll" value="!wd [[5d6+2]]" name="roll_wilddieexample" ></button>
 
<button type="roll" value="!wd [[5d6+2]]" name="roll_wilddieexample" ></button>
 +
</pre>
 +
 +
 +
 +
===Multiple Commands===
 +
This workaround allows the use of multiple line commands such as including an emote, roll template, and one or more API commands all in the same sheet roll button.
 +
Normally, only a single command line will be executed with type="roll" buttons. To overcome this limitation, use a textarea input as a "placeholder" and HTML substitutions for new-lines and carriage returns (ie "&amp;#13;&amp;#10;").
 +
example;
 +
<pre data-language="html" style="margin-bottom: 5px;overflow:auto;">
 +
<button type="roll" name="roll_multiline" value="@{multi_textarea}">Roll Multi-line Macro</button>
 +
<textarea name="attr_multi_textarea" class="hidden">Line One&amp;#13;&amp;#10;Line Two&amp;#13;&amp;#10;Line Three</textarea>
 +
</pre>
 +
 +
note: The textarea can be hidden as in the example above, or exposed on the sheet to allow customization of the roll.
 +
 +
==Roll Parsing==
 +
{{main|Custom Roll Parsing}}
 +
 +
As of July 13th, 2021, character sheets can now combine the functionality of roll buttons and action buttons to allow for roll parsing.
 +
 +
You essentially now have an action button that will perform dice rolls, with input from [[sheetworkers]]. CRP also requires changes to the [[Roll Template]].
 +
 +
* Official Documentation: {{hc|articles/4403865972503-Custom-Roll-Parsing-for-Character-Sheets Custom Roll Parsing for Character Sheets}}.
 +
* {{fpl|10296045/ Oosh's explanation}}
 +
* [https://app.roll20.net/forum/post/10534166/action-buttons-in-the-macro-bar/ Action Buttons in the Macro Bar]
 +
{{Ex}}
 +
 +
<pre style="overflow:auto;white-space:pre-wrap;" data-language="html">
 +
<button type="action" name="act_test">Click me</button>
 +
 +
<rolltemplate class="sheet-rolltemplate-test">
 +
    <div class="sheet-template-container">
 +
        <h1>{{name}}</h1>
 +
        <div class="sheet-results">
 +
            <h4>Result = {{roll1}}</h4>
 +
            <h4>Custom Result = {{computed::roll1}}</h4>
 +
        </div>
 +
    </div>
 +
</rolltemplate>
 +
 +
<script type="text/worker">
 +
    on('clicked:test', (info) => {
 +
        startRoll("&{template:test} {{name=Test}} {{roll1=[[1d20]]}}", (results) => {
 +
            const total = results.results.roll1.result
 +
            const computed = total % 4;
 +
 +
            finishRoll(
 +
                results.rollId,
 +
                {
 +
                    roll1: computed,
 +
                }
 +
            );
 +
        });
 +
    });
 +
</script></pre>
  
 
== Action Button ==
 
== Action Button ==
Example:
+
Action buttons can be used as events to trigger [[Sheet_Worker_Scripts|Sheetworkers]], and cannot be used for send messages to the {{Text Chat}}.
  
<code><button type="action" name="act_reduce"></button></code>
+
As of July 2021, Action Buttons can send messages to the chat, including roll templates. See [[Custom_Roll_Parsing]].
  
Action buttons can be used as events to trigger [[Sheet_Worker_Scripts|Sheetworkers]].
+
{{orange|You can't use underscores in the name of the action button. <code>act_reduce</code> is good, <code>act_reduce_dex</code> is bad}}
 +
 
 +
{{ex}}
 +
<pre data-language="html" style="overflow:auto;white-space:pre-wrap;">
 +
<button type="action" name="act_activate">Activate!</button>
 +
<script type="text/worker">
 +
on("clicked:activate", function() {
 +
  // write your sheetworker to do things here
 +
  console.log("Activate button clicked"); //example, just sends text to the browser console(hidden)
 +
});
 +
</script>
 +
</pre>
  
 
* the <code>type</code>-attribute must be set to <code>action</code>
 
* the <code>type</code>-attribute must be set to <code>action</code>
 
* the <code>name</code>-attribute must be defined, and have a <code>act_</code> prefix to function
 
* the <code>name</code>-attribute must be defined, and have a <code>act_</code> prefix to function
* '''Do not use action button names that include underscores''', otherwise they will fail to trigger as a detectable event for sheetworkers.
+
** '''Do not use action button names that include underscores''', otherwise they will fail to trigger as a detectable event for sheetworkers.
 +
** '''Bug:''' Having a position property applied to one of the containers of the button in the repeating row causes the button to not be recognized.
  
  
Two common uses:
+
It a good idea to display text inside the button .
 +
 
 +
'''Common uses:'''
 
* Swap between sheet tabs/visible areas (CSS Wizardry [[CSS_Wizardry#Tabs|Example]])
 
* Swap between sheet tabs/visible areas (CSS Wizardry [[CSS_Wizardry#Tabs|Example]])
 
* Increment stats, such as ammo usage
 
* Increment stats, such as ammo usage
 +
* below are some examples
 +
 +
===Change Tabs===
 +
[[File:Tabs-example2.gif|300px|thumbnail|right]]
 +
Details: '''[[CSS_Wizardry#Tabs]]'''
 +
 +
You can use action buttons to change what page is shown on the sheet, by having them change the tab name that should be shown.
 +
 +
Adjusting looks of Action buttons is much easier than for the [[CSS_Wizardry#radio_input_.2B_span_.method|invisible radio input + span]]-method for navigating pages.
 +
<br clear=all>
  
 
=== Adjust Stats Examples ===
 
=== Adjust Stats Examples ===
Made by [https://app.roll20.net/forum/post/8044523/one-button-to-modify-several-attributes/?pageforid=8044582#post-8044582 GiGs] and expanded here. Each step is expanded and commented for clarity.
+
{{fpl|8044582 Example}} by [[GiGs]], and expanded here. Each step is expanded and commented for clarity.
  
 
'''Add one to the '''level''' stat , when a button is clicked.'''
 
'''Add one to the '''level''' stat , when a button is clicked.'''
Line 85: Line 251:
 
Create an action button on the sheet:
 
Create an action button on the sheet:
  
<pre data-language="html" style="margin-bottom: 5px">
+
<pre data-language="html" style="margin-bottom: 5px;overflow:auto;">
<button type="action" name="act_add">
+
<button type="action" name="act_add">Add level</button>
 
</pre>
 
</pre>
  
 
Then add this code the the sheetworker section of the sheet:
 
Then add this code the the sheetworker section of the sheet:
  
<pre data-language="javascript" style="margin-bottom: 5px">
+
<pre data-language="javascript" style="margin-bottom: 5px;overflow:auto;">
 
on('clicked:add', function() {
 
on('clicked:add', function() {
 
     getAttrs(['level'], function(values) {
 
     getAttrs(['level'], function(values) {
Line 110: Line 276:
 
Create an action button on the sheet:
 
Create an action button on the sheet:
  
<pre data-language="html" style="margin-bottom: 5px">
+
<pre data-language="html" style="overflow:auto;white-space:pre-wrap;">
 
<button type="action" name="act_reduce">
 
<button type="action" name="act_reduce">
 
</pre>
 
</pre>
Line 116: Line 282:
 
Then add this code the the sheetworker section of the sheet:
 
Then add this code the the sheetworker section of the sheet:
  
<pre data-language="javascript" style="margin-bottom: 5px">
+
<pre data-language="javascript" style="margin-bottom: 5px;overflow:auto;">
 
on('clicked:reduce', function() {
 
on('clicked:reduce', function() {
 
     // make an array of the attributes you plan to adjust, for ease of use later
 
     // make an array of the attributes you plan to adjust, for ease of use later
Line 135: Line 301:
 
</pre>
 
</pre>
  
==Styling Roll Buttons==
+
===Reset Stats===
[[CSS_Wizardry#Styling_Roll_Buttons|Styling Roll Buttons]] shows a few examples on how to style your button to look differently.
+
Sometime you might want to reset some stats to their initial values, without having to do it manually or to make a new sheet. This can easily be done with an action button & a sheetworker.
 +
 
 +
<pre data-language="html" style="overflow:auto;white-space:pre-wrap;">
 +
<h3>Main Stats</h3>
 +
<label>Strength: <input name="attr_str" type="number" value=""></label>
 +
<label>Dexterity: <input name="attr_dex" type="number" value=""></label>
 +
<label>Mind: <input name="attr_mind" type="number" value=""></label>
 +
<label>HP: <input name="attr_hp" type="number" value="10"></label>
 +
<button type="action" name="act_reset" class="reset-button">Reset Main Stats</button>
 +
 
 +
<script type="sheet/worker">
 +
on('clicked:reset', () => {
 +
    setAttrs({
 +
        str: 0,
 +
        dex: 0,
 +
        mind: 0,
 +
        hp: 10
 +
    });
 +
});
 +
</script>
 +
</pre>
 +
 
 +
::'''Note:''' To avoid accidentally pressing the Reset button, it can be a good idea to hide or protect the button. With [[CSE]], you could replace the Reset button with a <code><nowiki><a href="#"></nowiki></code> link, which opens a [[CSE#Warning_Popup|Warning Popup]], where the actual reset button is located.
 +
 
 +
===JQuery functions===
 +
JQuery can be used to add enhanced listeners which give more functionality than the standard sheetworker listeners e.g. if the alt, shift or ctrl keys were down when the event was triggered.
 +
 
 +
<pre data-language="html" style="overflow:auto;white-space:pre-wrap;">
 +
<p>Click for a normal (public) roll. Hold down the <code>alt</code> key and click to whisper the roll to the gm.</p>
 +
<button class="roll">1d20</button>
 +
 
 +
<script type="text/worker">
 +
    $20('button.roll').on('click', async (e) => {
 +
        const roll = e.altKey ? '/w gm [[1d20]]' : '[[1d20]]';
 +
        const results = await startRoll(roll);
 +
        finishRoll(results.rollId);
 +
    });
 +
</script>
 +
</pre>
 +
See [[JQuery#Functions]] for more details.
  
 
== Compendium Button ==
 
== Compendium Button ==
Line 143: Line 348:
 
The compendium button can be used to open a compendium entry directly from a character sheet, in the same way as if you clicked on an entry in the in-app compendium. This can be used as a more convenient way to access rules and descriptions, for example, for a spell, the compendium button can be used to easily view the full description for that spell.
 
The compendium button can be used to open a compendium entry directly from a character sheet, in the same way as if you clicked on an entry in the in-app compendium. This can be used as a more convenient way to access rules and descriptions, for example, for a spell, the compendium button can be used to easily view the full description for that spell.
  
 +
The syntax is <code><button type="compendium" value="<entryname>"></code>.
 +
 +
Example:
 +
 +
<pre data-language="html" style="margin-bottom: 5px;overflow:auto;">
 +
<button type="compendium" value="Bard">Bard</button>
 +
</pre>
 +
 +
=Styling Roll Buttons=
 +
Here are shows a few examples on how to style your button to look differently.
 +
 +
The Action and Compendium buttons looks slightly different by default(see picture at top of article), but can be styled all the same.
 +
 +
==Remove the default d20 icon==
 +
 +
Want a roll button that doesn't have a d20 image in it? Simple!
 +
 +
'''CSS:'''
 +
<pre data-language="css">
 +
.ui-dialog .charsheet button[type=roll]::before {
 +
    content: "";
 +
}
 +
</pre>
 +
 +
'''HTML:'''
 +
<pre data-language="html" style="overflow:auto;white-space:pre-wrap;">
 +
<button class="sheet-blank-button" name="roll_BluffCheck" value="/roll 1d20 + @{Bluff}" type="roll">Bluff</button>
 +
</pre>
 +
 +
The d20 is a single character with the [[#dicefontd20|dicefontd20]] font-family in the button's <code>::before</code> pseudo-element. Setting the content to an empty string removes it.
 +
 +
==Roll button with a d6 icon==
 +
By using the [[CSS_Wizardry#Icon_Fonts|icon fonts]] available in Roll20, we can replace the d20 icon it with a different dice, instead of removing it.
 +
 +
'''CSS:'''
 +
<pre data-language="css">
 +
button[type=roll].sheet-d6-dice::before {
 +
    font-family: 'dicefontd6';
 +
    content: 'F ';
 +
}
 +
</pre>
 +
 +
'''HTML:'''
 +
<pre data-language="html" style="overflow:auto;white-space:pre-wrap;">
 +
<button class="sheet-d6-dice" name="roll_dex" value="/roll @{dex}d6" type="roll"></button>
 +
</pre>
 +
 +
==Button to blend in==
 +
 +
The {{repo|Roll20/roll20-character-sheets/tree/master/Stargate-RPG Stargate sheet}} is an example of a sheet that has turned the Attribute & Skill buttons to look like just text, setting the border and button background to transparent, and reducing it's padding.
 +
 +
==Button with an image==
 +
The {{repo|roll20-character-sheets/tree/master/Ambition_Avarice Ambition & Avarice}} sheet has two examples where the roll buttons have been changed from the default d20 icon, to make the d20 and d5 buttons look hand-drawn. For the image to stay in place when you hover over it with a mouse, you need to do some manual adjustments for <code>:hover</code> CSS class for the image position, that may vary depending on the size/shape of the image. [[Image use in character sheets]] contains more examples.
 +
 +
==Button Dynamic Text==
 +
By placing an [[CSS Wizardry#Attribute-Backed_.3Cspan.3Es|Attribute-Backed Span<span>]] inside the button.
 +
 +
You then have an input elsewhere with the identical name that can then change the value of the attribute displayed on the button.
 +
 +
<pre data-language="html" style="overflow:auto;white-space:pre-wrap;">
 +
<button type="roll" value="/roll 3d6" name="roll_attack"><span name="attr_attackname"></span></button>
 +
<input type="text" name="attr_attackname" value="Sword">
 +
</pre>
  
 
= See Also =
 
= See Also =
 
* [[Building Character Sheets]] - Main Article
 
* [[Building Character Sheets]] - Main Article
* [[Macros]] - how to construct the macros used inside buttons
+
* '''[[Complete Guide to Macros & Rolls‎]]'''
** [[Macros#Rolling_For_Initiative|Initiative Roll]]
+
** {{Text Chat}} - where the roll results appear, & info on the common chat commands
** [[Macros#Drop-Down_Prompts_for_Roll_Queries|Roll Queries]] - How to use Roll Queries in your buttons  
+
** [[Dice Reference]] - Comprehensive list of how the Roll20 dice-rolling syntax works, and list the features available
* [[Dice Reference]] - The Roll20 dice/math syntax
+
** [[Macros]] - How to create macros, and other info on how the Roll20 <span style="font-family:Pictos;">q</span>Text Chat works, like referencing stats on character sheets, roll queries, nesting macros & initiative
* [[Select Attributes for Sheet Roll]] - An advanced technique for a dynamic roll button
+
*** [[Macros#Rolling_For_Initiative|Initiative Roll]]
* [[API]] - if you want to create roll buttons that uses API commands
+
*** [[Macros#Drop-Down_Prompts_for_Roll_Queries|Roll Queries]] - How to use Roll Queries in your buttons  
 +
** [[Roll Templates]] - a method of formatting roll results in the chat, with some extra functions
 +
** [[API]]''(Pro Only)'' - API commands can be used in the <span style="font-family:Pictos;">q</span>Text Chat
 +
* '''Specific Tricks'''
 +
** [[Select Attributes for Sheet Roll]] - An advanced technique for a dynamic roll button
 +
** [[Reusing Rolls]] - clever way of reusing rolls within the same call
 +
 
 
<br>
 
<br>
 
<br>
 
<br>
 
[[Category:Character Sheet Creation]]
 
[[Category:Character Sheet Creation]]

Latest revision as of 05:44, 20 July 2024

This page is about creating/editing Custom Character Sheets(Pro feature), and how to use <button> HTML element.

The <button> have three roll20-specific types that can be used in character sheets; type="roll", type="action", type="compendium".

This guide gives a rundown of how each type is used, together with some examples on how to implement common things. More examples could be added under the appropriate section.


Contents

[edit] General

The code for the Example Buttons displayed at the top of this page:

<button type="roll" name="roll_exampleroll1" value="/roll d20 + 4" ></button>
<button type="roll" name="roll_exampleroll2" value="/roll d20 + 4">Roll Button</button>
<button type="action" name="act_exampleaction" >Action Button</button>
<button type="compendium" name="act_actionexample" >Compendium Button</button>
Examples of default Roll Button, Action Button, and Compendium Button

[edit] Roll Button

The common use for buttons in Roll20 is for making a roll button. By default, roll buttons show a d20 icon, and if any text is added to be displayed on the button, it is shown after the d20 icon.

Example:

<button type="roll" value="/roll 1d20 + @{Bluff}" name="roll_BluffCheck">Roll Bluff</button>
  • type-attribute must be set to roll
  • value-attribute defines the the roll macro
  • name-attribute allows the roll to be referenced in external Macros&q Text Chat as well as dragged to the Macro Quickbar. The name must be prefixed with roll_ for it to work, and each roll button should have a unique name.
    • Buttons names in repeating sections gain a unique prefix in their name based on their RowID and the rep section's name, placing the name last.
    • if you have multiple buttons with the same name, and you call the button name, Roll20 seems to call the last button in the HTML.
    • if button has no name, it cant be dragged to quickbar nor referenced in the chat.
  • (optional) add text to the Roll Button. in the above example, the button will show the d20 icon and the text "Roll Bluff". If left empty, the button only shows the default d20 icon. See the example image on this page.

To call a named roll button in the chat, it works similarly like calling a defined Ability macro from the A & A tab, e.g. %{Bob|BluffCheck}. This will call the "BluffCheck" button of the character named "Bob".

[edit] Roll Macro

Details on creating more advanced roll macros, check Complete Guide to Macros & Rolls‎.

The roll macro is placed in the value field.

<button type="roll" value="/roll 1d20 + @{Bluff}" name="roll_BluffCheck"></button>


For creating more advanced rolls, you can choose to have parts of the macro defined in an attribute(and more easily edited by the player or sheetworkers, or use Roll Templates:

<button type="roll" value="&{template:default} {{name=Magic attack (@{character_name}) }} {{Roll=[[@{intelligence}d6 + @{mana}d6 ]]}}" name="roll_Magic1"></button>


See also:

[edit] Roll Query, with Toggle

In your roll macro you can include an option roll query, that gives a popup asking if you want to add some modifier, either through a simple text field, or a dropdown. However, some users of the sheet might not always use it, so an option to turn on/off this popup is a good idea.

Here is a simple way you can have an optional element in your rolls that can be toggled with a simple checkbox.

<span>Modifier popup for rolls?<input type="checkbox" name="attr_rollmod" value="?{Modifiers?|0}"></span>
<input type="number" name="attr_composure" value="1" >
<button type="roll" name="roll_composure" value="&{template:default} {{name=Composure check}} {{result=[[(@{composure} + @{rollmod})d6]]}}"></button>
<input type="number" name="attr_reaction" value="1" >
<button type="roll" name="roll_reaction" value="&{template:default} {{name=Reaction check}} {{result=[[(@{reaction} + @{rollmod})d6]]}}"></button>

You can then use the checkbox's rollmod-attribute in multiple buttons at the same time, which means you can toggle the roll query on the whole sheet at the same time.

If you want to have more options, you can replace the checkbox with an <select> like this:

<select name="attr_rollmod">
   <option value="0" checked>Nothing</option>
   <option value="?{Modifier?|0}">Ask for Roll Modifier</option>
   <option value="@{level}">Add level to roll</option>
</select>

[edit] Initiative

More info: Macros#Rolling_For_Initiative & Turn Tracker

To send a roll result directly to the Turn Tracker, first, select the Token you wish to roll for initiative, use make a roll that has the &{tracker} in it.

Examples:

<button type="roll" name="roll_init" value="/roll 1d10 + 2 &{tracker}"></button>
<button type="roll" name="roll_init2" value="/roll 1d20 + ?{Modifier?|0} &{tracker}">Init</button>
<button type="roll" name="roll_initiative" value="&{template:default} {{name=Initiative}} {{Roll=[[d10+@{wis_mod} &{tracker}]]}}"></button>

[edit] Roll Template

Main Article: Roll Templates

With your roll buttons, you can make simple rolls like /roll d20 + @{bluff}}, but in many cases you might want to make use of Roll Templates to create better output of your rolls. Roll Templates can also be used to create pseudo-conditional behavior, such as showing a roll section only if you roll a critical success on a previous section.

<button type="roll" name="roll_attack" value="&{template:default} {{name=Attack}} {{To Hit=[[1d20+@{str}]]}} {{Damage=[[2d8+2]]}}">

There exist a Default roll template that can be accessed in any sheet, but it's a much better idea to at least use Jakob's Better Default Rolltemplate which is just a cleaner version of the default template, and is at least a start for creating your own.

To include Jacob's roll template to your sheet, simply copy the HTML code and save it at the end of your sheet's HTML-file, and do the same for the CSS code. You similarly copy other sheet's roll template to your sheet to enable their use.

[edit] Token Action

You can force a roll button to appear as a token action on an attached token, by adding class="tokenaction" to the button.

<button type="roll" class="tokenaction" name="roll_initiative" value="&{template:default} {{name=Initiative}} {{Roll=[[d10+@{wis_mod} &{tracker}]]}}"></button>

Caution: Token actions will have a fixed location in the order, and users have no ability to control whether those token actions appear or not, and they cannot not be renamed. These are fine to use in custom sheet in your own games, but few or no community sheets have them built in due to this annoyance.

[edit] Roll Table

You can use Roll Tables in your roll buttons to create custom rolls, but for it to work, the game needs to have the used roll tables created separately. and made available to the players, for the rolls to work.

<button type="roll" name="roll_fumble" value="/roll 2t[fumble]"></button>

[edit] API

See API-section from the Complete Guide to Macros & Rolls for more examples of general use.

Instead of using just normal macros in your rolls, you can choose to include API commands(require for that API to be installed in a game to work.

Depending on how the API you want to incorporate works, you might be able to mix normal macros and API commands in the same button, like using the stat-editing API to automatically remove an arrow when you roll an corresponding attack.

If you use these in sheet that will be published on Roll20 GitHub, you need to make API-based rolls optional.

Star Wars FFG and the Genesys sheet are two examples of sheet that uses custom API for rolling their dice, as the default Roll20 macros can't handle the custom things required.

Script:ChatSetAttr can be combined with normal macros to edit stats while a roll is made, and even make the changes depend on the results for the roll.

There exists a number of API scripts for ammo & spelslot tracking that can be configured to trigger when a roll is made, which means the button itself doesn't have to be edited to accommodate the API as an option, but they can run completely independently.

Wild Die Example

Script:Wild Dice is another API example that could be used in roll buttons.

Button to roll 5d6+2 according with the Wild Die method(and have the highest rolled normal dice be removed from the result if you roll a fumble on your wild die):

<button type="roll" value="!wd [[5d6+2]]" name="roll_wilddieexample" ></button>


[edit] Multiple Commands

This workaround allows the use of multiple line commands such as including an emote, roll template, and one or more API commands all in the same sheet roll button. Normally, only a single command line will be executed with type="roll" buttons. To overcome this limitation, use a textarea input as a "placeholder" and HTML substitutions for new-lines and carriage returns (ie "&#13;&#10;"). example;

<button type="roll" name="roll_multiline" value="@{multi_textarea}">Roll Multi-line Macro</button>
<textarea name="attr_multi_textarea" class="hidden">Line One&#13;&#10;Line Two&#13;&#10;Line Three</textarea>

note: The textarea can be hidden as in the example above, or exposed on the sheet to allow customization of the roll.

[edit] Roll Parsing

Main Page: Custom Roll Parsing

As of July 13th, 2021, character sheets can now combine the functionality of roll buttons and action buttons to allow for roll parsing.

You essentially now have an action button that will perform dice rolls, with input from sheetworkers. CRP also requires changes to the Roll Template.


Example:

<button type="action" name="act_test">Click me</button>

<rolltemplate class="sheet-rolltemplate-test">
    <div class="sheet-template-container">
        <h1>{{name}}</h1>
        <div class="sheet-results">
            <h4>Result = {{roll1}}</h4>
            <h4>Custom Result = {{computed::roll1}}</h4>
        </div>
    </div>
</rolltemplate>

<script type="text/worker">
    on('clicked:test', (info) => {
        startRoll("&{template:test} {{name=Test}} {{roll1=[[1d20]]}}", (results) => {
            const total = results.results.roll1.result
            const computed = total % 4;

            finishRoll(
                results.rollId,
                {
                    roll1: computed,
                }
            );
        });
    });
</script>

[edit] Action Button

Action buttons can be used as events to trigger Sheetworkers, and cannot be used for send messages to the q Text Chat.

As of July 2021, Action Buttons can send messages to the chat, including roll templates. See Custom_Roll_Parsing.



Example:

<button type="action" name="act_activate">Activate!</button>
<script type="text/worker">
on("clicked:activate", function() {
  // write your sheetworker to do things here
  console.log("Activate button clicked"); //example, just sends text to the browser console(hidden)
});
</script>
  • the type-attribute must be set to action
  • the name-attribute must be defined, and have a act_ prefix to function
    • Do not use action button names that include underscores, otherwise they will fail to trigger as a detectable event for sheetworkers.
    • Bug: Having a position property applied to one of the containers of the button in the repeating row causes the button to not be recognized.


It a good idea to display text inside the button .

Common uses:

  • Swap between sheet tabs/visible areas (CSS Wizardry Example)
  • Increment stats, such as ammo usage
  • below are some examples

[edit] Change Tabs

Tabs-example2.gif

Details: CSS_Wizardry#Tabs

You can use action buttons to change what page is shown on the sheet, by having them change the tab name that should be shown.

Adjusting looks of Action buttons is much easier than for the invisible radio input + span-method for navigating pages.

[edit] Adjust Stats Examples

Example(Forum) by GiGs, and expanded here. Each step is expanded and commented for clarity.

Add one to the level stat , when a button is clicked.

Create an action button on the sheet:

<button type="action" name="act_add">Add level</button>

Then add this code the the sheetworker section of the sheet:

on('clicked:add', function() {
    getAttrs(['level'], function(values) {
        // get the level stat, and coerce into a numerical value.
        const level = +values.level || 0; 
        // increase by 1
        const newlevel = level +1;
        // save the updated attribute to the sheet
        setAttrs({
           level: newlevel 
        });
   });
});

Reducing several stats with one button press.

Create an action button on the sheet:

<button type="action" name="act_reduce">

Then add this code the the sheetworker section of the sheet:

on('clicked:reduce', function() {
    // make an array of the attributes you plan to adjust, for ease of use later
    const attributes = ['list of attributes to adjust'];
    getAttrs(attributes, function(values) {
        const settings = {}; // make a variable to hold the changed attributes
        // loop through the attributes, get the value, then subtract 1
        attributes.forEach(att => {  // in each go through the loop, "att" becomes the next attribute
            let tempattribute = +values.att || 0;
            tempattribute -= 1;
            // store the changed attribute in the settings variable:
            settings[att] = tempattribute;
        });
        // save the updated attributes to the sheet
        setAttrs(settings);
   });
});

[edit] Reset Stats

Sometime you might want to reset some stats to their initial values, without having to do it manually or to make a new sheet. This can easily be done with an action button & a sheetworker.

<h3>Main Stats</h3>
<label>Strength: <input name="attr_str" type="number" value=""></label>
<label>Dexterity: <input name="attr_dex" type="number" value=""></label>
<label>Mind: <input name="attr_mind" type="number" value=""></label>
<label>HP: <input name="attr_hp" type="number" value="10"></label>
<button type="action" name="act_reset" class="reset-button">Reset Main Stats</button>

<script type="sheet/worker">
on('clicked:reset', () => {
    setAttrs({
        str: 0,
        dex: 0,
        mind: 0,
        hp: 10
    });
});
</script>
Note: To avoid accidentally pressing the Reset button, it can be a good idea to hide or protect the button. With CSE, you could replace the Reset button with a <a href="#"> link, which opens a Warning Popup, where the actual reset button is located.

[edit] JQuery functions

JQuery can be used to add enhanced listeners which give more functionality than the standard sheetworker listeners e.g. if the alt, shift or ctrl keys were down when the event was triggered.

<p>Click for a normal (public) roll. Hold down the <code>alt</code> key and click to whisper the roll to the gm.</p>
<button class="roll">1d20</button>

<script type="text/worker">
    $20('button.roll').on('click', async (e) => {
        const roll = e.altKey ? '/w gm [[1d20]]' : '[[1d20]]';
        const results = await startRoll(roll);
        finishRoll(results.rollId);
    });
</script>

See JQuery#Functions for more details.

[edit] Compendium Button

Main Article: Compendium Button

The compendium button can be used to open a compendium entry directly from a character sheet, in the same way as if you clicked on an entry in the in-app compendium. This can be used as a more convenient way to access rules and descriptions, for example, for a spell, the compendium button can be used to easily view the full description for that spell.

The syntax is <button type="compendium" value="<entryname>">.

Example:

<button type="compendium" value="Bard">Bard</button>

[edit] Styling Roll Buttons

Here are shows a few examples on how to style your button to look differently.

The Action and Compendium buttons looks slightly different by default(see picture at top of article), but can be styled all the same.

[edit] Remove the default d20 icon

Want a roll button that doesn't have a d20 image in it? Simple!

CSS:

.ui-dialog .charsheet button[type=roll]::before {
    content: "";
}

HTML:

<button class="sheet-blank-button" name="roll_BluffCheck" value="/roll 1d20 + @{Bluff}" type="roll">Bluff</button>

The d20 is a single character with the dicefontd20 font-family in the button's ::before pseudo-element. Setting the content to an empty string removes it.

[edit] Roll button with a d6 icon

By using the icon fonts available in Roll20, we can replace the d20 icon it with a different dice, instead of removing it.

CSS:

button[type=roll].sheet-d6-dice::before {
    font-family: 'dicefontd6';
    content: 'F ';
}

HTML:

<button class="sheet-d6-dice" name="roll_dex" value="/roll @{dex}d6" type="roll"></button>

[edit] Button to blend in

The Stargate sheet is an example of a sheet that has turned the Attribute & Skill buttons to look like just text, setting the border and button background to transparent, and reducing it's padding.

[edit] Button with an image

The Ambition & Avarice sheet has two examples where the roll buttons have been changed from the default d20 icon, to make the d20 and d5 buttons look hand-drawn. For the image to stay in place when you hover over it with a mouse, you need to do some manual adjustments for :hover CSS class for the image position, that may vary depending on the size/shape of the image. Image use in character sheets contains more examples.

[edit] Button Dynamic Text

By placing an Attribute-Backed Span inside the button.

You then have an input elsewhere with the identical name that can then change the value of the attribute displayed on the button.

<button type="roll" value="/roll 3d6" name="roll_attack"><span name="attr_attackname"></span></button>
<input type="text" name="attr_attackname" value="Sword">

[edit] See Also