Revision as of 12:46, 26 February 2019

While the majority of Roll20's character sheets are written using only HTML and CSS, sheetworker scripts(javascript) are often necessary to either simplify complicated HTML or add more advanced functionality to a character sheet. For those of us "non-programmers", the examples given on the Sheet Worker Scripts page may be less than exhaustive. This page was created to help better explain how to use sheetworker scripts in your character sheets.

This page may or may not contain specific examples of sheet worker code, however the information provided is invaluable to learning how to implement sheet workers into your character sheet.

Understanding sheet workers.

(credit: Jakob)

Usually, the best way to learn something is to do it! Start solving the problems you want to solve using sheet workers, and learn along the way :).

Now, that probably wasn't very helpful. I could also encourage you to look at code others have written, which you should do; just realize that many sheet authors are also amateurs (such as me), hence the code may not be the most elegantly-written example.

That probably also wasn't helpful. Let me try something else: depending on what your course taught you, much of it (everything dealing with manipulation of the DOM) is not going to be very helpful. Here's some important things you need to keep in mind that might make sheet workers different from what you've learned:

1. Sheet workers are event-driven. Everything interesting your workers do will happen in response to a certain event on the sheet; most of the time, the triggering event will be changing an attribute on the sheet (i.e., the value of some input, be it a checkbox, radio, text, number input, or textarea). This is what the on("change:attr", function () { ...}) is there for: it's about registering a function that's supposed to be executed every time attr changes.

2. Sheet workers can only really do one thing. Sheet workers can change the value of attributes, and that's pretty much it (they can also remove repeating rows, but that's not their main use). If you want your sheet workers to do a thing, ask yourself if it can be accomplished by changing the value of an attribute (this includes being able to (un)check checkboxes), +perhaps some CSS. If yes, you can do it with sheet workers. If not, you cannot.

3. Sheet workers are asynchronous. The main interesting functions you have access to in sheet workers, namely getAttrs, setAttrs, and getSectionIDs, take as their second argument functions that do other stuff. This means that you cannot trust that your code will simply be executed from top to bottom, and have to write in such a way that it makes sense no matter when asynchronous functions are executed. This is often a source of confusion for people.

Good Practices

(credit: GiGs)

• I think it's a good idea (especially when still learning) to get into the habit of putting all the values you are using in variables at the top of the code. It makes writing the code a bit more laborious, but if you reuse values, or have long macros, it can make things clearer, and most importantly, you can then use console.log statements to check what their values are. (they will appear in the browser's dev console, which you can usually find by pressing f12).

• Another tip is its a good idea to just use a single setAttrs statement, at the end of the sheet worker. For this one which is just modifying a single attribute, it doesn't matter, but you'll eventually get into making workers that set multiple attributes. when that happens, you definitely want to group them into a single statement, to avoid unpredictable errors.

• Also its a good idea to use variable names that match the value they are calling. In the code below, for example, i renamed index to currenthp, which I think is more descriptive.

• It's also a good idea to use lower case only for attribute names, and use underscores instead of dashes or otehr symbols in the name. For example, avoid strength-mod, use strengthmod or strength_mod instead.

• One final tip: if you are using parseInt on cells that users can enter values into, it's a good idea to add a default value. For instance parseInt('something')|||0 means that if the cell contains text, or not a number, you'll get a number in the code. Your if statements will fail without this, if the cells being called don't actually have numbers in them.

Autocalc Fields and Sheet Workers

(credit: GiGs) A common pitfall is to try to combine autocalc fields and sheet workers. Try not to do this.

First, autocalc fields need to be set as disabled, and sheet workers cannot edit a disabled input. If you want to use a sheetworker to create a value that is displayed but cant be edited, set the input to readonly. this looks the same as disabled, and cant be edited, but sheetworkers can update it.

Second, don't try to grab autocalc fields in a sheet worker. The getAttrs function in a sheet worker will grab the text of an autocalc field, not the number it resolves to. If the attribute is something like "[[@{STR} + @{DEX}]]" then getAttrs will give you a value of "[@{STR} + @{DEX}]]" and not 23 or 30 or whatever number you are expecting.

So, you need to recreate that formula in the sheet worker anyway, by using getAttrs to grab STR and DEX values, and then adding them together within the worker. Alternatively, replace the initial autocalc field with a sheet worker.

Because of these two facts, once you start using sheet workers, you tend to abandon autocalc fields. They dont interact well. You can still use autocalcs for standalone attributes that dont affect anything else, but sheet workers for everything else.

See Also

• Sheet Worker Snippets
• Universal Sheet Workers
• The RepeatingSum Function
• How to integrate table of stats into a sheet