When you use an attribute name in a macro, it;s easy – just oput the name inside @{ }. Say you are adding the strength_mod attribute, that will look like +@{attack_mod}.
It’s not always quite that straightforward. If you are looking at the character sheet code, you’ll see attr_attack_mod. Realise that the the attr_ part is not part of the attribute name – its a prefix that tells Roll20 this is an attribute. It must exist on all attributes.
So there we have two different syntaxes for the same attribute. Now imagine attack_mod is inside a repeating section. How do we create a macro for it? The complication here is that a repeating section can contain any number of rows – it might have 1, 10, or a 100. (It might also have zero, but that’s a different problem we won’t discuss here.)
So, how do we know when we want to use attack_mod we are using the correct attack_mod? There might be a dozen different attributes of that name!
Repeating Section names are built differently, because of this issue. They are clunky, but when you use the correct name, you always get the right name. We will now examine how.
Names in a Repeating Section
Attributes in a repeating section are made up of three parts:
- Repeating Section Name: the sheet needs to know which repeating section to use. Repeating section names always start with repeating_ and are typically followed by a single word, like spells, so repeating_spells.
- 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 this 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, or, indeed, attack_mod.
Each part is separated with an underscore, so a full attribute name might be repeating_spells_-ghet6gyiy87a_attack_mod. See the three sections which make up the full name?
Shorthand Names
Those names can be very clunky, especially the Row ID. So when creating macros, roll20 allows you to use a shorthand name. You can use a row number, instead of row id.
Replace the row id with $0, $1, $2, etc. This uses programming numbering, so the first item is 0, the second item is 1, and so on. It addresses the actual visible row of the repeating section.
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 %{selected|repeating_attacks_$0_attack}Code language: Markdown (markdown)This would activate the button on the 1st row of the repeating_attacks section, named attack. 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.
Repeating Section Name Gotchas
When creating or using repeating sections there are a couple of things to be careful of. This part is directed more ti sheet authors than users.
Single Word Names
When naming your repeating section, you must not use a second underscore.
You can’t create a repeating section called repeating_spells_known. That second underscore will break the section, it will never be recognised.
You can use other legal characters, so you could name a section repeating_spells-known. But it’s better to just use a single word after the repeating_, so repeating_spells is a better name. Re[eating section names are already long and unwieldy – try to avoid making them even more so!
Abilities as Macros
This was used as an example:
/roll %{selected|repeating_attacks_$0_attack}Code language: Markdown (markdown)When calling a button in a repeating section, you must always supply a character identifier. This can be a specific charecter name, or something like selected (allowing you to pick a character on demand).
This applies even if you create the call in the Abiolities section on a character sheet. For attributes, you don’t need to include a name there – roll20 automatically supplies it. But for buttons created in the sheet code, this isn’t true. You must always supply the attribute name.
The full attribute name is not needed within a row
In direct contradiction of the last point, when coding a character sheet, you don’t need to supply the character name if you are working in the same row of a repeating section. You don’t even need to supply the repeating section name, either. Say you have HTML like this:
<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)See how the button calls @{macro}? Its referring to the macro in the same repeating section, and so the character name, repeating section name, and row ID are all supplied by Roll20. You can ignore them.
This is only useful to sheet authors. When calling the attack macro from anywhere else, you still need to supply a character identifier, the repeating section and a row number or id. So that might look like:
/roll %{selected|repeating_attacks_$0_attack}Code language: Markdown (markdown)You can understand thuis simply: if the attribute or ability is being called within a context, roll20 supplies the details. But if called generally, where Roll20 might have to guess any of the row id, repeating section, or character, you have to supply those things.
Conclusion
So that’s repeating section names, a topic important and complex enough to need its own post. In the next post we’ll look at how to build a repeating section – its HTML. And the post after that, we’ll look at styling the section (its CSS), and most of the rest of the posts will be everything you need to know to automate a repeating section – the sheet worker side of it.
