Roll20 Wiki

{{revdate}}{{BCS}}


This is a collection of more advanced [[Sheet Author]] Tips that currently doesn't fit on the [[:Category:Character_Sheet_Creation|other pages relating to character sheet creation & editing]]. Most of the suggestions & ideas are taken from the Roll20 forums, or discussions among Sheet Authors.

'''[[Sheet Author]]''' is a badge people who have created & submitted [[CS|character sheets]] to Roll20 get.

__TOC__

==Read the documentation==
Give the [[Building Character Sheets]]-article a full read, as it contains lots of information on the specific quirks & pitfalls of how Roll20 character sheets works compared to default HTML/CSS/JavaScript. Even if you know how things work.

Some Highlights:

* [[Character Sheet Development/Common Mistakes|Common Mistakes]]
* [[Building_Character_Sheets#Best_Practices|Best Practices]]
* [[Building_Character_Sheets#Advanced_Sheet_Options|Advanced Sheet Options]]

==[[Custom Sheet Sandbox|Sheet Sandbox]]==
Using the [[Custom Sheet Sandbox|Sheet Sandbox]] while editing/developing character sheets is much more effective and quicker than the normal [[Building_Character_Sheets#The_Sheet_Editor|Sheet Editor]].

Alongside it, most authors use a text editor such as [https://code.visualstudio.com/ VSCode] or [https://www.sublimetext.com/ Sublime Text].

===[[Sheet Autouploader|Autouploader]]===
{{:Roll20 Autouploader}}
{{clear}}
==Code with a Proper Text Editor==
Rather than using the built-in code editor, all sheet authors who do sheets with any regularity use a separate text editor meant for coding, as they makes things much easier, and have tons of features  & extensions that are useful.

Some use an [[wikipedia:Integrated_development_environment|IDE]], but due to Roll20 having a bunch of unique stuff, it's not really practical to test code locally. It's best to test the code live in a [[Sheet Sandbox]], or the [[Sheet Editor]].

It's quicker to edit & save code on your computer, then upload the new sheet version to the [[Sheet Sandbox]] through the menu, than editing & using the [[Sheet Editor]].

Popular Text Editors(among [[Sheet Author|sheet authors]]):

* [[VS Code]](Windows, Mac, Linux) ([https://code.visualstudio.com/ dl])
* [https://www.sublimetext.com/ Sublime Text] (Windows, Mac, Linux)
** {{repo|Anduh/SublimeSettings SublimeSettings}} - Roll20-specific HTML Syntax highlight that also does [[sheetworker]] highlight in html sheets. Created by [[Andreas J.]], based on [[Cassie]]'s  original HTML+JS combo highlighter
* [https://notepad-plus-plus.org/ Notepad++] (Windows Only)

===VS Code===
{{:VS Code}}

==Web Developer Tools==
{{main|Character Sheet Development/Debugging}}
{{NavSheetDoc}}
==Code Validation==
It's a good idea to use a validator to check your code for mistakes in your code. Many IDE & text editors can install such extensions automatically, but given that Roll20 does a few things their own way, by default a HTML validator would complain about lot of things that aren't wrong, but just isn't accepted as standard HTML, such as <code><button type="roll"></button></code>.

* '''HTML''': [https://validator.w3.org/ W3C's HTML Validator]
** initially give many warnings and errors on roll20-specific things, but you can filter away things that aren't wrong, and the list of error is quickly reduced to a manageable amount
** [https://developer.mozilla.org/en-US/docs/Learn/HTML/Introduction_to_HTML/Debugging_HTML Debugging HTML]
* '''CSS''': [https://jigsaw.w3.org/css-validator/ W3C's CSS Validator]
** [https://developer.mozilla.org/en-US/docs/Learn/CSS/Building_blocks/Debugging_CSS Debugging CSS]
* '''JavaScript'''(for sheetworkers & API): [https://closure-compiler.appspot.com/home Closure Compiler for JS]
* '''JSON'''(for [[i18n|translation files]] & [[sheet.json]]: [https://jsonlint.com/?code= jsonlint.com]

==Frameworks==
Beyond just using HTML/CSS directly, you could use some pre-processors, language extensions, or frameworks that can speed up the sheet development, instead of directly writing HTML/CSS. Here are a few suggestions, used by a good number of sheet authors, including Roll20's teams working on the official sheets.  

:''Use PUG & SASS/SCSS & JavaScript to make sheets. PUG & SCSS are the two most useful things I've ever learned for sheet development. Character sheets which use to take hundred+ hours takes now 20-40 thanks to PUG which is a JavaScript based language to write HTML. You'll save yourself a lot of redundant work by just using the power of loops & variables if nothing else.''

:''Troubleshooting becomes much easier when you need to fix just one line in a loop rather than a dozen copy/paste html snippets.''

:''PUG and SCSS can be used to simply split up the HTML & CSS files into smaller, more manageable files, which can then simply be compiled into their end results when it's time to use the sheet in a game.''

:''These are compiled languages so you'll need to do that. Easily done via terminal if your tech savy, or [https://prepros.io/ prepros.io] if you're not.''

===PUG===
{{:PUGjs}}

=== SASS ===
{{:SASS}}

=== Handlebars ===
Suggestion by [https://app.roll20.net/users/2322441 Primal Zed]

{{forum|post/8380005/sheet-templating-with-handlebars thread}}

'''Pros:'''

* Looks like HTML (or whatever file type you're templating), with handlebars blocks added in
* Inject data values anywhere directly into the HTML
* Can yield benefit with little effort - sheet authors can use as much or as little as they want
* Handlebars blocks have opening and close tags similar to HTML
* Easy to add new templates for re-use and organization

'''Cons:'''

* Involves new syntax to learn and helpers to understand
** Built-In Helpers
** For advanced use: Additional Helpers
** For advanced use: Repeat Helper
* Requires Node.js installation and some command lines

=== Bootstrap===
There are a number of sheets in the {{repo|Roll20/roll20-character-sheets repository}} that have been built with [https://getbootstrap.com/ Bootstrap], but using it for sheet development is a bit on the heavy side, and can have a higher bar to get started with than only using pre-prosessors like PUG and SASS.

==Git/GitHub==
* [[Beginner's_Guide_to_GitHub| Beginner's Guide to GitHub(Roll20)]]
* [[Short Git Guide]] - A guide to using the command line version of Git to work on your computer, instead of GitHub Desktop

===Install the Pull App to GitHub===

{{warning|Be sure to create separate branches on your fork for editing since the PULL bot might overwrite your <code>master</code>-branch when syncing with the Roll20 repository. Use at your own risk.}}
[https://wei.github.io/pull/#basic-setup Pull App] is a GitHub bot that can automatically watch and pull in Roll20's upstream default <code>master</code>-branch to your fork using hard reset every few hours. You can also manually trigger it anytime.

Failure to keep your GitHub fork in sync with the master repo can create merge conflicts causing a pull request to be rejected or delayed. The Pull App can help automate this process and keep your fork in sync with Roll20's <code>master</code>-branch.

'''While the Pull App will sync in the background every few hours, it is recommended that you manually run the bot before creating a branch for editing to ensure your fork's <code>master</code>-branch is in sync with Roll20's most current <code>master</code>-branch.'''

===Use Branches in GitHub===

Do not make changes to your GitHub <code>master</code>-branch. Instead make a branch from <code>master</code> to do all upgrades there. Submit pull request to the Roll20 repo directly from a branch. This is a safe way to do version control and will improve the integrity of your work.



==Pattern Libraries & Components==
{{main|Character Sheet Development/Pattern Libraries}}

{{:Character Sheet Development/Pattern Libraries}}

==Advanced Sheet Features==

===Statblock Importer===
Some sheets have integrated options to import sheets to Roll20, such as for plaintext or <code>.json</code> statblocks.

Existing Sheets with integrated import functions:
* [[Mutants & Masterminds 3E Official#Hero_Labs_Importer|Mutants & Masterminds 3E Official]] -herolab importer
* [[Pathfinder Community Sheet#HeroLab Character import|Pathfinder Community Sheet]] - herolab importer
* [[Official_Savage_Worlds#JSON_Importer|Official Savage Worlds]] - json importer 
* {{sheet-gh|Shadowrun5thEdition Shadowrun5thEdition}} & {{sheet-gh|Shadowrun5th Shadowrun5th}} both have Chummer importers
* [[GeneFunk2090]] statblock importer
* {{sheet-gh|Mythras/src/scripts/import.js Mythras}} json importer


Some sheets have instead a separate [[API]] for this purpose. 

===GM Screen===
Sometimes just an NPC sheet isn't enough, and it would be beneficial for the GM to have a GM Screen built into the sheet.

===Changelog and Update Notification inside Sheet===
[[File:GURPS-sheet-update-notice.png|right|thumb|350px|The GURPS sheet displaying the latest sheet update notice.]]
If you a lots of changes to a sheet, or want to make sure that all users of the sheet are informed of the updates, you could integrate the sheet changelog & notification into the sheet, so next time they open a sheet their sheet they seem the update notice, & can dismiss them at will.

Alternatively, the changelog could be placed on a separate tab, such as folded it into the '''Settings'''-tab 

The team behind the [[GURPS]] character sheet is a great example of incorporating a comprehensive changelog into the sheet, with a collapsible notice of the latest update/message from the sheet authors, and is non-obstructive even when not dismissed.
* {{repo|Roll20/roll20-character-sheets/tree/master/GURPS GURPS 4E sourcecode}}
* https://app.roll20.net/forum/post/10732652/notifying-users-of-changes-to-sheet
<br clear="right">

==Sharing code/collaboration==
If you need to share larger parts of a sheets code with others on the Roll20 forums or somewhere else quickly, using [[Beginner's_Guide_to_GitHub#GitHub_Gist|GitHub Gist]] to share the full sheet is a smart alternative to Dropbox/Google Drive/Pastebin.

The "Revisions" tab of a gist shows clearly code changes between revisions, so tracking what have changed makes things easier for you and others.

* [http://hilite.me/ hilite.me] can be used to convert your code to pretty html-formatted code that's very clear when copypasted to the [[forums]]. (Trick by [[Aaron|The Aaron]])

=Related Pages=
* [[Custom Sheet Sandbox|Sheet Sandbox]] – the better editor to use when you code your character sheets
* [[Javascript:Best Practices]]
* [[Sheet Author's Journey]] - tutorial
* [[Andreas Guide to Sheet Development]] - general advice & mentions of things to consider when developing sheets
* [[Building Character Sheets]] - main article
** [[CSS Wizardry]] - List of Tips & Tricks on how to create a variety of effects on your character sheet
** [[Designing Character Sheet Layout]] - tips on how to best design the broad strokes of a character sheet
** [[Default Sheet Settings| Default Sheet Settings]] - Customize default settings and values of new character sheets added to a campaigns 
** [[:Category:Character Sheet Creation|List of all pages related to "Character Sheet Creation"]]
* [[Reusing Rolls]] - Recent macro-related discovery that have uses for character sheet rolls

==See Also==
* Community
** {{forum|category/277980 Roll20 Forums - Character Sheets & Compendiums}} - Best place for discussing Sheets with other [[Sheet Authors]], and to get clatest info
** [https://discordapp.com/invite/sMsv5KD Unofficial Roll20 Discord] - The Discord server have two channels for discussing Character Sheet Creation, and many active Sheet Authors are present.
* [https://google.github.io/styleguide/htmlcssguide.html Google's HTML/CSS Styleguide]
* [https://css-tricks.com/css-style-guides/ css-tricks.com Style Guides collection]
** [https://developer.mozilla.org/en-US/docs/Web/CSS/:is is() pseudo-class]
* [[Character_Sheet_Development/Sheet_Templates|Sheet Templates/Examples]]
* {{yt.be|k6wDQJnGJCk PT1 coding a Roll20 Character Sheet}} 40min (April 2021) 
<br>
[[Category:Sheetworker]]
[[Category:Character Sheet Creation]]
[[Category:Character Sheet Development]]
[[Category:Tips]]
[[Category:External Tools]]