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 "Roll Templates"

From Roll20 Wiki

Jump to: navigation, search
m (Helper Functions)
m
(45 intermediate revisions by 12 users not shown)
Line 1: Line 1:
Roll Templates are a special facet of the Character Sheets system which provide additional layout and styling options for the display of roll results.
+
Roll Templates are a special facet of the [[Character Sheets]] system which provide additional layout and styling options for the display of roll results.
 
+
[[File:Roll template default example2.JPG|right|thumb|350px|The output of a '''default template''' used in {{Text Chat}}]]
 
==Using Roll Templates==
 
==Using Roll Templates==
  
Line 14: Line 14:
  
 
[[File:Roll template default example.JPG||right]]
 
[[File:Roll template default example.JPG||right]]
The &{template:<template_name>} is the part that tells the system to use a Roll Template, and specifies the name of the template you want to use. Then you just provide all the data for the template in the format {{<propertyname>= <value>}}. The "propertyname" that you should use depends on the template -- the Character Sheet documentation should let you know what's available, and we've provided documentation on all of the built-in templates below. "Value" can be either text or an inline roll, including macros, abilities, etc. Note that if you use a macro or ability, it must be an inline roll, not a "/roll" command.
+
The <code>&{template:<template_name>}</code> is the part that tells the system to use a Roll Template, and specifies the name of the template you want to use. Then you just provide all the data for the template in the format <code>{{<propertyname>= <value>}}</code>. The "propertyname" that you should use depends on the template -- the Character Sheet documentation should let you know what's available, and we've provided documentation on all of the built-in templates below. "Value" can be either text or an inline roll, including macros, abilities, etc. Note that if you use a macro or ability, it must be an inline roll, not a <code>/roll</code> command.
  
