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 (PUG & SCSS)
m (Frameworks)
(12 intermediate revisions by one user not shown)
Line 31: Line 31:
  
 
* [https://code.visualstudio.com/ VSCode]
 
* [https://code.visualstudio.com/ VSCode]
* [https://www.sublimetext.com/ Sublime Text 3]
+
* [https://www.sublimetext.com/ Sublime Text]
 
** {{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
 
** {{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
  
Line 54: Line 54:
 
* '''HTML''': [https://validator.w3.org/ W3C's HTML Validator]
 
* '''HTML''': [https://validator.w3.org/ W3C's HTML Validator]
 
** initially give many varnings 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
 
** initially give many varnings 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]
 
* '''JavaScript'''(for sheetworkers & API): [https://closure-compiler.appspot.com/home Closure Compiler for JS]
 
* '''JavaScript'''(for sheetworkers & API): [https://closure-compiler.appspot.com/home Closure Compiler for JS]
 
* '''CSS''': [https://jigsaw.w3.org/css-validator/ W3C's CSS Validator]
 
* '''CSS''': [https://jigsaw.w3.org/css-validator/ W3C's CSS Validator]
* '''JSON'''(for [[i18n|translation files]] & <code>sheet.json</code>: [https://jsonlint.com/?code= jsonlint.com]
+
* '''JSON'''(for [[i18n|translation files]] & [[sheet.json]]: [https://jsonlint.com/?code= jsonlint.com]
  
 
==Frameworks==
 
==Frameworks==
Beyond just using HTML/CSS directly, you could use some pre-processors that can speed up the development, instead of directly writing HTML/CSS. Here is a few suggestion, used by some sheet authors including Roll20 themselves.   
+
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 some sheet authors, including Roll20 themselves.   
  
===PUG & SCSS===
+
[[Cassie]]'s Suggestion:
 +
:''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.''
  
:[[Cassie]]'s Suggestion:
+
:''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.''
::''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.''
+
:''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 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.''
+
===PUG===
 
+
'''PUG''' is a template engine for writing/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.
::''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.''
+
  
 +
<pre data-language="pug" style="overflow:auto;white-space:pre-wrap;">
 +
//- 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)
 +
</pre>
 +
Result HTML:
 +
<pre data-language="pug" style="overflow:auto;white-space:pre-wrap;">
 +
<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>
 +
</pre>
  
'''[https://pugjs.org/ PUG]'''
+
'''[https://pugjs.org/ PUGjs.org]'''
 
* [https://pugjs.org/api/getting-started.html PUG - Getting Started]
 
* [https://pugjs.org/api/getting-started.html PUG - Getting Started]
 
* [https://pughtml.com/ PUG -> HTML online converter]
 
* [https://pughtml.com/ PUG -> HTML online converter]
 
* [https://codingshala.com/pug-tutorial/ codingshala  PUG tutorial]
 
* [https://codingshala.com/pug-tutorial/ codingshala  PUG tutorial]
<br>
+
 
'''[https://sass-lang.com/ SASS/SCSS]'''
+
Examples, Sheets, & Sheet template made with PUG:
 +
* {{gist|Anduh/968bdae0c8dda4f7171fab2561acbea2 Example snippets of SCSS & PUG}}, by [[Andreas J.]]
 +
* {{repo|clevett/SheetTemplate SheetTemplate}} by [[Cassie]]
 +
* {{repo|aureyia/roll20-character-sheet-boilerplate Aureyia's Roll20 Sheet Boilerplate}} - Uses PUG, Stylus(CSS) & Gulp
 +
* {{repo|Roll20/roll20-character-sheets/tree/master/Stargate-RPG Stargate RPG}} active sheet using some PUG & SCSS, by [[Andreas J.]]
 +
* {{repo|roll20-character-sheets/tree/master/Genefunk%202090 Genefunk 2090}} sheet createed with PUG, by [[Scott C.]]
 +
* there are several sheets in the {{repo|Roll20/roll20-character-sheets sheet repository}} made using either or both, you can search  through it to find more examples
 +
 
 +
=== SASS ===
 +
'''[https://sass-lang.com/ 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 <code>.charsheet</code> in from of every class.
 +
 
 +
<pre data-language="scss" style="overflow:auto;white-space:pre-wrap;">
 +
/*-------------------------------------------*/
 +
/*-----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;
 +
  }
 +
}
 +
</pre>
 +
resulting CSS:
 +
<pre data-language="css" style="overflow:auto;white-space:pre-wrap;">
 +
/*-------------------------------------------*/
 +
/*-----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;
 +
}
 +
</pre>
 +
 
 
* [https://sass-lang.com/guide Learn SCSS/SASS]
 
* [https://sass-lang.com/guide Learn SCSS/SASS]
 
* Online Compilers: [https://www.sassmeister.com/ sassmeister playground] | [https://www.cssportal.com/scss-to-css/ cssportal.com]
 
* Online Compilers: [https://www.sassmeister.com/ sassmeister playground] | [https://www.cssportal.com/scss-to-css/ cssportal.com]
Line 86: Line 189:
 
* Guides to SASS/SCSS should be pretty interchangeable, apart from the with/without bracket syntax
 
* Guides to SASS/SCSS should be pretty interchangeable, apart from the with/without bracket syntax
  
<br>
+
Examples, Sheets, & Sheet template made with PUG:
Sheets & Sheet template built using PUG & SCSS, or similar:
+
* {{gist|Anduh/968bdae0c8dda4f7171fab2561acbea2 Example snippets of SCSS & PUG}}, by [[Andreas J.]]
 
* {{repo|clevett/SheetTemplate SheetTemplate}} by [[Cassie]]
 
* {{repo|clevett/SheetTemplate SheetTemplate}} by [[Cassie]]
 
* {{repo|aureyia/roll20-character-sheet-boilerplate Aureyia's Roll20 Sheet Boilerplate}} - Uses PUG, Stylus(CSS) & Gulp
 
* {{repo|aureyia/roll20-character-sheet-boilerplate Aureyia's Roll20 Sheet Boilerplate}} - Uses PUG, Stylus(CSS) & Gulp
* there are several sheets in the {{repo sheets}} made using either or both, you can search  through th
+
* {{repo|Roll20/roll20-character-sheets/tree/master/Barbaric Barbaric!}} sheet using only a bit of scss, by [[Andreas J.]]
 
+
* {{repo|Roll20/roll20-character-sheets/tree/master/Stargate-RPG Stargate RPG}} active sheet using some PUG & SCSS, by [[Andreas J.]]
 +
* there are several sheets in the {{repo|Roll20/roll20-character-sheets sheet repository}} made using either or both, you can search  through it to find more examples
 
=== Handlebars ===
 
=== Handlebars ===
 
Suggestion by [https://app.roll20.net/users/2322441 Primal Zed]
 
Suggestion by [https://app.roll20.net/users/2322441 Primal Zed]
Line 114: Line 218:
  
 
=== Bootstrap===
 
=== Bootstrap===
There are a number of sheets in the {{Repo Sheets}} 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.
+
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==
 
==Git/GitHub==
Line 208: Line 312:
  
 
* {{forum|permalink/8664931 Forum post}} by [[GiGs]], explaining a sheet versioning script, found in this {{gist|G-G-G/52b96cff0b827c42f9d04ab411fb42e8 gist}}
 
* {{forum|permalink/8664931 Forum post}} by [[GiGs]], explaining a sheet versioning script, found in this {{gist|G-G-G/52b96cff0b827c42f9d04ab411fb42e8 gist}}
 +
* {{fpl|8366824/ Primal Zed's example}}
 
* [[Aaron|The Aaron]]'s take on a Versioning script, in the context of [[API]] scripts {{forum|permalink/6606100/ post}}
 
* [[Aaron|The Aaron]]'s take on a Versioning script, in the context of [[API]] scripts {{forum|permalink/6606100/ post}}
 +
* {{fpl|5615535/ Sheet Versioning example - Exalted 3E sheet}} (2017)
 +
** includes attribute migration from static attributes to a [[Repeating Section|repeating section]]. Utilizes {{repo|shdwjk/TheAaronSheet TheAaronSheet}}
 +
 +
 +
See also the '''[[Sheet_Worker_Snippets#Migrate_Attributes|MigrateAttributes]]''' sheetworker examples, both show a simple method for sheet versioning alongside migrating attributes to new names.
  
 
===Improved Sheetworker diagnostics===
 
===Improved Sheetworker diagnostics===
Line 246: Line 356:
  
 
{{ex}}
 
{{ex}}
::'''Using REGEX to add Title code for attribute and roll names'''
+
::'''Using REGEX to add <code>title=</code>(i.e. hover descriptions) for all attributes and roll buttons'''
::Many sheets do not tell users the different attribute names. The easiest method is to include a title="@{attrname}" in each input/select. Buttons could also benefit from adding a title="%{buttonname}" but isn't as big of a deal.
+
::Many sheets do not tell users the different attribute names. The easiest method is to include a <code>title="@{attrname}"</code> in each input/select. Buttons could also benefit from adding a <code>title="%{buttonname}"</code> but isn't as big of a deal.
 
::It's possible to create a regex or some other syntax/replace command that could be run on any sheet that already doesn't have them, and add these attribute name tooltips for all attributes.
 
::It's possible to create a regex or some other syntax/replace command that could be run on any sheet that already doesn't have them, and add these attribute name tooltips for all attributes.
 +
::This same example could be used as a base for creating <code>i18n</code> attributes for [[i18n|sheet translations]]
  
 
::'''Basic syntax to add Attribute titles''':
 
::'''Basic syntax to add Attribute titles''':
Line 270: Line 381:
 
replace regex: name="roll_$1" title="%{$1}"
 
replace regex: name="roll_$1" title="%{$1}"
 
</pre>
 
</pre>
::(Arbitrarily chose "50" as max-length of attr name, use larger number if you might have super long names of course.)
+
::(Arbitrarily chose "50" as the max-length of possible <code>attr</code> names, use a larger number if you might have longer names.)
  
 
==Sharing code/collaboration==
 
==Sharing code/collaboration==
Line 296: Line 407:
 
* [https://google.github.io/styleguide/htmlcssguide.html Google's HTML/CSS Styleguide]
 
* [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://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]
 
* Sheet Templates/Examples
 
* Sheet Templates/Examples
 
** {{repo|Roll20/roll20-character-sheets/tree/master/kitchensink Roll20's "kitchensink"}} Roll20's template (fairly old)
 
** {{repo|Roll20/roll20-character-sheets/tree/master/kitchensink Roll20's "kitchensink"}} Roll20's template (fairly old)
Line 302: Line 414:
 
** {{repo|joesinghaus/Blades-template Sheet template based on Blades in the Dark}} by [[Jakob]]
 
** {{repo|joesinghaus/Blades-template Sheet template based on Blades in the Dark}} by [[Jakob]]
 
** {{repo|aureyia/roll20-character-sheet-boilerplate Aureyia's Roll20 Sheet Boilerplate}} - Uses PUGjs, Stylus(CSS) & Gulp
 
** {{repo|aureyia/roll20-character-sheet-boilerplate Aureyia's Roll20 Sheet Boilerplate}} - Uses PUGjs, Stylus(CSS) & Gulp
 
+
* {{yt.be|k6wDQJnGJCk PT1 coding a Roll20 Character Sheet}} 40min (April 2021)
 
<br>
 
<br>
 
[[Category:Sheetworker]]
 
[[Category:Sheetworker]]

Revision as of 12:26, 28 May 2021

Main Article: Building Character Sheets

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.

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

Web Developer Tools

Uisng the Firefox dev tools to inspect live sheet code

Using the built in Web Dev tools in your browser helps a lot with figuring things out. Both Firefox & Chrome have their own versions, which both are accessed by pressing F12 at any time.


User Cases

  • make live edits on you sheet and see how things change(like adjusting the width of a number input to look good)
  • figure out why something works or doesn't work in your code, to narrow down the problem source (like why a css class is not working)
  • reading the webdev console to figure out what's going on with your sheetworkers. (If you add console.log("set strength mod to" + strmod) to specific places in your code, you can see what steps are taken and what is left out)



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 some sheet authors, including Roll20 themselves.

Cassie's Suggestion:

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 writing/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;
}
  • Learn SCSS/SASS
  • Online Compilers: sassmeister playground | cssportal.com
  • Beginner's Guide to Using SCSS
  • The processor is called SASS, but also means represent the SASS syntax(kinda like CSS, but doesn't use brackets) which is less used. SCSS is the more common syntax used, as it more closely looks like regular CSS.
  • Guides to SASS/SCSS should be pretty interchangeable, apart from the with/without bracket syntax

Examples, Sheets, & Sheet template made with PUG:

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

Suggestion by Cassie

A pattern library can be your best friend if you want to make multiple sheets. Component style programming will let you save styles to be reused between sheets. With my last project I put work into my Sheet Template. This saves me a good deal of time by not needing to start from scratch every time. Its a slow work in progress were I'm reinventing much of Bootstrap.

Helpful Functions

//Convert Integers to be Negative
const convertIntegerNegative = number => number > 0 ? -Math.abs(number) : number

//Convert an object with negative numbers
const convertIntegersNegatives = numbers => {
  numbers => {
    for (let [key, value] of Object.entries(numbers)) {
      numbers[key] = convertIntegerNegative(value);
    }
    return numbers
  }
}

//Pass in eventinfo.triggerName
const findRepeatingField = trigger => trigger.split('_')[1]

//Pass in eventinfo.triggerName
const getReprowid = trigger => {
  const split = trigger.split('_');
  return `${split[0]}_${split[1]}_${split[2]}`
}

//Pass in an object keep that has the repeating section
//Example repeating_weapon_-m1czg68yzicwhfdpyys_name
const getReprowAttribute = key => {
  const getReprowid = processingFunctions.getReprowid(key)
  return key.split(`${getReprowid}_`)[1]
}

//Provide the function with an array of keys to find translations for 
//Example ['strength', 'agility', 'willpower']
const getTranslations = translationKeys => {
  let translations = {}
  translationKeys.forEach(key => translations[`${key}`] = getTranslationByKey(key))
  return translations
}

const parseInteger = string => parseInt(string) || 0

//Use for converting the result of getAttrs from strings into integers
const parseIntegers = numbers => {
  for (let [key, value] of Object.entries(numbers)) {
      numbers[key] = parseInt(value) || 0
  }
  return numbers  
}

const setAttributes = (update, silent) => silent && typeof update === 'object' ? setAttrs(update, {silent:true}) : typeof update === 'object' ? setAttrs(update) : console.error(`${update} is not an object`)

//returns strength from @{strength}
const sliceAttr = attribute => attribute.slice(2, -1)

const sumIntegers = numbers => numbers.reduce((a,b) => a + b, 0)

Sheet Versioning

It can be beneficial to use a visible sheet version on a sheet, so people know when the sheet have updated. Also using sheet version will make it easier for you and others to track the state of the sheet and possible changelog.

If you have complex stat & sheetworkers in you sheet and make changes to them, it can be beneficial to add sheet versioning sheetworker that updates things for character using older version of the sheet to a new one.

An example would be to update an attribute name with a typo, to one with the correct spelling. The sheet versioning would next time a sheet is opened notice it is a older version, and then perform the sheet update transferring the attribute values of the old attribute to the new one, while it would do nothing on sheet that are already the latest version.


See also the MigrateAttributes sheetworker examples, both show a simple method for sheet versioning alongside migrating attributes to new names.

Improved Sheetworker diagnostics

TheAaronSheet contains a number of helpful sheetworker functions like simplifying repeating sections, but it also has a improved debugging settings that can help making various dev console messages more distinct.

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.





Documentation

The "Instructions"-section of the sheet.json is a bit unwieldy to fill out and structure(mix of normal Markdown-syntax, and using /n for line breaks), so it might be easier to place any larger documentation here on the Roll20 Community Wiki.

If the character sheet have several tabs or is long, the wiki could better fit more preview images of the sheet, rather than having something complicated on GitHub/the Sheet Template Preview.

Alternatively, add a Readme.md-file in the same folder with the sheet code, and then write sheet instructions using Markdown on it.

Link to the sheet's wiki page/readme in the "Instructions" (e.g. For sheet instructions, go to [ExampleRPG](https://wiki.roll20.net/ExampleRPG)..

Using REGEX

One method of saving time with sheet dev is to use regex to find & replace more complex things in code.


Example:

Using REGEX to add title=(i.e. hover descriptions) for all attributes and roll buttons
Many sheets do not tell users the different attribute names. The easiest method is to include a title="@{attrname}" in each input/select. Buttons could also benefit from adding a title="%{buttonname}" but isn't as big of a deal.
It's possible to create a regex or some other syntax/replace command that could be run on any sheet that already doesn't have them, and add these attribute name tooltips for all attributes.
This same example could be used as a base for creating i18n attributes for sheet translations
Basic syntax to add Attribute titles:
find all: name="attr_REGEX"
replace with: name="attr_REGEX" title="@{REGEX}"
REGEX is replaced with regex commands or some other search syntax that search/accepts alphanumerals, -, _ (in essence, anything that's a valid attribute name)
Basic syntax to add Roll buttons titles:
find all: name="roll_REGEX"
replace with: name="roll_REGEX" title="%{REGEX}"
Attribute example:
find regex: name="attr_([A-Za-z0-9_-]{1,50})"
replace regex: name="attr_$1" title="@{$1}"
Buttons example:
find regex: name="roll_([A-Za-z0-9_-]{1,50})"
replace regex: name="roll_$1" title="%{$1}"
(Arbitrarily chose "50" as the max-length of possible attr names, use a larger number if you might have longer names.)

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