You can learn about most HTML Elements in other tutorial sites, but Roll Buttons are special to Roll20. Roll Buttons are used to print text to chat, and that text can include rolls.
There is another button type, action buttons, but we won’t be talking about them here – they’ll be dealt with under Sheet Workers.
A Roll Button is a way to create an Ability on the sheet – a special kind of Macro that uses that sheet’s stats. Players can trigger that Ability by clicking a button and can drag the Ability to their Macro Quick Bar for quick access.
Roll Buttons can include anything that is valid in a macro.
Creating a Roll Button
Roll buttons are created just like any other HTML Element:
<button type="roll" name="roll_attack" value="/roll 1d20+6"></button>Code language: HTML, XML (xml)By default, they look like a die, as in the picture. You can put text or other elements before or after them. Here are some examples of making buttons.
Attack <button type="roll" name="roll_attack" value="/roll 1d20+6"></button>
<br>
<span>Attack</span>
<button type="roll" name="roll_attack" value="/roll 1d20+6"></button>
<br>
<p>
<span>Attack</span>
<button type="roll" name="roll_attack" value="/roll 1d20+6"></button>
</p>Code language: HTML, XML (xml)Notice that they are inline elements like spans – that means they don’t cause a line break. So in this simple example, I had to use <br> elements to create line breaks.
Buttons as Containers
Since Button Elements have the closing tag (</button>) they can be used as containers. Any text inside the button will appear on the button itself.
<button type="roll" name="roll_attack" value="/roll 1d20+6">Attack</button>
<button type="roll" name="roll_save" value="/roll 1d20+6">Save</button>Code language: HTML, XML (xml)The button image can be removed, and the text and button can be restyled, but you’ll have to wait for CSS to see how to do that.
The Most Common Mistake
Actually two mistakes. You must always include the type and the “roll_” part of the button name. The button might appear to work if one or both of those is omitted, but the button will not work properly as a button. The player won’t be able to drag the button to their macro button, and the button can’t be used in macros. So don’t forget these parts.
Buttons as Macros
As already noted, you can include anything in a Button value that you can use in a macro. There’s a page on the wiki covering them, and I’ll probably create a page or two on them later. For now, here’s a simple example using an attack_bonus attribute.
<button type="roll" name="roll_attack" value="/roll 1d20+@{attack_bonus}">Attack</button>Code language: HTML, XML (xml)Buttons Refer to Their Owner
Button values always use the attributes from the same character sheet. So you don’t need to include the character name, selected, or target. You can use selected or target to affect other characters, as normal.
Line Breaks
There are two ways to create linebreaks in button values. You can manually enter a line break, or you can use \n. Here are buttons that use both:
<button type="roll" name="roll_text" value="This is some text
This is the second line of text
This is the third line of text">Text</button>
<button type="roll" name="roll_text" value="This is some text\nThis is the second line of text\nThis is the third line of text">
Text</button>Code language: HTML, XML (xml)The second one is a lot harder to read!
Spaces at the Start of Lines
Be aware that tabs or spaces at the start of a line are ignored, so if you do this:
<button type="roll" name="roll_text" value="This is some text
This is the second line of text
This is the third line of text">Text</button>Code language: HTML, XML (xml)You will get exactly the same output as either of the previous buttons.
You can also do this:
<button type="roll" name="roll_text" value="
This is some text
This is the second line of text
This is the third line of text">Text</button>Code language: HTML, XML (xml)That first line will be ignored – it’s just not printed. So if you have long button values, you can enter a line break to make the code more readable.
However, the / is a special character in Roll20 macros. If there’s one right at the start of a line, Roll20 might do something special. /roll is the most common and familiar example. If you have spaces at the start of lines before a /roll, that will be printed out as text, like this:
<button type="roll" name="roll_text" value="
Here is a roll
/roll 1d20
Oh dear, that wasn't a roll after all.">Text</button>Code language: HTML, XML (xml)
Roll20 will ignore the spaces on printout, but they still stop / commands from working!
Quotations
Button values have to be inside quotes, so if you want to print quotes out, you have to use the other kind of quotes. For example.
<button type="roll" name="roll_quote" value="
I say, 'Careful there, good chap!'">Text</button>
<button type="roll" name="roll_quote" value='
I say, "Careful there, good chap!"'>Text</button>Code language: HTML, XML (xml)If you use the same type of quote inside the value, everything after that quote will be ignored. So don’t do this:
<button type="roll" name="roll_quote" value="
I say, "Careful there, good chap!"">Text</button>Code language: HTML, XML (xml)Special Uses
Macro Bar
As noted earlier, you can drag a properly formed button to the Macro Quick Bar. If you don’t know about that, you really should. It’s a great tool for speeding up play.
Token Action
Token Actions are great. You can set a button as a token action, by adding class=”tokenaction” like so:
<button type="roll" name="roll_neverdothis" class="tokenaction"
value="I mean it, never do this!">Oh no!</button>Code language: HTML, XML (xml)Never do this!
The problem with this – if you add this in the character sheet code, players can never switch it off. That token action always appears. Players like to have control over which token actions appear, and for macros and abilities they can enable or disable them at will. Buttons in character sheets are always there.
I have never seen a character sheet which uses this feature, and that’s because it would be really unpopular.
Roll20 Wiki Page
Since Buttons are unique to Roll20, here’s the official wiki page: Roll Button
