Difference between revisions of "Character Sheet Development/Best Practice"
From Roll20 Wiki
Andreas J. (Talk | contribs) m (→Sheetworkers & Roll Templates) |
Andreas J. (Talk | contribs) m |
||
| (3 intermediate revisions by one user not shown) | |||
| Line 4: | Line 4: | ||
===Attributes/Inputs=== | ===Attributes/Inputs=== | ||
| − | * '''Attribute names should be lowercase'''. For the sake of consistency & to avoid some quirks related to [[sheetworkers]], it's best to always give lowercase attribute names, such as | + | * '''Attribute names should be lowercase'''. For the sake of consistency & to avoid some quirks related to [[sheetworkers]], it's best to always give lowercase attribute names, such as {{c|attr_strength}}, {{c|attr_strength_mod}}, which will then be called in macros and sheetworkers as {{c|strength}}, {{c|strength_mod}}. It might be a good idea to limit them to [https://en.wikipedia.org/wiki/Alphanumericals alphanumerical] + {{c|_}} and {{c|-}}. |
| − | * '''RPGs have weird words'''. Utilize <code>spellcheck="false"</code> for text inputs and | + | * '''RPGs have weird words'''. Utilize <code>spellcheck="false"</code> for text inputs and {{c|<textarea>}}, to prevent the browser from indicating spell errors. |
| − | * '''Use fewer Attributes & Inputs'''. The more attributes and inputs you have the slower the sheet will load. This is not a concern for the average sheet but robust sheets such as the ''[[D&D 5E Sheet by Roll20]]''- or the ''[[Pathfinder (Community)]]''-sheets large amount of attributes & inputs can lead to performance issues if left unmanaged. If [[sheetworkers]] need to process many attributes often, or the game relies on characters having many entires in [[Repeating Sections]], it might impact performance. | + | * '''Use fewer Attributes & Inputs'''. The more attributes and inputs you have the slower the sheet will load. This is not a concern for the average sheet but robust sheets such as the ''[[D&D 5E by Roll20|D&D 5E Sheet by Roll20]]''- or the ''[[Pathfinder (Community)]]''-sheets large amount of attributes & inputs can lead to performance issues if left unmanaged. If [[sheetworkers]] need to process many attributes often, or the game relies on characters having many entires in [[Repeating Sections]], it might impact performance. |
* '''Spans over disabled inputs'''. [[CSS_Wizardry#Attribute-Backed_.3Cspan.3Es|Attribute-backed spans]] are more efficient than disabled inputs. | * '''Spans over disabled inputs'''. [[CSS_Wizardry#Attribute-Backed_.3Cspan.3Es|Attribute-backed spans]] are more efficient than disabled inputs. | ||
| Line 21: | Line 21: | ||
===Other Roll20-specific=== | ===Other Roll20-specific=== | ||
| + | * '''Include a minimum width'''. Including a minimum width on the sheet will help with resizing. Try to not exceed the default width when a sheet opens for the first time, approximately 800px-900px. Character sheets with an NPC view may be smaller and elaborate PC sheets are sometimes bigger. Currently{{source|May 2022}} it's not possible to change the default width of the char sheet window, so if your sheet is much wider than the window, it might be annoying for users to have to resize them each time they are opened. | ||
| − | * ''' | + | * '''Use Supported Fonts'''. Either use the five named fonts ({{c|Arial}}, {{c|Patrick Hand}}, {{c|Contrail One}}, {{c|Shadows}} {{c|Into Light}}, and {{c|Candal}}), or [[BCS/CSS#Google_Fonts|Google Fonts]]. Roll20 also comes with some [[CSS_Wizardry#Icon_Fonts|Icon Fonts]], and it's possible to us Google's [[Character_Sheet_Development/CSS#Material_Icons|Material Icons]]. |
| + | |||
| + | * '''Use <code>^{ }</code> for [[i18n|translations]] in button macros'''. In your [[Character Sheet Development/Button#Roll_Macro|button macros]] using <code>^{key}</code> will insert the appropriate key from the appropriate language's <code>translation.json</code>. This makes roll templates more adaptable to other languages, and avoid hardcoding words. | ||
* (Applies to [[Legacy Sheet]], not [[CSE]])'''Don't include''' <code>sheet-</code> '''for CSS Class names in the HTML'''. <code>sheet-</code> is automatically added to the CSS classes in the HTML, so it's redundant to repeat it there. Leaving it out also increases readability if lots of classes are used. | * (Applies to [[Legacy Sheet]], not [[CSE]])'''Don't include''' <code>sheet-</code> '''for CSS Class names in the HTML'''. <code>sheet-</code> is automatically added to the CSS classes in the HTML, so it's redundant to repeat it there. Leaving it out also increases readability if lots of classes are used. | ||
| Line 28: | Line 31: | ||
** '''WARNING:''' the above is untrue for classes of <code><rolltemplate></code> elements. For those, you do need to specify the full class name (i.e. starting with <code>sheet-</code>) or your rolltemplates will simply stop working. | ** '''WARNING:''' the above is untrue for classes of <code><rolltemplate></code> elements. For those, you do need to specify the full class name (i.e. starting with <code>sheet-</code>) or your rolltemplates will simply stop working. | ||
| − | * ''' | + | ===General=== |
| + | * '''Avoid using <code>!important</code> in CSS'''. Whenever possible try to avoid using <code>!important</code> in CSS as it can create a cascading effect of needing to use ever more <code>!important</code> to fix things. | ||
| − | * ''' | + | * '''Follow general HTML/CSS best practices'''. [https://google.github.io/styleguide/htmlcssguide.html Google's HTML/CSS Style Guide] is a good one to follow. Roll20's sheet framework is less forgiving than HTML/CSS in general, so following the style guide is a good way to avoid several minor pitfalls. |
| − | + | ||
| − | + | ||
<noinclude>==See Also== | <noinclude>==See Also== | ||
* [[Character Sheet Development/Restrictions]] | * [[Character Sheet Development/Restrictions]] | ||
* [[Character Sheet Development/Common Mistakes]] | * [[Character Sheet Development/Common Mistakes]] | ||
| + | |||
| + | [[Category:Character Sheet Creation]] | ||
| + | [[Category:Character Sheet Development]] | ||
</noinclude> | </noinclude> | ||
Latest revision as of 10:19, 8 May 2022
 | Page Updated: 2022-05-08 |
 | This is related to Editing(coding) Character Sheets, which require Pro info to be able to use.Main Page: Building Character Sheets |
Character Sheet Development
Getting Started
- Using Custom Sheets
- Building Sheets
(Main Page) - Glossary
- Code Restrictions
- Best Practice
- Common Mistakes
- Tutorials
- Examples, Templates
- Pattern Libraries
- HTML & storing data
- CSS & Styling
General
- Updates & Changelog
- Known Bugs
- Character Sheet Enhancement(CSE)
- Custom Roll Parsing
- Legacy Sheet(LCS)
- (upcoming) Beacon SDK
Reference
- Buttons
- Repeating Sections
- Sheetworkers
- Roll Templates
- sheet.json
- Translation
- Auto-Calc
- Advanced
- All SheetDev Pages
Tools & Tips
Git/GitHub 
Other
These are general best practice guidelines to help increase consistency among sheet authors, in order to make more maintainable code repository for the community. Some of these are generic, while others are specific to how the Roll20 Character Sheet Framework functions.
Contents |
[edit] Attributes/Inputs
- Attribute names should be lowercase. For the sake of consistency & to avoid some quirks related to sheetworkers, it's best to always give lowercase attribute names, such as
attr_strength,attr_strength_mod, which will then be called in macros and sheetworkers asstrength,strength_mod. It might be a good idea to limit them to alphanumerical +_and-.
- RPGs have weird words. Utilize
spellcheck="false"for text inputs and<textarea>, to prevent the browser from indicating spell errors.
- Use fewer Attributes & Inputs. The more attributes and inputs you have the slower the sheet will load. This is not a concern for the average sheet but robust sheets such as the D&D 5E Sheet by Roll20- or the Pathfinder (Community)-sheets large amount of attributes & inputs can lead to performance issues if left unmanaged. If sheetworkers need to process many attributes often, or the game relies on characters having many entires in Repeating Sections, it might impact performance.
- Spans over disabled inputs. Attribute-backed spans are more efficient than disabled inputs.
[edit] Sheetworkers & Roll Templates
- Avoid Asynchronous cascades. Whenever possible avoid asynchronous cascades for sheet workers. An example of this is,
getAttrs-> calculations ->setAttrs->getAttrs-> calculations ->setAttrs… A better way to do this isgetAttrsfor everything you'll need then do all necessarily calculations before finally using a singlesetAttrs.
- Use Sheetworkers over Auto Calculated attributes. Sheetworkers only trigger when events happen ,which improves performance for character sheets over auto calculated attributes since these events occur less frequently.
- Place Roll Templates and sheetworker code at bottom of the html page It's considered best practice to place JavaScript at end of pages. This also means the rolltemplates won't mess with the Preview Pane if you're using the Sheet Editor.
[edit] Other Roll20-specific
- Include a minimum width. Including a minimum width on the sheet will help with resizing. Try to not exceed the default width when a sheet opens for the first time, approximately 800px-900px. Character sheets with an NPC view may be smaller and elaborate PC sheets are sometimes bigger. Currently[May 2022]it's not possible to change the default width of the char sheet window, so if your sheet is much wider than the window, it might be annoying for users to have to resize them each time they are opened.
- Use Supported Fonts. Either use the five named fonts (
Arial,Patrick Hand,Contrail One,ShadowsInto Light, andCandal), or Google Fonts. Roll20 also comes with some Icon Fonts, and it's possible to us Google's Material Icons.
- Use
^{ }for translations in button macros. In your button macros using^{key}will insert the appropriate key from the appropriate language'stranslation.json. This makes roll templates more adaptable to other languages, and avoid hardcoding words.
- (Applies to Legacy Sheet, not CSE)Don't include
sheet-for CSS Class names in the HTML.sheet-is automatically added to the CSS classes in the HTML, so it's redundant to repeat it there. Leaving it out also increases readability if lots of classes are used.- For example in the HTML, instead of
class="sheet-strRow", just doclass="strRow". - WARNING: the above is untrue for classes of
<rolltemplate>elements. For those, you do need to specify the full class name (i.e. starting withsheet-) or your rolltemplates will simply stop working.
- For example in the HTML, instead of
[edit] General
- Avoid using
!importantin CSS. Whenever possible try to avoid using!importantin CSS as it can create a cascading effect of needing to use ever more!importantto fix things.
- Follow general HTML/CSS best practices. Google's HTML/CSS Style Guide is a good one to follow. Roll20's sheet framework is less forgiving than HTML/CSS in general, so following the style guide is a good way to avoid several minor pitfalls.
