Revision as of 17:57, 6 January 2023

Page Updated:   2023-01-06

This is related to Editing(coding) Character Sheets, which require Pro info to be able to use. Main Page: Building Character Sheets

Main Page: Building Character Sheets

HTML is used to define the Character Sheet, and Roll20 have a couple of differences in how this work from baseline HTML, which are described in this section. You can use most of the basic HTML elements, such as p, div, span, textarea, input, select, img as normal, while some, such as <button> works noticeably differently.

Note: You cannot use JavaScript on your sheet outside of sheetworkers, and their <script type="text/worker">-element.

See Building Character Sheets#Restrictions for how Roll20 differs in how HTML can be used.

Storing User Data

Most HTML-elements used for storing user input can be used in Roll20 sheet, with an notable distinction. For each element, you must include a name-attribute which begins with attr_. This defines the unique attribute-name for the element, and tells that it's an attribute that should be saved to the character. This must also be done for values & attributes that the user can't edit, for that data to be usable in calculations or similar. All these attributes( except from repeating sections) will show up in the Attributes & Abilities-tab on the character sheet, after having been edited for the first time.

Text & Numbers

To create a field for saving text or numbers entered by the user, the following elements can be used:

• <input type="text"> MDN documentation
• <input type="number"> MDN documentation
• <textarea> MDN documentation

Note: <input>-elements must have a specified type, and the input types that work on Roll20 are: (text, number, hidden, checkbox, radio and range).

Example:

<input type="text" name="attr_class" value="fighter" >   // leave as value="" if you don't want the user to need to delete the default value
<input type="number" name="attr_healthpoints" value="10" >
<input type="number" name="attr_healthpoints_max" value="10" >
<textarea name="attr_notes" value=""></textarea>
<input type="range" name="attr_hp" min="0" max="10" value="10">  // max value can't be edited by user

If you want the field to utilize the max of an attribute instead of the normal value, you can append _max to the name of the field, e.g. <input type="number" name="attr_healthpoints_max" /> represents the max value for <input type="number" name="attr_healthpoints" value="10" >.

You can also use a <span>-element to display a read-only attribute on your sheet, e.g. < span name="attr_strength_mod"></ span>.

