A Sheet Worker Reprise

Since the sheet worker series has been a long one (sooo long), this post covers the main things you need to know, and the main pitfalls to avoid.

Test Your Sheet On Roll20

Many people come to the Roll20 Forums puzzled why their code isn’t working when it worked fine on another site. But roll20 is a custom build, and code made for other sites frequently doesn’t work here. If you want to be sure your code works, you must test it on Roll20.

The Script Block

You need to create a script block in the html file. This can be placed anywhere in the file, but for efficiency is best placed at the end.

You can theoretically have multiple script blocks, each containing its own sheet workers. All will run. But there was a Roll20 bug once that caused all script blocks after the first to be ignored. While that has been removed, it’s still a good idea to have just one script block. Workers in one block don’t know about others, so cannot call on functions in another script block.

The script block looks like this:

<script type="text/worker">
/* all your functions and workers go here */


</script>Code language: JavaScript (javascript)

Anatomy of A Sheet Worker

A sheet worker is broken up into several sections, many of which look basically the same.

on('change:stat', () => // this is the event line
   getAttrs(['stat'], values => {

      /* this is the body of the worker */

      setAttrs({
         new_stat: stat_value
      });
   });
});Code language: JavaScript (javascript)

This is a decent template of a sheet worker. Many will look like this.

Common Pitfalls

• The event line must be entirely lower-vase.
• Use the same rules for HTML attribute names and variable names
• Remember that = sets a value, while == or === compare values. They are not the same.
• There are three sets of quotation marks: ‘, “, and `. The last type are called backticks, and are very useful in template literals.
• Some functions in Roll20 are asynchronous. These functions are relatively slow, and you should avoid unneccesary duplication. These functions include getAttrs and setAttrs.
• Asynchronous functions must be nested inside each other, not listed one after the other.
• Roll20 stores all attribute values as strings, but unpredictable things can occur if you try to do comparisons or arithmetic with strings. So if you want to treat an attribute as anything other than a string, it’s a good idea to coerce that string into something else.
• Buttons each need a unique name, to work with macros or to drag them on the user’s macro bar. If you forget to include the name, the button still works but loses some functionality.
• html, css, and js each allow different rules for comments. Use <!– –> for html, /* */ for CSS, and either // or /* */ for JavaScript.
• Use your own syntax for coding, and stick to it. This makes your code easier to read. For example, I indent when code is nested, and end every appropriate line with a ;. This isn’t necessary – the code will work anyway, but it makes it easier for a human to read the code.

There are likely many more possible pitfalls and conventions to observe than listed here. i might add to the post in time.

Series Navigation

<< Strings in Sheet Workers