Character Sheet Development/Restrictions
From Roll20 Wiki
Page Updated: 2023-11-19 |
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
Restrictions in Roll20's Character Sheet Development-framework. Checking Character Sheet Development/Bugs & Quirks is also recommended.
Character Sheet Development
Getting Started
- Using Custom Sheets
- Building Sheets
(Main Page) - Glossary
- Code Restrictions
- Best Practice
- Common Mistakes
- Tutorials
- Examples, Templates
- Pattern Libraries
- HTML & storing data
- CSS & Styling
General
- Updates & Changelog
- Known Bugs
- Character Sheet Enhancement(CSE)
- Custom Roll Parsing
- Legacy Sheet(LCS)
- (upcoming) Beacon SDK
Reference
- Buttons
- Repeating Sections
- Sheetworkers
- Roll Templates
- sheet.json
- Translation
- Auto-Calc
- Advanced
- All SheetDev Pages
Tools & Tips
Other
Generally speaking, character sheets are created with HTML, CSS, and JavaScript (for Sheetworkers), but there exist some constraints & security filtering that restricts what can be used, and where, in character sheet code.
Contents |
HTML & CSS
Security Filtering
- Using the word
eval
anywhere in the sheet code will stop everything from working. Roll20 have put this as a security measure to prevent eval from used even in a roundabout way. You cant have attribute or class names that includes it.- Known list of forbidden words:
data:
,eval
,cookie
,window
,parent
,this
,behaviour
,behavior
,expression
,moz-binding
- this also prevent you from importing fonts that contain
eval
as part of the name, like "MedievalSharp"
- Known list of forbidden words:
- All images will be passed through the Roll20 image proxy to prevent security attacks. This should be largely transparent to you and shouldn't affect anything, but it's something to be aware of. Images in Sheets
CSE
Character Sheet Enhancement is the new sheet code style that was released in March 2021. It has expanded features, is closer to baseline HTML/CSS, and is generally less restrictive compared to Legacy Sheets.
HTML:
In the Roll20, the character sheet code is basically wrapped inside a giant <form>
tag(so don't use it).
- Most DOM functionalities can't be used.
- Do not use Root HTML elements such as
<html>
<head>
,<title>
, or<body>
in your HTML. Doing so will prevent your character sheet from loading in the virtual tabletop.- HTML Elements that don't work:
<meter>
,<progress>
,link
,video
,iframe
,meta
,input type="color"
. Trying to add any of these to a sheet will either result in Roll20 removing them or behave like they are a<div>
. - Restricted attributes examples:
autoplay
,download
,onclick
- HTML Elements that don't work:
- Elements that now work:
<datalist>
,<details>
,<summary>
,<a href>
,main
,section
- Enable use of #id in HTML elements, &
<a href=#>
- Attribute names are case-insensitive when checked for uniqueness. All
<input>
,<select>
,<textarea>
etc. should have unique attribute names if intended to be independent. Two inputs with same attr name will mirror each other and update if the other one is changed. - To create a section where you can dynamically add new entries, the Repeating Sections method is used through the
<fieldset>
-element. -
<input>
and<button>
elements are restricted to a limited number of types. This is likely true with other elements. - All images will be passed through the Roll20 image proxy to prevent security attacks. This should be largely transparent to you and shouldn't affect anything, but it's something to be aware of. Images in Sheets
-
<svg>
-element aren't supported directly, but they can be used if saved as separate.svg
files: Example - All attributes in Roll Templates need to be written with double quotes, as single quotes results in roll template code being completely ignored.
- classes called in Roll Templates must use the
sheet-classname
format, like is used with Legacy Sheet
- classes called in Roll Templates must use the
- If using the roll20-made rows & columns, need to prefix
sheet-
to their use in the HTML(likely in the CSS also). - You cannot refer to external CSS stylesheets. Everything needs to be in the CSS file.
CSS:
- Certain(?) Media queries can now be used
- Do not use
.sheet-new-window
as a CSS class name, as Roll20 already uses it and will block you from trying to override it. Forum thread - Roll20 have some predefined CSS classes for its custom row/column system and other default, so very generic class names like:
.sheet-row
,.sheet-col
,.sheet-3colrow
,.sheet-2colrow
. -
.sheet-character
is best to be avoided when naming your own CSS classes. If you use the predefined classes, you need to call them by their full name in the HTML. - Repeating Sections Restrictions
- Default Fonts: The following fonts can be accessed by default:
Arial
,Patrick Hand
,Contrail One
,Shadows Into Light
andCandal
- Google Fonts: can be used with the
@import
-function [Note: If you use@import
with Google’s own generated URL, you may see the following error:Potential CSS security violation; character sheet template styling thrown out.
To work around this issue, changecss2?family
tocss?family
in the URL (i.e., remove the “2
”).]
- Google Fonts: can be used with the
- Enable use of #id in HTML elements
- You can't refer to external CSS stylesheets. Everything needs to be in the CSS file.
Legacy Sheet
Legacy Sheet is the old sheet coding framework/method, which is more restrictive than CSE.
See Legacy Sheet#Legacy Sheet Restrictions for details.
Repeating Sections
The Repeating Sections are a Roll20-specific design implemented inside <fieldset>
-elements, and comes with their own challenges & quirks that interact with other of the sheet system, such as sheetworkers.
Details: Repeating Sections - Restrictions
Roll Templates
Roll Templates are part of character sheets, but also functions somewhat disjoint, having it's own quirks.
Details: Roll Templates - Restrictions
Mobile
See Character Sheet Development/Mobile
Javascript
Main Section: Sheetworkers - Restrictions
Many JavaScript functions or functionalities can't be used within Roll20, are limited to the Sheetworker framework.
If you're attempting to do any slightly more advanced data-handling, check existing sheet for user-cases. There shouldn't be any differences between Legacy Sheet and CSE for sheetworkers.
Translation
See Character Sheet Translation for how internationalization of sheets work.
Tools
To truly test sheets, one needs to do so inside Roll20 using either available tool, and any try at offline/local testing will lack connection to Roll20's back-end & the default CSS libraries/styling Roll20 has for character sheet elements.
- Sheet Sandbox
- Sheet Editor
- VS Code(recommendation)