In this post, you’ll find a brief overview of Repeating Sections, covering all the basics. In the next few posts, we’ll look at gotchas and advanced uses, but if you aren’t too demanding, this post will be everything you need.
What Is A Repeating Section
Imagine your players have an equipment list, or a list of spells or attacks. They can add things to that list or remove them. They are dynamic. This is where repeating sections come in.
You can build a section with a fixed number of rows and columns, but then you have to guess how many the players need, and if they need more than you have provided the sheet can never satisfy them.
This is where repeating sections shine, and the clue is in the name. You create one section of html – all the inputs, spans, dropdown lists, buttons and so on that are needed for one section. Then whenever a player clicks the Add button, that entire section is copied, creating a new section. It repeats.
You never need to declare a limit – the sheet starts with no sections, but will create as many as the player creates. You can also delete a section, and even change their order. In this way, the section is dynamic.
Building a Repeating Section
A repeating section is madeup of HTML elements, and is built exactly like any other part of the sheet. The only special thing is that the elements are included inside a fieldset, like this:
<fieldset class="repeating_example">
<label>A checkbox</label>
<input type="checkbox" name="attr_clickme" value="1">
</fieldset>Code language: HTML, XML (xml)An empty repeating section looks like this:
<fieldset class="repeating_NAME">
<!-- elements go here -->
</fieldset>Code language: HTML, XML (xml)The fieldset element creates a repeating section, and must be given a classname that always starts with repeating_.
One Very Important Gotcha
Repeating section names must never include a second underscore. The name repeating_spell_list is a no-no. These are fine: repeating_spell-list, repeating_spellList, or repeating_spelllist.
On the character sheet, an empty Repeating Section might look like:
Notice the Add and Modify buttons. The sheet creates them automatically – you don’t have to worry about that. Modify allows you to delete or rearrange sections.
Names in a Repeating Section
Let’s say you create a simple repeating section for spells, and your section records just the spell name and the spell level.
<fieldset class="repeating_spells">
<span>Name:</span>
<input type="text" name="attr_name" placeholder="Enter name">
<span>Level:</span>
<input type="number" name="attr_level" placeholder="Enter level">
</fieldset>Code language: HTML, XML (xml)Now, the player creates a macro to print out the name of the spell. Anywhere else on the sheet, they could use @{name}. But there’s a problem here. There could be 1 section, or 20. How does the character sheet know which version of the @{name} attribute to use?
To solve this problem, attributes in a repeating section are made up of three parts:
- Repeating Section Name: the sheet needs to know which repeating section to use.
- Row Id: a special id is created for each section (each section is often called a row). This is how the sheet knows which row to use. An ID follows the Roll20 UUID format, so it looks like a random string of numbers and letters that starts with a dash – something like -ghet6gyiy87a. It is so complicated to make sure no UUID is ever repeated – you wont accidentally get the same row id twice in the same section. You rarely need to worry about the row ID – its only used in sheet workers.
- Field name: the actual attribute name, like name or level.
Each part is separated with an underscore, so a full attribute name might be repeating_spells_-ghet6gyiy87a_name.
Shorthand Names
Whenever trying to use the attribute, you must use the full repeating section attribute name. But those row ids make the names pretty cumbersome, so in macros you can use a shorthand.
Replace the row id with $0, $1, $2, etc. This is an index that starts at $0 for the first row, and increases by one for each extra row.
Let’s say you create a simple repeating section for attacks:
<fieldset class="repeating_attacks">
<span>Name:</span>
<input type="text" name="attr_macro" value="1d20+5">
<button type="roll" name="roll_attack" value="@{macro}"></button>
</fieldset>Code language: HTML, XML (xml)This lets people enter an attack macro in the input, and click the button to attack with it. You could then create a macro with this text:
/roll @{repeating_attacks_$0_attack}Code language: Markdown (markdown)The full name is still cumbersome, but it’s more convenient than trying to figure out the row id.
These shorthand names refer to a specific position in the repeating section. The above macro always points to the first item. If you reorder items, changing say the 1st item to the 3rd position, it isn’t triggered by the same macro any more. This is something to be careful of.
The full attribute name is not needed within a row
See @{macro) in the above example. That would be @{repeating_attacks_ROWID_macro} if called anywhere else in the sheet. But if you are referring to an attribute on the same row within a repeating section, you can just use the field name.
Styling Your Repeating Section
You style the appearance of a repeating section exactly like any other part of the sheet using CSS. You can give classes to elements inside the section, and then apply CSS to those.
I often create a container inside the repeating section, and if there is styling I want to apply to a whole section, I can target that div. If I want styling to surround the fieldset (like borders), putting it inside a div makes this easy.
<div class="border">
<fieldset class="repeating_example">
<div class="this-is-for-easy-styling">
<label>A checkbox</label>
<input type="checkbox" name="attr_clickme" value="1">
</div>
</fieldset>
</div>Code language: HTML, XML (xml)You can target the fieldset directly, but that is a bit more complicated and is handled in a later post.
Repeating Sections and Sheet Workers
This is where things get complicated. Because it’s so much more complicated, sheet workers will have their own post (more than one, actiually).
Conclusion
Repeating Sections are incredibly useful, and most sheets will not be complete without one or more of them. They are great for adding dynamic content, at the cost of cumbersome macro names. Think of a repeating section this way: the HTML is a template, a set of instructions to the sheet to add these items to the sheet every time the player clicks the add button.