It is possible to use a <span>-element to show the same value as an exiting attribute <input>-element with the same name. Updating the value in the <input>-element will update the displayed value of the <span>-element. (For a <span>-attribute to show properly, it needs to be saved on the sheet in some form, either with a normal input or a <input type="hidden">

Default Values

You can optionally include a value-attribute on any input text/number element, which will define the default value for the field.

For example, the following would define an "AC" field with a default value of "0". If no default value is specified, it is an empty string ("").

<input type="number" name="attr_AC" value="0" />

type="text"

For storing text on the sheet. Also good for any input that is used for a mix of numbers and characters.

• <input type="text"> MDN Web Docs

<input type="text" name="attr_class" value="fighter" > 

Character Name

When making an <input type="text"> for the character name, it's adviced to use attr_character_name as it's name attribute, as this will automatically link/update with the name displayed on the N Journal's character name.

<input type="text" name="attr_character_name" />

type="number"

By default, small up/down arrows are displayed at the end of the field when it's selected, that can be used to increase/decrease it's value by increments of 1. By default the number field prefers whole integers, and on hover might complain if there is decimal numbers there. By default, there appears up-down arrows on the input when it's selected.

To allow decimals in the field, add step="any" to the input.

• step: defines in what increments the input is increase/decrease, and what numbers it allows. When not defined, it's default is "1". Ex. step="0.2"more info
• min, max: can be used to define the minimum and maximum values allowed in the field. Ex. min="0" max="10" more info

<input type="number" name="attr_hp" step="any" value="10" min="0" max="20" />

Auto-Calculating Values

Main Page: Auto-Calc

!!!WARNING!!! This feature is HIGHLY discouraged in modern sheets as it is not compatible with sheetworkers. If you add a sheetworker to your sheet, you will most likely wind up needing to change all of your auto-calcs to sheetworker calculated attributes.

You can include a formula in the default value for the field, and specify either disabled="true" for the input. If you do so, the sheet will display the result of the formula instead of the formula itself.

For example, this would create a StrMod-attribute, which shows half the Strength value.

<input type="number" name="attr_StrMod" value="(@{Strength}/2)" disabled="true" />

Auto-Calc a more simple method than using sheetworkers, but have several drawbacks. Most sheet authors recommend against using auto-calc in anything but the most simple sheets, and instead use sheetworkers.

These auto-calculating attributes can be used in Sheet Rolls, Macros, and Abilities as normal.

type="hidden"

Using <input type="hidden"> can be useful to save hidden variables on the character sheet, that the user doesn't need to see. It will save the value of the input, but won't be shown on the character sheet in any way, making it easier to user than having to hide the input with CSS.

Example:

<input type="hidden" value="10" name="attr_str_mod" value="0" />

Usercases for type="hidden":

• Sheetworkers make good use of them to calculate & save various info and secondary stats sheet users don't need to see
• storing the value of an read-only attribute displayed with a <span>
• Advanced Character Sheet Translation options
• A number of CSS Wizardry examples

type="range"

input range -MDN docs – Style Input range

<input type="range"> can be used for displaying a progress bar, but doesn't work for it's intended. See Custom Progress Bar for examples.

Dragging the range's "thumb" to other values doesn't update the actual value saved on the char sheet, so it only works as a display.

Example:

<input type="range" name="attr_hp" min="0" max="10" value="10">
<input type="number" name="attr_hp">
<span name="attr_hp"></span>

Dropdown menu

The <select>-element can be used to save info a pre-determined list of options the user can access from a dropdown menu, which are split into separate <option>-elements. The multiple-tag for <select> doesn't seem to work in Roll20.^{forum post(Forum)}

• <select> on MDN
• <option> on MDN
• <optgroup> on MDN

Example:

<select name="attr_woundlevel">
  <option value="0" selected="selected">Healthy</option>
  <option value="1">Stunned</option>
  <option value="1">Wounded</option>
  <option value="2">Wounded Twice</option>
  <option value="5">Incapacitated</option>
  <option value="10">Mortally Wounded</option>
</select>

To choose which option is selected by default, include the selected="selected" like in the example.

Optgroup

It seems optgroups are currently stripped from sheets since May 2021, see discussion(Forum)+BCS/Bugs. workaround: CSS_Wizardry#Optgroup

You can use <optgroup> to group selections in your <select>-element. Example of optgroup - Free Spacer sheet

<select name="attr_selectedsheet">
  <optgroup label="Player">
    <option value="1" selected>PC</option>
    <option value="2">Ship</option>
  </optgroup>
  <optgroup label="Gamemaster">
    <option value="3">NPC</option>
    <option value="4">Monster</option>
  </optgroup>
</select>

Checkboxes and Radio Buttons

For checkboxes and radio buttons, you must always specify a value-attribute.

For checkboxes, if the box is checked the attribute will be set to the value of the checkbox. The value can be anything, and doesn't have to be defined as "1" or "yes". If it is not checked, the value for that attribute is "0".

If you would like a checkbox to be checked by default, or choose what radio button is selected as default, add the checked-attribute to the input(checked="true" also works).

• <input type="checkbox"> on MDN
• <input type="radio"> on MDN

Example:

<input type="checkbox" name="attr_HasShield" value="1" checked >

For radio inputs, if one of them is selected, the attribute will be set to the value of that radio input. If no radio input is selected, the value will be an empty string. It's recommended that of the radio inputs should have the checked attribute to set a default value. Radio inputs are the only type of field where it is meant to have more then one field with the same name-attribute, as they are meant to be linked.

Example:

<input type="radio" value="10" name="attr_Multiplier" >
<input type="radio" value="25" name="attr_Multiplier" checked>

See also the CSS Wizardry page for some clever uses for checkboxes and radio inputs, or how to change their looks.

Static Info

General text, such as names & labels for different fields & other info can be displayed with mostly any of the common HTML tags. The default looks of most tags varies a bit, but can be be changed with CSS when wanted.

Example:

<h2>Stats</h2>
<span>Character Name:</span>
<input type="text" name="attr_character_name" />

• <h1> - <h5>: Good for section titles
• <span>, <p>: Good for a block of text, doesn't have much formatting
• <label>: Good for labelling input fields. Is by default bold font and leaves extra space under itself
• <div>: Generally best tag for structuring the sheet. Contains no styling, can be used for text.

Sheet Rolls and Roll Buttons

Main Article: Button

You can include pre-defined rolls on your sheet. This is a great way to add the rolls that will be needed by the player when using the standard rolls in the game system.

For example, you may want to add a "Roll Check" button next to each skill on the sheet. To define a roll button, use the <button> tag. The type-attribute is set to "roll". The roll itself is defined in the value-attribute. You can also add a name attribute which allows the roll to be referenced in external Macros, Abilities or the Chat. The name needs to have the roll_-prefix to work.

Example of a "Bluff check" roll button:

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

Referencing attributes/fields on the sheet is done with the @{AttributeName} syntax. You could also then roll that example in other Macros or Abilities using %{BoB|BluffCheck}.

Note: The names you give your roll buttons must be unique from any Ability or other roll button on your characters, if you want to reference them in Abilities or Macros. If a character sheet have several roll buttons with identical names but different values, calling the roll button name will prompt the last entry in the sheet's HTML.

See also:

• Complete Guide to Macros & Rolls - Definitive guide for constructing any kind of macros, for general use, or for roll buttons
  • Initiative Roll
  • Roll Queries - How to use Roll Queries in your buttons
  • Dice Reference - The Roll20 dice/math syntax
  • Select Attributes for Sheet Roll - An advanced technique for a dynamic roll button

Repeating Sections

Main Page: BCS/Repeating Sections

Sometimes you may have a type of object where there may be one or more of them, and it's not known ahead of time how many there are. A good example of this is the Skills listing for a Character in Official Savage Worlds. Roll20's sheets allow you to define a template for each item in the section, and the player can then add as many of these in the listing as they need.
Example:

<h3>Skills</h3>
<fieldset class="repeating_skills">
  <button type="roll" "name="roll_skill" value="/em uses @{skillname}, and rolls [[@{dtype}]]"></button>
  <input type="text" name="attr_skillname" value="">
  <select name="attr_dtype" class="dtype"> 
    <option value="d4">d4</option>
    <option value="d6">d6</option>
    <option value="d8">d8</option>
    <option value="d10">d10</option>
    <option value="d12">d12</option>
  </select>
</fieldset>

A more detailed explanation of repeating sections including styling, naming restrictions, sheetworkers counting rows and filtering can be found on Styling Repeating Sections.

In many cases, things inside a Repeating Section behaves differently than if you'd create the same thing in a normal part of the sheet, so adjustments to CSS & sheetworkers is very likely needed to get the same behaviour.

The naming restrictions will be of particular interest as uppercase characters can cause issues with draggable buttons.

Layout

Main Article: Designing Character Sheet Layout

Many sheet authors recommend using your own CSS for styling and to layout the sheet using CSS Flexbox and/or CSS Grid instead of the built-in column/rows option, or HTML tables.

Roll20 don't accept new sheet submissions that rely on HTML tables for design(Minimum Requirements -Sheet Code), so you shouldn't be using <table> if you want your sheet published in the dropdown. There are old sheets in the repo using them, but they where created before this rule against <table> was made.

Roll20 provides a few basic classes you can use to organize things into a simple column-based layout. To use them, just create a div with a class of 3colrow, 2colrow, or row. Then inside of that div, create a div for each column with a class of col. For example, to create a 3-column layout, you would could:

<div class='3colrow'>
  <div class='col'>
    <!-- Put the content for the first column here -->
  </div>
  <div class='col'>
    <!-- Second column -->
  </div>
  <div class='col'>
    <!-- Third column -->
  </div>
</div>

Images

Main Page: Image use in character sheets

You can have static images on your character sheet, such as placing the logo for the game at the top or having an image in the background to make the sheet look nicer overall. To show an image on a character sheet, you need to refer to the exact URL of where it's located on the internet.

If you're creating a character sheet that will be added to Roll20 for everybody's use, it's highly recommended to upload the images to GitHub along with the sheet code, so the image is secure and doesn't risk disappearing like is possible with free image hosting sources or directly linking to some website.

New Oct. 2021: You can now also show a character's Avatar & Token on the sheet.

• Details: Sheet Images - Avatar & Token

Logo Example:

<img src="https://raw.githubusercontent.com/Roll20/roll20-character-sheets/master/kitchensink/logo.png" />

img {
  max-height: 100px;
}

In Roll20's kitchensink character sheet template, the image source is directly linked to the version existing in Roll20's Github and works because the image exists in that exact place. The image's size is defined in the .css-file to be max 100px height, otherwise it would have retained it's original size.

Background Example:

.charsheet {
  background-image: url(https://cdn.pixabay.com/photo/2015/09/29/15/12/stars-964022_960_720.png); /*black space with tiny white stars*/
  background-color: black;
  background-repeat: repeat;
  color: white;
}

The Star Wars D6-character sheet displays in the background an black image with tiny white stars. By defining background-repeat: repeat;, the image repeats as a pattern in the background if it doesn't cover the entire character sheet. The background-color: black; is a backup in case the image stops working, keeping the sheet background almost identical without causing readability issues. color: white; sets the default text color of the sheet as white, which is much more readable against the black background.

See Also

• Sheet Examples
• Building Character Sheets#Restrictions
• Character Sheet Development/CSS
  • Designing Character Sheet Layout
  • Image use in character sheets
• Sheet Author Tips
• Character Sheet Repository‎