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
m (PUG & SCSS)
(9 intermediate revisions by one user not shown)
Line 1: Line 1:
Here is a list of Sheet Author Tips for when working with character sheets & submitting your updates to Roll20, taken from the forums.
+
''Main Article:'' '''[[Building Character Sheets]]'''
 +
 
 +
This is a collection of more advanced Sheet Author Tips that doesn't fit the other pages. Most of the suggestions& ideas are taken from the forums.
  
 
__TOC__
 
__TOC__
Line 11: Line 13:
 
* [[Building_Character_Sheets#Best_Practices| Best Practices]]
 
* [[Building_Character_Sheets#Best_Practices| Best Practices]]
 
* [[Building_Character_Sheets#Advanced_Sheet_Options|Advanced Sheet Options]]
 
* [[Building_Character_Sheets#Advanced_Sheet_Options|Advanced Sheet Options]]
 +
 +
==[[Custom 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]].
  
 
==Frameworks==
 
==Frameworks==
Line 21: Line 26:
  
 
Troubleshooting becomes much easier when you need to fix just one line in a loop rather than a dozen copy/paste html snippets.
 
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/ if you're not.
 
These are compiled languages so you'll need to do that. Easily done via terminal if your tech savy or https://prepros.io/ if you're not.
Line 51: Line 59:
 
===Install Pull to GitHub===
 
===Install Pull to GitHub===
  
EVERYONE should install Pull on theirs forks!! https://wei.github.io/pull/#basic-setup GiGs found this a bit ago and it is incredibly useful for keeping forks updated. So many pull request get rejected or delayed due to a failure to keep GitHub forks in sync with the master repo. This will automate that for you.
+
[https://wei.github.io/pull/#basic-setup Pull] is a GitHub bot GiGs found, and it can automatically keep your fork updated to Roll20 main repo.
 +
 
 +
So many pull request get rejected or delayed due to a failure to keep GitHub forks in sync with the master repo. This will automate that for you.
 +
 
 +
It's recommended to manually run the bot before each time you start on a new thing, to avoid it performing updates when Roll20 is in the middle of merging new pull requests. This caused lot of problems when people had it to automatically update repos. 
  
 
===Use Branches in GitHub===
 
===Use Branches in GitHub===
Line 120: Line 132:
 
</pre>
 
</pre>
  
=See Also=
+
=== Sheet Versioning===
* [[CSS Wizardry]] - List of Tips & Tricks on how to create a variety of effects on your character sheet
+
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.
* [[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  
+
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.
* [[:Category:Character Sheet Creation|List of all pages related to "Character Sheet Creation"]]
+
 
 +
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.
 +
 
 +
[https://app.roll20.net/forum/permalink/8664931/ Forum post] by {{user profile|157788|GiGs}}, explaining a sheet versioning script, found in this [https://gist.github.com/G-G-G/52b96cff0b827c42f9d04ab411fb42e8 gist]{{github}}
 +
===Improved Sheetworker diagnostics===
 +
[https://github.com/shdwjk/TheAaronSheet 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.
 +
 
 +
===Sheet Changelog and notification===
 +
[[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 the users of the sheet are informed of the updates, you could integrate the sheet changelog & notice into the sheet, so everyone will know of the changes, & can dismiss them at will. Alternatively the changelog can be placed on a tab somewhere
 +
 
 +
The team behind the [[GURPS]] character sheet is an example of incorporating a comprehensive changelog into the sheet, with a collapsible notice of the latest update/message from the sheet authors.
 +
<br>
 +
<br>
 +
<br>
 +
<br>
 +
<br>
 +
=== Documentation ===
 +
The "instructions" section of the sheet.json is a bit unwieldy to fill out, so it might be easier to place any larger documentation here on the Roll20 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.
 +
 
 +
==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.
 +
 
 +
=Related Pages=
 +
* [[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
 +
** [https://app.roll20.net/forum/category/277980 Roll20 Forums - Character Sheets & Compendiums] - Best place for discussing Sheets with other Sheet Creators, and to get current 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]
 +
* Sheet Templates/Examples
 +
** [https://github.com/Roll20/roll20-character-sheets/tree/master/kitchensink Roll20's character sheet] Roll20's template
 +
** [https://github.com/clevett/SheetTemplate Cassie's sheet template] by Cassie (Uses PUG/SCSS so not recommended for beginners)
 +
** [https://github.com/Anduh/Roll20-grid-template CSS Grid sheet template] by Anduh
 +
** [https://github.com/joesinghaus/Blades-template Sheet template based on Blades in the Dark] by Jakob
 +
 
 
<br>
 
<br>
 
[[Category:Sheetworker]]
 
[[Category:Sheetworker]]
 
[[Category:Character Sheet Creation]]
 
[[Category:Character Sheet Creation]]

Revision as of 14:02, 22 October 2020

Main Article: Building Character Sheets

This is a collection of more advanced Sheet Author Tips that doesn't fit the other pages. Most of the suggestions& ideas are taken from the forums.

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:

Custom Sheet Sandbox

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

Frameworks

Beyond just using HTML/CSS directly, you could use some pre-processors that can speed up the development, instead of directly writing HMTL/CSS. Here is a few suggestion, used by some sheet authors including Roll20 themselves.

PUG & SCSS

Suggestion by Cassie

Use PUG & 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/ if you're not.

Handlebars

Suggestion by Primal Zed

Forum 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

Git/GitHub

Install Pull to GitHub

Pull is a GitHub bot GiGs found, and it can automatically keep your fork updated to Roll20 main repo.

So many pull request get rejected or delayed due to a failure to keep GitHub forks in sync with the master repo. This will automate that for you.

It's recommended to manually run the bot before each time you start on a new thing, to avoid it performing updates when Roll20 is in the middle of merging new pull requests. This caused lot of problems when people had it to automatically update repos.

Use Branches in GitHub

Do not make changes to your GitHub master. 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 transations for 
//Example ['strenght', 'agility', 'willpower']
const getTranslations = translationKeys => {
  let translations = {}
  translationKeys.forEach(key => translations[`${key}`] = getTranslationByKey(key))
  return translations
}

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

//Use for convernting 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 @{strenght}
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.

Forum post by GiGs, explaining a sheet versioning script, found in this gistTemplate:Github

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.

Sheet Changelog and notification

The GURPS sheet displaying the latest sheet update notice.

If you a lots of changes to a sheet, or want to make sure that the users of the sheet are informed of the updates, you could integrate the sheet changelog & notice into the sheet, so everyone will know of the changes, & can dismiss them at will. Alternatively the changelog can be placed on a tab somewhere

The team behind the GURPS character sheet is an example of incorporating a comprehensive changelog into the sheet, with a collapsible notice of the latest update/message from the sheet authors.




Documentation

The "instructions" section of the sheet.json is a bit unwieldy to fill out, so it might be easier to place any larger documentation here on the Roll20 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.

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.

Related Pages

See Also