Roll20 Wiki

{{revdate}}{{NavMacroDocs}}
{{main|Macro Guide}}

'''[[HTML]] Entities''' (a.k.a. ''HTML Escape Characters'') can be useful to escape HTML characters so they aren't processed prematurely. This is useful in creating [[macros]], [[Building Character Sheets]], and [[Help:Contents|wiki editing]].

<onlyinclude>
When creating some complicated [[macros]], usually involving [[Nesting|nesting]], you will need to use [https://www.w3schools.com/html/html_entities.asp HTML entities] in parts of the code to trick the Roll20 system to make it behave like you want, or some advanced tricks won't work.

Here are some HTML Entities/Escape Characters that are commonly useful to escape when creating advanced Roll20 macros. See [https://www.freeformatter.com/html-entities.html HTML Entities] or [https://www.html.am/reference/html-special-characters.cfm special character] for more:
<div style="float:right">{{notebox| '''<code>&#124;</code>''', '''<code>&#125;</code>''', and '''<code>,</code>''' are the most common character that need to be replaced in nested macros.}}</div>
::{| class="wikitable"
|-
! Character || Replacement
|-
| <code>&#124;</code> (pipe) || <code>&amp;#124;</code>, (<code>&amp;vert;</code>)
|-
| <code>,</code>|| <code>&amp;#44;</code>, (<code>&amp;comma;</code>)
|-
| <code>&#123;</code>|| <code>&amp;#123;</code>, (<code>&amp;lbrace;</code>)
|-
| <code>&#125;</code>|| <code>&amp;#125;</code>, (<code>&amp;rbrace;</code>) 
|-
| <code>&</code> || <code>&amp;#38;</code>, (<code>&amp;amp;</code>)  
|-
| <code>space</code> || <code>&amp;#160;</code>, (<code>&amp;nbsp;</code>)
|-
| <code>=</code> || <code>&amp;#61;</code>, (<code>&amp;equals;</code>)
|-
| <code>_</code> || <code>&amp;#95;</code>, (<code>&amp;lowbar;</code>)
|-
| <code><nowiki>(</nowiki></code> || <code>&amp;#40;</code>, (<code>&amp;lpar;</code>)
|-
| <code><nowiki>)</nowiki></code> || <code>&amp;#41;</code>, (<code>&amp;rpar;</code>)
|-
| <code><nowiki>[</nowiki></code>  || <code>&amp;#91;</code>, (<code>&amp;lbrack;</code>)
|-
| <code><nowiki>]</nowiki></code>  || <code>&amp;#93;</code>, (<code>&amp;rbrack;</code>)
|-
| <code><nowiki><</nowiki></code> || <code>&amp;#60;</code>, (<code>&amp;lt;</code>) 
|-
| <code><nowiki>></nowiki></code> || <code>&amp;#62;</code>, (<code>&amp;gt;</code>) 
|-
| <code><nowiki>`</nowiki></code>(backtick, grave accent) || <code>&amp;#96;</code>, (<code>&amp;grave;</code>)
|-
| {{c|*}}(asterisk)|| <code>&amp;#42;</code>, (<code>&amp;ast;</code>)
|-
| {{c|!}} || <code>&amp;#33;</code>, (<code>&amp;excl;</code>)
|-
| {{c|"}}(doublequote)|| <code>&amp;#34;</code>, (<code>&amp;quot;</code>)
|-
| {{c|#}} || <code>&amp;#35;</code>, (<code>&amp;num;</code>)
|-
| {{c|-}}(hyphen) || <code>&amp;#45;</code>, (<code>&amp;dash;</code>)
|-
| {{c|@}} || <code>&amp;#64;</code>, (<code>&amp;commat;</code>)
|}
</onlyinclude>

==Examples==
{{main|Roll Queries & Nesting}} 

By using HTML entities to replace all <code>}</code> inside "Choose a Roll", it will now correctly process where the query ends. This is essentially to prevent the Roll Query from closing at the first <code>}</code> it encounters.
<pre>?{Choose a Roll|
  STR,/roll 1d20 + 3 + (?{Modifier&amp;#125;) |
  DEX,/roll 1d20 + 2 + (?{Modifier&amp;#125;) |
  CON,/roll 1d20 + 1 + (?{Modifier&amp;#125;) }
</pre>

If your query options contains <code>|</code>, you need to replace them to prevent the query thinking it's a delimiter between options.
<pre>
?{Pick a pair|Alice&#124;Bob|Bob&#124;Charlie}
</pre>

==Nested Query Improvement==
An fix for macros to not needing to use HTML Entities for nested macros was tried in 2021{{source|https://app.roll20.net/forum/permalink/10260308/}}, but it was seemingly shelved at some point. There might be new try with this as part of Jumpgate updates. [[User:1223200|1223200]] ([[User talk:1223200|talk]]) 11:40, 28 September 2024 (UTC)

[https://app.roll20.net/forum/permalink/10260308/ Now on Dev Server: Roll Query Improvements!] July 20th, 2021

Some, if not all, character substitutions might become redundant, when roll20 improves nested [[Dice Reference/Roll Query|Roll Query]] handling in macros.

:''Now on the [[Dev Server]]({{Pro}}-users) for testing, improved roll query parsing!''

:''Recently, an update to our character sheet code broke a workaround that some sheets were using to implement nested roll queries. Rather than fixing this workaround, we did a little extra work to properly support nested queries. Now, you should be able to nest roll queries inside of each other without needing to use any character codes.''

==Related==
* [[Roll Queries & Nesting]]
* [https://www.web2generators.com/html-based-tools/online-html-entities-encoder-and-decoder HTML Character Encoder/Decoder]
* [https://www.urlencoder.org/ URL encoding]
* [https://techstacker.com/how-to-escape-html/ How to Escape HTML Characters]

[[Category:Macros]]
[[Category:API]]
[[Category:Character Sheet Creation]]
[[Category:Wiki Editing]]