Roll20 Wiki

Storing User Data

Character Sheet Development
Getting Started

General

Reference

Tools & Tips

Git/GitHub

Other

Most HTML-elements used for storing user input can be used in Roll20 sheet, but there is one notable difference how it's handled. 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 advised to set the name-attribute to be attr_character_name, as this will automatically link/update with the name displayed on the N Journal's character name. It's one of the pseudo-attributes.

<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

You can include a formula in the default value for the field, and specify either disabled="true" or readonly 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 in stead 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)

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

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).

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>

Related Pages

CSS Wizardry-page some clever uses for checkboxes and radio inputs, or how to change their looks.
Character Sheet Enhancement how to use datalists, and other new things with CSE-sheets
Sheetworkers How more complicated manipulation & calculation of attributes is handled
- Auto-Calc older and simpler method for calculating secondary attributes. Recommendation: avoid using if possible