Character Vault
Any Concept / Any System
Compendium
Your System Come To Life
Roll20 for Android
Streamlined for your Tablet
Roll20 for iPad
Streamlined for your Tablet

Personal tools

Difference between revisions of "Sheet Author Tips"

From Roll20 Wiki

Jump to: navigation, search
m (Changelog and Update Notification inside Sheet)
m
Line 21: Line 21:
  
 
Alongside it, most authors use a text editor such as [https://code.visualstudio.com/ VSCode] or [https://www.sublimetext.com/ Sublime Text].
 
Alongside it, most authors use a text editor such as [https://code.visualstudio.com/ VSCode] or [https://www.sublimetext.com/ Sublime Text].
 +
 +
'''Browser Extension: [[R20AutoCode‎‎]]''' - automates sheet code upload to Sheet Sandbox, streamlining development.
  
 
==Code with a Proper Text Editor==
 
==Code with a Proper Text Editor==

Revision as of 06:11, 16 May 2022


This is a collection of more advanced Sheet Author Tips that currently doesn't fit on the 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 character sheets to Roll20 get.

Contents


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:

Sheet Sandbox

Using the Sheet Sandbox while editing/developing character sheets is much more effective and quicker than the normal Sheet Editor.

Alongside it, most authors use a text editor such as VSCode or Sublime Text.

Browser Extension: R20AutoCode‎‎ - automates sheet code upload to Sheet Sandbox, streamlining development.

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 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 authors):

VS Code

Visual Studio Code(VS Code) is a popular text editor. It's free, and available for Windows/Linux/Mac, as well as accessible online through vscode.dev.

VS Code has some uses with Roll20, primarily for editing complicated macros, and for Character Sheet Creation.

Here are some useful VS Code extensions:

Roll20 Syntax Highlight

Showcase of Roll20 Macros

Roll20 Macros by Andreas J.

Extension to make roll20 macro and API command writing & troubleshooting easier. Highlight works when you use VSCode to view .rmacro-files.

Features:

  • bracket pairing & highlights
    • shows with colors which brackets/parentheses belong together(making mismatched brackets easier to find)
    • does this for roll20 macros syntax too (@{ }, ?{ }, %{ }, &{ }, $[[ ]])
  • syntax highlight
    • roll, macro & API commands (e.g. /r, !example, #dex)
    • in dice rolls, d & dF
    • some common keywords, like selected, template, %%NEWLINE%%
    • special characters used in macros (e.g. ~,|#=+, and HTML Entities)
  • Features: full summary

Roll20 Sheet Dev

Showcase of Roll20 Sheet Dev

Roll20 Sheet Dev by Andreas J.

Extension to help with Character Sheet Development.

Features:

Other Extensions


Web Developer Tools

Main Page: Character Sheet Development/Debugging

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 <button type="roll"></button>.

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 prepros.io if you're not.

PUG

PUG is a template engine for generating HTML, where you can use various features & tool to write code more efficiently, such as using variables and loops, and has a simpler syntax.

//- Comment that only appears in PUG
- var pages = ["character", "skills", "inventory", "magic", "familiar", "background", "campaign", "vehicle", "settings"];
div
  span Page selection
  select(name="attr_sheetTab")
    each tab in pages
      option(value=`${tab}`)= tab[0].toUpperCase() + tab.slice(1)

Result HTML:

<div>
     <span>Page selection</span><select name="attr_sheetTab">
        <option value="character">Character</option>
        <option value="skills">Skills</option>
        <option value="inventory">Inventory</option>
        <option value="magic">Magic</option>
        <option value="familiar">Familiar</option>
        <option value="background">Background</option>
        <option value="campaign">Campaign</option>
        <option value="vehicle">Vehicle</option>
        <option value="settings">Settings</option>
    </select>
</div>

PUGjs.org

Examples, Sheets, & Sheet template made with PUG:


SASS

SASS/SCSS is a widely used CSS extension language. It's CSS Compatible, so you can start using it by writing plain CSS first, and slowly including more SASS features, while keeping it familiar & looking mostly like CSS.

One of the things you can do it to nest your code, saving you from repeating yourself with things like needing to add .charsheet in from of every class.

/*-------------------------------------------*/
/*-----Main Settings and hide classes--------*/
// comments with two slashes won't appear in the resulting .css,  which is handy for writing extra comments thaat aren't relevant to the css.
// SCSS enables nesting of classes, saving time in writing, and making it easier to read/organize the CSS. There are also tother features,but this is the main one I've started to use, as it helps with reading the scss/css. One can start from pure css, and then bit by bit simplify/refactor it to use more scss features
.charsheet {
	.main-settings {
	    display: none;
		position: relative;
		margin-left: 0;
		
		.container {
			width: 850px;
		}
		.input-row {
			label {
				display: inline-block;
				width: auto;
			}
			input {
				margin-right: 30px;
			}
			select {
				width: 45%;
				margin-right: 15px;
			}
		}
	}
  input.main-options.options-flag + span,/*displays the cog icon*/
  input[type=radio]:checked ~ .master-container input.options-flag + span {
      font-family: pictos;
      font-style: normal;
  }
}

resulting CSS:

/*-------------------------------------------*/
/*-----Main Settings and hide classes--------*/
.charsheet .main-settings {
  display: none;
  position: relative;
  margin-left: 0;
}
.charsheet .main-settings .container {
  width: 850px;
}
.charsheet .main-settings .input-row label {
  display: inline-block;
  width: auto;
}
.charsheet .main-settings .input-row input {
  margin-right: 30px;
}
.charsheet .main-settings .input-row select {
  width: 45%;
  margin-right: 15px;
}
.charsheet input.main-options.options-flag + span,
.charsheet input[type=radio]:checked ~ .master-container input.options-flag + span {
  font-family: pictos;
  font-style: normal;
}

Examples, Sheets, & Sheet template made with SASS:


Handlebars

Suggestion by Primal Zed

thread(Forum)

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 repository that have been built with 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

Install the Pull App to GitHub

Pull App is a GitHub bot that can automatically watch and pull in Roll20's upstream default master-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 master-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 master-branch is in sync with Roll20's most current master-branch.

Use Branches in GitHub

Do not make changes to your GitHub master-branch. Instead make a branch from master 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 Page: 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 .json statblocks.

Existing Sheets with integrated import functions:


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

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.


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

  • 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 The Aaron)

Related Pages

See Also