Here's an example that uses a "%{Character|attack}" ability:
+
{{orange| Macros for roll templates are sensitive to leading spaces, so '''<code><nowiki>{{name=Dexterity}}</nowiki></code>''' will work, but  '''<code><nowiki>{{ name=Dexterity}}</nowiki></code>''' won't. }}
 +
 
 +
Here's an example that uses a <code>%{Character|attack}</code> ability:
  
 
<pre style="overflow:hidden;white-space:pre-wrap">
 
<pre style="overflow:hidden;white-space:pre-wrap">
Line 24: Line 26:
 
====When Can I Use Roll Templates?====
 
====When Can I Use Roll Templates?====
  
You can use a Roll Template in general messages (without a command like "/desc" or "/emote") and whispers. You can't use roll templates with the "/roll" command; instead, Roll Templates are meant to be used with inline rolls. As long as they use inline rolls, you can use Roll Templates with macros, Character Abilities, and sheet authors can use them inside of their Roll Buttons on sheets.
+
You can use a Roll Template in general messages (without a command like <code>/desc</code> or <code>/emote</code>) and whispers. You can't use roll templates with the <code>/roll</code> command; instead, Roll Templates are meant to be used with inline rolls. As long as they use inline rolls, you can use Roll Templates with macros, Character Abilities, and sheet authors can use them inside of their Roll Buttons on sheets.
  
 
==Built-In Roll Templates==
 
==Built-In Roll Templates==
  
The following roll templates are built-in to Roll20 and can be used in any game.
+
The following roll templates are built-in to Roll20 and can be used in any game. You don't have to even have a character sheet template selected for your game to use it.
  
 
====Default====
 
====Default====
  
To use the default template, use "&{template:default}".
+
To use the default template, you first call <code>&{template:default}</code>, the (optionally) define what will be shown in the header in a <code><nowiki>{{name= }}</nowiki></code>-section, after which you can create any number of "rows" by creating more <code>{{ }}</code>-sections.
  
 
{| class="wikitable"
 
{| class="wikitable"
Line 38: Line 40:
 
! Property !! Expected Value
 
! Property !! Expected Value
 
|-
 
|-
| name || The name of the roll, shown in the header of the roll listing
+
| name || The name of the roll, shown in the header of the roll listing. (''If not used in a roll, the header will appear at the top of the roll template as a purple bar with no text.'')
 
|-
 
|-
 
|}
 
|}
  
'''The default template is special''', and will list out whatever argument you give it in a table. So for example, you could do the following:
+
'''The default template is special''', and will list out whatever argument you give it in a table. It will put in the middle of the purple header anything you define in the <code><nowiki>{{name= }}</nowiki></code> section, and then with every subsequent <code>{{ }}</code> segment, it will alternate with white & gray background.
 +
 
 +
If a <code>=</code> is used in the <code>{{ }}</code> rows, the roll template will align the <code>=</code> in the middle, and all rows will have the <code>=</code> in the same spot. If any row have lots of more text/content on either side of the <code>=</code>, it will be pressed to the side of the template for all rolls.
 +
 
 +
So for example, you could do the following:
  
 
<pre style="overflow:hidden;white-space:pre-wrap">
 
<pre style="overflow:hidden;white-space:pre-wrap">
Line 50: Line 56:
 
<br />
 
<br />
  
==Creating a Roll Template==
+
Notice that the content of the roll template is pressed to the left side, due the text segment on the '''Note'''-row. If that segment is removed, the content of the remaining rows will be closer to the center.
  
If you are a '''Sheet Author''', you can include as many roll templates as you want in your Character Sheet HTML and CSS. We'll let you know how below.
+
<big>[https://jsfiddle.net/8w3qm3zL/41/ Here] is a fairly exact example of the default template with it's dependent CSS classes.</big>
  
If you are a '''Pro''' subscriber, you can create your own Roll Templates if you are using the "Custom" character sheet option with your game. Follow the instructions below.
+
==Creating a Roll Template==
 +
''Main Page:'' '''[[Building Character Sheets/Roll_Templates]]'''
  
===Defining the Layout of the Roll Template===
+
You can create & use custom Roll Templates by [[Building Character Sheets|Editing/Building Character Sheets]], as they are a part of the Character Sheet's code.
  
The first step in creating a Roll Template is defining the layout, including what properties you are going to make available to be filled in by player. Roll Templates are just HTML, and you have access to all the same HTML as any other part of a Character Sheet (including <code>div</code> and <code>table</code>). Here's an example of the layout of a Roll Table:
+
The main page details what parts & features goes into creating a roll template, along with showing the code for a number of existing Roll Templates
<pre style="overflow:hidden;white-space:pre-wrap">
+
<rolltemplate class="sheet-rolltemplate-test">
+
    <table>
+
<tr><th>{{rollname}}</th></tr>
+
<tr><td><span class="tcat">Attack: </span>{{attack}} | {{attackadvantage}} vs AC</td></tr>
+
{{#damage}}
+
<tr>
+
<td><span class="tcat">Damage: </span>{{damage}} <span class="tcat">Crit: </span>{{dmgcrit}}</td>
+
</tr>
+
<tr>
+
<td><span class="tcat">Type: </span>{{dmgtype}}</td>
+
</tr>
+
{{/damage}}
+
<tr>
+
<td><span class="tcat">Effect: </span>{{atteffect}}</td>
+
</tr>
+
    </table>
+
</rolltemplate>
+
</pre>
+
  
Your template should have a <code>rolltemplate</code> tag with a class of "sheet-rolltemplate-<template_name>". "template_name" is the same name that will be used in the &{template:<template_name>} portion of the command, and should not contain spaces.  You can put the roll template anywhere you want in your Character Sheet's HTML, but we recommend putting it at the very end. It will automatically be "removed' from your template so it isn't shown as part of the sheet in the Character view. Note that you cannot nest rolltemplates inside of each other.
+
= See Also =
 +
* '''[[Complete Guide to Macros & Rolls‎]]'''
 +
** {{Text Chat}} - where the roll results appear, & info on the common chat commands
 +
** [[Dice Reference]] - Comprehensive list of how the Roll20 dice-rolling syntax works, and list the features available
 +
** [[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
 +
*** [[Reusing_Rolls#Rolltemplate_Helper_functions|Reusing Rolls in Roll Templates]]
 +
** [[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
 +
* [[BCS|Building Character Sheets]]
 +
** [[Building Character Sheets/Roll Templates|Creating Roll Templates]]
 +
** [[Sheet Author Tips]] More advanced tips for creating/maintaining sheets, workflow, & useful tools
 +
** [[Custom Sheet Sandbox|Sheet Sandbox]] – the better editor to use when you code your character sheets
 +
* [https://roll20.zendesk.com/hc/en-us/articles/360037257334-How-to-Make-Roll-Templates Roll20 Help Center version of this page] - Almost always outdated/lacking compared to any pages on sheet development on the wiki
 +
<br>
 +
<br>
  
After that, it's up to you to decide how to structure your roll. We recommend a table layout, but it's up to you.
 
 
Inside of the template, you have access to following:
 
 
====Properties====
 
 
You can include any property you'd like by using the double-curly-braces. So <code>{<nowiki />{myproperty}}</code> would output whatever (inline roll, text. etc.) is given to the template via <code>{{myproperty=<value>}}</code> in the roll. To create a new property, just add it to your template and give it a unique name. Again, avoid the use of spaces to ensure maximum compatibility with all helper functions.
 
 
====Logic====
 
 
If you do <code>{{#<property>}}</code> followed by <code>{<nowiki />{/<property>}}</code>, all of the parts between those two tags will only be shown if the property contains a value. This can be useful for providing several different parts to a template which may only be used some of the time. For example, the "Effect" part of a roll may only apply to spells, so if the roll doesn't provide an effect, that section will not be shown.
 
 
You can also do <code>{<nowiki />{^<property>}}</code> followed by <code>{<nowiki />{/<property>}}</code> to mean the opposite -- that is, only show the section if the given property does not exist. This logic also applies to the helper functions below. For example you could check if a roll was not a critical by using <code>{{#^rollWasCrit() <rollname>}}</code> and closed with <code>{{/^rollWasCrit() <rollname>}}</code>. Note that the helper functions require both the <code>#</code> and the <code>^</code> symbols to be interpreted correctly by the roll template.
 
 
<pre style="overflow:hidden;white-space:pre-wrap">
 
{{#^rollWasCrit() attackroll }}
 
    <span class='tcat'>Not a Crit!</span>
 
{{/^rollWasCrit() attackroll }}
 
</pre>
 
 
====Helper Functions====
 
 
There are several helper functions dealing with rolls provided as well. You use these just like the normal Logic pattern above, but you are calling a function and providing a property. The section contained between the tags will only be shown if the function evaluates to true.
 
 
{| class="wikitable"
 
|-
 
! Helper Function !! Shows Section If
 
|-
 
| <code>{{#rollWasCrit() <rollname>}}</code> || If the provided roll contains any crits, the section will be shown. For example, <code>{<nowiki />{#rollWasCrit() attack}}</code> would check the "attack" property for an inline roll that has at least one critical roll.
 
|-
 
| <code>{{#rollWasFumble() <rollname>}}</code> || Same as #rollWasCrit(), but checks for any fumbles (rolls of 1).
 
|-
 
| <code>{{#rollTotal() <rollname>}}</code> || Checks the total of an inline roll for the value. If they match, the section is shown. For example, <code>{<nowiki />{#rollTotal() attack 10}}</code> would check the "attack" property for an inline roll that totaled 10.
 
|-
 
| <code>{{#rollGreater() <rollname>}}</code> || Checks the total of an inline roll for the value. If the roll result is greater, the section is shown. For example, <code>{<nowiki />{#rollGreater() AC 16}}</code> would check the "AC" property for an inline roll that resulted in 17 or higher.
 
|-
 
| <code>{{#rollLess() <rollname>}}</code> || Checks the total of an inline roll for the value. If the roll result is less, the section is shown. For example, <code>{<nowiki />{#rollLess() deathsave 10}}</code> would check the "deathsave" property for an inline roll that resulted in 9 or less.
 
|-
 
| <code>{{#rollBetween() <rollname>}}</code> || Checks the total of an inline roll for the value. The rollBetween() function accepts two numbers. If the roll result is equal to or between, the section is shown. For example, <code>{<nowiki />{#rollBetween() strength 7 9}}</code> would check the "strength" property for an inline roll that resulted in a seven, eight, or nine.
 
|}
 
 
Note: All helper functions will only check the first inline roll found in a property.
 
 
'''Important:''' When you "close" the section of a helper function, you must put the entire function call including all arguments. For example, <code>{<nowiki />{#rollWasCrit() attack}}</code> would be closed by <code>{<nowiki />{/rollWasCrit() attack}}</code>.
 
 
Here's an example roll template that would only show its Critical Damage section if the Attack roll is a crit:
 
 
<pre style="overflow:hidden;white-space:pre-wrap">
 
    <table>
 
<tr><th>{{rollname}}</th></tr>
 
<tr><td><span class="tcat">Attack: </span>{{attack}}</td></tr>
 
<tr>
 
<td>
 
                              <span class="tcat">Damage: </span>{{damage}}
 
                              {{#rollWasCrit() attack}}
 
                              <span class="tcat">Crit: </span>{{dmgcrit}}
 
                              {{/rollWasCrit() attack}}
 
                        </td>
 
</tr>
 
  </table>
 
</pre>
 
 
====Helper Function Variables====
 
 
All of the helper functions that accept a number, such as rollTotal() or rollBetween(), can use the result of another inline roll in the same Roll Template in place of the number. For example <code>{<nowiki />{#rollGreater() save poison}}</code> would compare the result of the save inline roll and the poison inline roll and show the section if the save result was greater.
 
 
====Special Helper Function: allProps()====
 
 
There is a special helper function called allProps() that can be used to dynamically list all of the properties that were passed to a roll, even if you don't explicitly include them. You can also specify properties to ignore. For example, the following would show a table with a table row for each property included in the roll, except for the "attack" property:
 
 
<pre style="overflow:hidden;white-space:pre-wrap">
 
<table>
 
    <caption>{{name}}</caption>
 
    {{#allprops() attack}}
 
      <tr><td>{{key}}</td><td>{{value}}</td>
 
    {{/allprops() attack}}
 
</table>
 
</pre>
 
 
===Styling Roll Templates===
 
 
To style a Roll Template, just include CSS for it in the CSS for your Character Sheet. Here's a quick example that should give you a good idea of how to do it (in this example, the roll template's name is "customtest"):
 
 
<pre style="overflow:hidden;white-space:pre-wrap">
 
.sheet-rolltemplate-customtest table {
 
    width: 100%;
 
border: 1px solid;
 
color: black;
 
font-size: 1em;
 
font-family: "Helvetica Neue", Helvetica, sans-serif;
 
}
 
 
.sheet-rolltemplate-customtest th {
 
background-color: rgba(112, 32, 130,1);
 
color: #ffffff;
 
padding: 2px;
 
border-bottom: 1px solid black;
 
line-height: 1.6em;
 
font-size: 1.2em;
 
}
 
 
.sheet-rolltemplate-customtest .userscript-tcat {
 
font-weight: bold;
 
}
 
 
.sheet-rolltemplate-customtest td {
 
padding: 5px;
 
border-bottom: 1px solid black;
 
}
 
 
.sheet-rolltemplate-customtest tr:nth-child(odd) {
 
background-color: rgba(217, 217, 214,1);
 
}
 
 
.sheet-rolltemplate-customtest tr:nth-child(even) {
 
background-color: rgba(233, 233, 233,1);
 
}
 
 
.sheet-rolltemplate-customtest .inlinerollresult  {
 
display: inline-block;
 
min-width: 1.5em;
 
text-align: center;
 
border: 2px solid rgba(167, 168, 170,1); /*Cool Gray 6 C*/
 
}
 
 
.sheet-rolltemplate-customtest .inlinerollresult.fullcrit {
 
border: 2px solid #3FB315;
 
}
 
 
.sheet-rolltemplate-customtest .inlinerollresult.fullfail {
 
border: 2px solid #B31515;
 
}
 
 
.sheet-rolltemplate-customtest .inlinerollresult.importantroll {
 
border: 2px solid #4A57ED;
 
}
 
</pre>
 
 
Notice that all of the styles begin with ".sheet-rolltemplate-<templatename>". You can then style your own custom HTML (such as the tables, divs, and classes that you used). Note that any classes you include in your roll template layout (such as "tcat" in the above example) will have ".userscript-" added to the beginning of them for security reasons. The easiest thing to do is to create your layout, then perform a roll in-game and inpect the resulting HTML so you can make sure you are accounting for any security filtering that is taking place.
 
 
==Roll Template Examples==
 
Listed below are a handful of system specific examples of the Roll Template functionality.
 
 
===Dungeons and Dragons 5th Edition===
 
[[File:Rolltemplate 5e.png|right]]
 
Macro:
 
<pre style="overflow:hidden;white-space:pre-wrap">
 
&{template:5eAttack} {{name=@{meleeweaponname1}}} {{subtags=Main Hand, Finess, @{meleedmgtype1}}} {{attack=[[1d20+@{meleetohit1}]]}} {{attackadv=[[1d20+@{meleetohit1}]]}} {{damage=[[@{meleedmg1}+@{meleedmgbonus1}]]}} {{dmgcrit=[[@{meleedmg1}]]}}
 
</pre>
 
HTML:
 
<pre style="overflow:hidden;white-space:pre-wrap">
 
<rolltemplate class="sheet-rolltemplate-5eAttack">
 
    <table>
 
        <tr><th>{{name}}</th></tr>
 
        <tr><td class="subheader">{{subtags}}</td></tr>
 
        <tr class="arrow-container"><td><div class="arrow-right"></div></td></tr>
 
<tr class="rowcolor"><td><span class="tcat">Attack: </span>{{attack}} | {{attackadv}} vs AC</td></tr>
 
{{#damage}}
 
<tr>
 
        <td>
 
                    <span class="tcat">Damage: </span>{{damage}}
 
                    <span class="tcat">Crit: </span>{{dmgcrit}}
 
                </td>
 
    </tr>
 
{{/damage}}
 
        {{#snkattk}}
 
    <tr>
 
        <td>
 
                    <span class="tcat">Sneak Attack: </span>{{snkattk}}
 
                    <span class="tcat">Crit: </span>{{snkcrit}}
 
                </td>
 
    </tr>
 
{{/snkattk}}
 
    </table>
 
</rolltemplate>
 
</pre>
 
CSS:
 
<pre style="overflow:hidden;white-space:pre-wrap">
 
.sheet-rolltemplate-5eAttack table {
 
    width: 189px;
 
    padding: 2px;
 
border: 1px solid;
 
    background-color: #ffffff;
 
}
 
 
.sheet-rolltemplate-5eAttack th {
 
color: rgb(126, 45, 64);
 
    padding-left: 5px;
 
line-height: 1.6em;
 
font-size: 1.2em;
 
    text-align: left;
 
font-family: "Times New Roman", Times, serif;
 
    font-variant: small-caps;
 
}
 
 
.sheet-rolltemplate-5eAttack .sheet-subheader {
 
    color: #000;
 
    font-size: 1em;
 
    font-style: italic;
 
}
 
 
.sheet-rolltemplate-5eAttack .sheet-arrow-right {
 
    border-top: 3px solid transparent;
 
    border-bottom: 3px solid transparent;
 
border-left: 180px solid rgb(126, 45, 64);
 
}
 
 
.sheet-rolltemplate-5eAttack .sheet-tcat {
 
    font-style: italic;
 
}
 
 
.sheet-rolltemplate-5eAttack td {
 
    padding-left: 5px;
 
}
 
 
.sheet-rolltemplate-5eAttack .inlinerollresult  {
 
    background-color: #ffffff;
 
    border: none;
 
}
 
 
.sheet-rolltemplate-5eAttack .inlinerollresult.fullcrit {
 
color: #3FB315;
 
    border: none;
 
}
 
 
.sheet-rolltemplate-5eAttack .inlinerollresult.fullfail {
 
color: #B31515;
 
    border: none;
 
}
 
 
.sheet-rolltemplate-5eAttack .inlinerollresult.importantroll {
 
color: #4A57ED;
 
    border: none;
 
}
 
</pre>
 
 
===Dungeons and Dragons 3.5 / Pathfinder===
 
[[File:Rolltemplate pf.png|right]]
 
Macro:
 
<pre style="overflow:hidden;white-space:pre-wrap">
 
&{template:pf_spell} {{name=@{repeating_lvl-0-spells_0_name}}}{{school=@{repeating_lvl-0-spells_0_school}}} {{level=sorcerer/wizard 0}} {{casting_time=@{repeating_lvl-0-spells_0_cast-time}}} {{components=@{repeating_lvl-0-spells_0_components}}} {{range=@{repeating_lvl-0-spells_0_range}}} {{target=@{repeating_lvl-0-spells_0_targets}}} {{duration=@{repeating_lvl-0-spells_0_duration}}} {{saving_throw=@{repeating_lvl-0-spells_0_save}}} {{sr=@{repeating_lvl-0-spells_0_sr}}} {{rng_attack=[[1d20 + @{attk-ranged}]]}} {{damage=1d3([[1d3]])}} {{spell_description=@{repeating_lvl-0-spells_0_description}}}
 
</pre>
 
HTML:
 
<pre style="overflow:hidden;white-space:pre-wrap">
 
<rolltemplate class="sheet-rolltemplate-pf_spell">
 
    <table>
 
        <tr><th>{{name}}</th></tr>
 
        <tr>
 
            <td><span class="tcat">School </span>{{school}}; <span class="tcat">Level </span>{{level}}</td>       
 
        </tr>
 
        <tr>
 
            <td><span class="tcat">Casting Time </span>{{casting_time}}</td>       
 
        </tr>
 
        <tr>
 
            <td><span class="tcat">Components </span>{{components}}</td>       
 
        </tr>
 
        <tr>
 
            <td><span class="tcat">Range </span>{{range}}</td>       
 
        </tr>
 
        <tr>
 
            <td><span class="tcat">Effect/Target </span>{{target}}</td>       
 
        </tr>
 
        <tr>
 
            <td><span class="tcat">Duration </span>{{duration}}</td>       
 
        </tr>
 
        <tr>
 
            <td><span class="tcat">Saving Throw </span>{{saving_throw}}; <span class="tcat">Spell Resistance </span>{{sr}}</td>       
 
        </tr>
 
        {{#rng_attack}}
 
            <tr><td><span class="tcat">Ranged Attack </span>{{rng_attack}}</td></tr>
 
        {{/rng_attack}}
 
        {{#mel_attack}}
 
            <tr><td><span class="tcat">Melee Attack </span>{{mel_attack}}</td></tr>
 
        {{/mel_attack}}
 
{{#damage}}
 
<tr><td><span class="tcat">Damage: </span>{{damage}}</td></tr>
 
{{/damage}}
 
        <tr>
 
            <td>{{spell_description}}</td>       
 
        </tr>
 
    </table>
 
</rolltemplate>
 
</pre>
 
CSS:
 
<pre style="overflow:hidden;white-space:pre-wrap">
 
.sheet-rolltemplate-pf_spell table {
 
    width: 100%;
 
    padding: 2px;
 
    background:url(http://i.imgur.com/BLb0XMU.jpg) top left repeat;
 
}
 
 
.sheet-rolltemplate-pf_spell th {
 
color: rgb(233, 223, 151);
 
    background-color: rgb(63, 32, 33);
 
    padding-left: 5px;
 
line-height: 1.1em;
 
font-size: 1em;
 
    text-align: left;
 
font-family: "Arial", Helvetica, sans-serif;
 
    text-transform: uppercase;
 
}
 
 
.sheet-rolltemplate-pf_spell .sheet-arrow-right {
 
    border-top: 3px solid transparent;
 
    border-bottom: 3px solid transparent;
 
border-left: 180px solid rgb(126, 45, 64);
 
}
 
 
.sheet-rolltemplate-pf_spell .sheet-tcat {
 
    font-weight: bold;
 
}
 
 
.sheet-rolltemplate-pf_spell td {
 
    padding-left: 5px;
 
    font-size: 0.9em;
 
}
 
 
.sheet-rolltemplate-pf_spell .inlinerollresult  {
 
    background-color: transparent;
 
    border: none;
 
}
 
 
.sheet-rolltemplate-pf_spell .inlinerollresult.fullcrit {
 
color: #3FB315;
 
    border: none;
 
}
 
 
.sheet-rolltemplate-pf_spell .inlinerollresult.fullfail {
 
color: #B31515;
 
    border: none;
 
}
 
 
.sheet-rolltemplate-pf_spell .inlinerollresult.importantroll {
 
color: #4A57ED;
 
    border: none;
 
}
 
</pre>
 
 
===World of Darkness===
 
[[File:Rolltemplate wod.png|right]]
 
Macro:
 
<pre style="overflow:hidden;white-space:pre-wrap">
 
&{template:wod} {{name=@{character_name}}} {{roll_name=Command}} {{attr=Intelligence}} {{attr_num=@{intelligence}}} {{skill=Intimidation}} {{skill_num=@{intimidation}}} {{pwr=Dominate}} {{pwr_num=@{dominate}}} {{mod_num=?{Modifiers|0}}} {{result=[[{(@{intelligence}+@{intimidation}+@{dominate}+?{Modifiers|0})d10!}>8]]}}
 
</pre>
 
HTML:
 
<pre style="overflow:hidden;white-space:pre-wrap">
 
<rolltemplate class="sheet-rolltemplate-wod">
 
    <table>
 
        <tr><th>{{name}} rolls{{#roll_name}} {{roll_name}}{{/roll_name}}</th></tr>
 
        <tr><td class="attr">
 
            {{#attr}}
 
                {{attr}}({{attr_num}})
 
            {{/attr}}
 
            {{#skill}}
 
                + {{skill}}({{skill_num}})
 
            {{/skill}}
 
    {{#pwr}}
 
    + {{pwr}}({{pwr_num}})
 
    {{/pwr}}
 
            {{#mod_num}}
 
                + Modifiers({{mod_num}})
 
            {{/mod_num}}
 
        </td></tr>
 
        <tr>
 
            <td class="result">{{result}} Successes</td>       
 
        </tr>
 
    </table>
 
</rolltemplate>
 
</pre>
 
CSS:
 
<pre style="overflow:hidden;white-space:pre-wrap">
 
.sheet-rolltemplate-wod table {
 
    width: 189px;
 
    height: 189px;
 
    padding: 2px;
 
    background: url(http://i.imgur.com/xBk4U1p.jpg) top left;
 
    background-size: 189px 189px;
 
    background-repeat: no-repeat;
 
    font-family: "Courier New", Courier, monospace;
 
    font-weight: bold;
 
    border-spacing: 0;
 
}
 
 
.sheet-rolltemplate-wod th {
 
color: rgb(112, 0, 0);
 
    padding: 15px 2px 2px 20px;
 
line-height: 1.2em;
 
font-size: 1.2em;
 
    text-align: left;
 
}
 
 
 
.sheet-rolltemplate-wod td {
 
    padding-left: 20px;
 
    font-size: 1.0em;
 
    vertical-align: top;
 
}
 
 
.sheet-rolltemplate-wod .sheet-result {
 
    font-size: 1.2em;
 
    text-align: center;
 
    color: rgb(112, 0, 0);
 
    padding-bottom: 20px;
 
}
 
 
.sheet-rolltemplate-wod .inlinerollresult  {
 
    background-color: transparent;
 
    color: #000000;
 
    border: none;
 
}
 
 
.sheet-rolltemplate-wod .inlinerollresult.fullcrit {
 
color: #3FB315;
 
    border: none;
 
}
 
 
.sheet-rolltemplate-wod .inlinerollresult.fullfail {
 
    color: #000000;
 
    border: none;
 
}
 
 
.sheet-rolltemplate-wod .inlinerollresult.importantroll {
 
color: #3FB315;
 
    border: none;
 
}
 
</pre>
 
 
[[Category:Docs]]
 
[[Category:Docs]]
 +
[[Category:Macros]]

Revision as of 12:59, 7 January 2021

Roll Templates are a special facet of the Character Sheets system which provide additional layout and styling options for the display of roll results.

The output of a default template used in q Text Chat

Contents

Using Roll Templates

If you're using a Character Sheet, there's a really good chance you'll use a Roll Template just by clicking the roll button on the sheet, or by calling a sheet roll in a macro or ability. You don't have to do anything extra to do this, it's already set up for you in advance by the sheet author.

If you're interested in using Roll Templates in your own custom macros or creating your own custom templates, read on further.

Using a roll template is very easy. Just include a special flag in your chat message which tells Roll20 that you want to use a Roll Template, and then provide all of the data that you want to include. Here's an example that uses the "default" template (which all games have access to, regardless of the game system or character sheet you are using):

&{template:default} {{name=Test Attack}} {{attack=[[1d20]]}} {{damage=[[2d6]]}}
Roll template default example.JPG

The &{template:<template_name>} is the part that tells the system to use a Roll Template, and specifies the name of the template you want to use. Then you just provide all the data for the template in the format {{<propertyname>= <value>}}. The "propertyname" that you should use depends on the template -- the Character Sheet documentation should let you know what's available, and we've provided documentation on all of the built-in templates below. "Value" can be either text or an inline roll, including macros, abilities, etc. Note that if you use a macro or ability, it must be an inline roll, not a /roll command.


Here's an example that uses a %{Character|attack} ability:

&{template:default} {{name=Test With Ability}} {{attack= %{Character_Name|attack} }} {{damage= #damagemacro }}

When Can I Use Roll Templates?

You can use a Roll Template in general messages (without a command like /desc or /emote) and whispers. You can't use roll templates with the /roll command; instead, Roll Templates are meant to be used with inline rolls. As long as they use inline rolls, you can use Roll Templates with macros, Character Abilities, and sheet authors can use them inside of their Roll Buttons on sheets.

Built-In Roll Templates

The following roll templates are built-in to Roll20 and can be used in any game. You don't have to even have a character sheet template selected for your game to use it.

Default

To use the default template, you first call &{template:default}, the (optionally) define what will be shown in the header in a {{name= }}-section, after which you can create any number of "rows" by creating more {{ }}-sections.

Property Expected Value
name The name of the roll, shown in the header of the roll listing. (If not used in a roll, the header will appear at the top of the roll template as a purple bar with no text.)

The default template is special, and will list out whatever argument you give it in a table. It will put in the middle of the purple header anything you define in the {{name= }} section, and then with every subsequent {{ }} segment, it will alternate with white & gray background.

If a = is used in the {{ }} rows, the roll template will align the = in the middle, and all rows will have the = in the same spot. If any row have lots of more text/content on either side of the =, it will be pressed to the side of the template for all rolls.

So for example, you could do the following:

&{template:default} {{name=Test Attack}} {{attack=[[1d20]]}} {{note= This is some note content}} {{Saving Throw= vs Will}}

Roll template default example2.JPG

Notice that the content of the roll template is pressed to the left side, due the text segment on the Note-row. If that segment is removed, the content of the remaining rows will be closer to the center.

Here is a fairly exact example of the default template with it's dependent CSS classes.

Creating a Roll Template

Main Page: Building Character Sheets/Roll_Templates

You can create & use custom Roll Templates by Editing/Building Character Sheets, as they are a part of the Character Sheet's code.

The main page details what parts & features goes into creating a roll template, along with showing the code for a number of existing Roll Templates

See Also