Sometimes, people come to the Roll20 Forums confused why their sheet code isn’t working. In helping them, we learn the answer is that they tested their code in one of the many websites designed to test HTML, CSS, and JavaScript. And that prompts a very familiar refrain: You must always test Roll20 sheets on Roll20.
People who know a little bit of coding may be tempted to reply that they know what they are doing, and their code should work. Why doesn’t it?
I understand that impulse. And they are right – it would work on other sites. But Roll20 is different. It has its own coding limitations. Some things that do work elsewhere will not work on Roll20.
That is why the truism is correct: test your sheets on Roll20.
On this page, I’ll explain some of the major gotchas, the most common things that trip people up. But Andreas, of the Roll20 forums, has covered this ground already. So if you want an extremely comprehensive list of things to account for, go to Building Character Sheets on the Roll20 wiki.
There are three separate coding languages used to make up a character sheet – HTML, CSS, and JavaScript. And every single one of those has differences on Roll20 that affect how a Roll20 sheet appears, and whether it even works. Let’s cover each in turn.
HTML
When you visit a webpage, that page is drawn from a header to a footer, and each part of the page has its own section of code, including header, body, footer, etc. many of these are standardised, and its natural to build a roll20 character sheet the same way.
But a roll20 character sheet is only part of the webpage. On roll20, you have the battlemap and the sidebars, among other things, and all those are part of the webpage. The character sheet itself is only a small part of the website. There might even be several character sheets open at the same time, all contained in their own frames within the single Roll20 campaign website.
And so, there are common HTML terms you cannot use, like <html> <head>, <title>, or <body>.
Your character sheet is not a complete website.
Legacy vs CSE
A relatively new complication is the Character Sheet Enhancement. Roll20 introduced an upgrade to their treatment of HTML, to improve their code and make some features work that didn’t before.
Unfortunately, there’s always a downside. Existing sheets needed to be upgraded to work with it, but it wasn’t practical to assume that all sheets would be. There are hundreds of sheets, and some have been abandoned by authors but are still in use.
Everything on this website assumes sheets will be written using CSE. There is no reason to create a new sheet using Legacy code. But many still exist, so Roll20 has to support both.
That creates a complication when giving advice – we have to first figure out which code a sheet is using, and a writer who hasn’t followed Roll20 changes may not know!
Anyway, if you are using CSE some HTML elements now work that didn’t before, like <datalist>, <details>, <summary>, <a href>, main, and section. So if you are having issues with any of those, you are probably using Legacy code and should upgrade your sheet to modern CSE. This is easier than it sounds. See CSS below.
CSS
Luckily, CSS is very easy, and works for the most part as you’d expect from other websites. There are two main complications:
- If you are using Legacy code, you need to prepend sheet- to all class names (so the class name legacy would become sheet-legacy) and ids are not recognised.
- Roll20 has helpfully pre-applied some styles to some elements, and if you want to override those styles to replace with your own, you need to take advantage of specificity.
Upgrading a Legacy Sheet to CSE
For the most part this is easy. And there are two different ways to proceed (use one, don’t mix and match):
- In CSS, remove sheet- from all class names.
- In HTML, add sheet- to all classnames.
Either of these will fix the issue, and you can immediately take advantage of the new CSE features.
There is one complication (as always):
RollTemplates
Rolltemplate CSS does not take advantage of the new CSE features, and the most important part of this is that classnames still need to be prepended with sheet-.
So, you do need to be careful when updating a sheet to CSE. If the styling in a rolltemplate suddenly stops working, make sure you havent accidentally “fixed” their class names, and if so restore them.
It’s likely that at some point in the future, Rolltemplates will not have this issue. But for now, you have to be careful.
JavaScript
There is really just one issue with JavaScript, but its a massive one. It means that all code you find on other sites will not work on Roll20.
All JScript code elsewhere uses something called the DOM, or Document Object Model, and on Roll20, we are forbidden from attempting to modify the DOM.
It’s important to remember what JavaScript is allowed to do on Roll20:
- Create and modify current values of attributes (and ‘attribute’ has a specific meaning on Roll20)
- And that’s it, really.
There are some expansions to this that muddy the water, a little. Action buttons and RollQuery – which will be covered later – expand the basics of what’s allowed, but anything containing the object document is not allowed, and that is almost everything you’ll find on other sites.
So the important realisation is this: any JavaScript you create must be created specifically for Roll20. It will not work anywhere else, and code created for other sites will not work on Roll20.
Other Assorted Considerations
Those are the big things. There are a few other assorted gotchas. Some are blanket stops like the above, and some are strong recommendations. For example:
- don’t use Tables for layout – they will work but Roll20 doesn’t allow them.
- Don’t use anything containing the word eval, which includes, for example, the word medieval.
- When creating attribute names, try to use names that also work as JavaScript variable names. This isn’t a rule but will make your life easier.
It’s also worth at least skimming the wiki page about Roll20 Bugs & Quirks if you have weird issues, to see if you have accidentally hit any problems. But if you avoid the issues on this page, you should be okay.
