Character Vault
Any Concept / Any System
Compendium
Your System Come To Life
Roll20 for Android
Streamlined for your Tablet
Roll20 for iPad
Streamlined for your Tablet

Personal tools

Difference between revisions of "Compendium Integration"

From Roll20 Wiki

Jump to: navigation, search
m (See Also)
m (Enabling Drag-and-Drop Functionality for Your Sheet)
 
(10 intermediate revisions by one user not shown)
Line 1: Line 1:
''Main Article:'' '''[[Building Character Sheets]]'''
+
{{revdate}}{{BCS}} {{NavSheetDoc}}
  
The [https://app.roll20.net/compendium Roll20 Compendium] feature is a repository of information such as rules, spells, items, and monsters for select open-license gaming systems. By designating that your sheet is compatible with a Compendium, players will have direct access to that Compendium in the right sidebar during gameplay.
+
The [https://app.roll20.net/compendium Roll20 Compendium] feature is a repository of information such as rules, spells, items, and monsters for select open-license gaming systems. By designating that your sheet is compatible with a {{Compendium}}, players will have direct access to that Compendium in the right sidebar during gameplay.
  
 
==Designating Compatibility for Your Sheet==
 
==Designating Compatibility for Your Sheet==
  
To designate compatibility with a Compendium, just include the Compendium's short name in the "compendium" field of your <code>sheet.json</code> file. For an example, see the [https://github.com/Roll20/roll20-character-sheets/tree/master/DD5thEditionLegacy D&D 5E by Roll20] sheet.json file of the 5th Edition OGL Sheet by Roll20] on Github.
+
To designate compatibility with a Compendium, just include the Compendium's short name in the "compendium" field of your <code>[[sheet.json]]</code> file. For an example, see the [https://github.com/Roll20/roll20-character-sheets/tree/master/DD5thEditionLegacy D&D 5E by Roll20 sheet.json file] on Github.
  
  
 
If you are using a Custom sheet, there is a Setting on the Game Settings page that will allow you to manually select a Compendium to use for your game.
 
If you are using a Custom sheet, there is a Setting on the Game Settings page that will allow you to manually select a Compendium to use for your game.
  
==Enabling Drag-and-Drop Functionality for Your Sheet==
+
===Enabling Drag-and-Drop Functionality for Your Sheet===
  
In addition to basic compatibility, you have the option of telling Roll20 how information from the Compendium can be included on your sheet directly. This allows players to drag-and-drop an entry from the compendium directly into your sheet, and Roll20 will fill in the values you specify. To do so, you must add the class <code>compendium-drop-target</code> to the <code>div</code> tag surrounding the section you want to fill in. For repeating sections, place this inside of the <code>fieldset</code> tag. Then, add the <code>accept="Attribute Name"</code> attribute to one or more <code>input, select, textarea</code> tags. Here's a simple example which would be compatible with the [https://app.roll20.net/compendium/dnd5e/Fireball Fireball entry] from the 5th Edition SRD Compendium.
+
In addition to basic compatibility, you have the option of telling Roll20 how information from the Compendium can be included on your sheet directly. This allows players to drag-and-drop an entry from the compendium directly into your sheet, and Roll20 will fill in the values you specify. To do so, you must add the class <code>compendium-drop-target</code> to the <code>div</code> tag surrounding the section you want to fill in. For [[BCS/Repeating Sections|Repeating Sections]], place this inside of the <code>fieldset</code> tag. Then, add the <code>accept="Attribute Name"</code> attribute to one or more <code>input, select, textarea</code> tags. Here's a simple example which would be compatible with the [https://app.roll20.net/compendium/dnd5e/Fireball Fireball entry] from the 5th Edition SRD Compendium.
 +
 
 +
* [https://app.roll20.net/forum/permalink/11732373/ Helpful Compendium Integration Tip/Example] Dec 2023
  
 
<pre data-language="HTML">
 
<pre data-language="HTML">
Line 44: Line 46:
  
  
Note that the process of changing these values will trigger local Sheet Worker and remote API events exactly as if the user themselves had entered the data by hand. So you can also create hidden inputs to accept data from the Compendium and then process that data further using Sheet Workers if you want more control over how the data is presented. See the Spells section in the [https://github.com/Roll20/roll20-character-sheets/blob/050bf47f88757291bf52158c1bae69470ff05e0f/5th%20Edition%20OGL%20by%20Roll20/5th%20Edition%20OGL%20by%20Roll20.HTML#L1429 5th Edition OGL sheet] for an advanced example of this process.
+
Note that the process of changing these values will trigger local [[sheetworker|Sheet Worker]] and remote API events exactly as if the user themselves had entered the data by hand. So you can also create hidden inputs to accept data from the Compendium and then process that data further using Sheet Workers if you want more control over how the data is presented.
  
==Compendium Buttons==
+
===Compendium Buttons===
The compendium button can be used to open a compendium entry directly from a character sheet, in the same way as if you clicked on an entry in the in-app compendium. This can be used as a more convenient way to access rules and descriptions, for example, for a spell, the compendium button can be used to easily view the full description for that spell.
+
{{main|button}}
 +
 
 +
The compendium [[button]] can be used to open a compendium entry directly from a character sheet, in the same way as if you clicked on an entry in the in-app compendium. This can be used as a more convenient way to access rules and descriptions, for example, for a spell, the compendium button can be used to easily view the full description for that spell.
  
 
The syntax is <code><button type="compendium" value="<entryname>"></code>. Here are a few valid examples:
 
The syntax is <code><button type="compendium" value="<entryname>"></code>. Here are a few valid examples:
  
<pre data-language="javascript">
+
<pre data-language="html" style="margin-bottom: 5px">
 
<button type="compendium" value="Bard"></button>
 
<button type="compendium" value="Bard"></button>
 
</pre>
 
</pre>
Line 57: Line 61:
  
  
<pre data-language="javascript">
+
<pre data-language="html" style="margin-bottom: 5px">
 
<button type="compendium" value="Classes:Bard"></button>
 
<button type="compendium" value="Classes:Bard"></button>
 
</pre>
 
</pre>
Line 63: Line 67:
  
  
<pre data-language="javascript">
+
<pre data-language="html" style="margin-bottom: 5px">
 
<button type="compendium" value="Classes:Bard#Spellcasting"></button>
 
<button type="compendium" value="Classes:Bard#Spellcasting"></button>
 
</pre>
 
</pre>
Adding a "#" followed by a subhead title will cause the window to open directly to that section. This example will open the entry for the Bard class, pre-scrolled to the Spellcasting section. If no section with that name is found, the window will open scrolled to the top.
+
Adding a <code>#</code> followed by a subhead title will cause the window to open directly to that section. This example will open the entry for the Bard class, pre-scrolled to the Spellcasting section. If no section with that name is found, the window will open scrolled to the top.
  
  
 
Dragging an entry from the compendium contains an attribute specifically for this button, <code>uniqueName</code>, a string containing both the category and entry name, which ensures there will be only one match in the compendium. So, the syntax for this button in a compendium drop section is as follows:
 
Dragging an entry from the compendium contains an attribute specifically for this button, <code>uniqueName</code>, a string containing both the category and entry name, which ensures there will be only one match in the compendium. So, the syntax for this button in a compendium drop section is as follows:
  
<pre data-language="javascript">
+
<pre data-language="html" style="margin-bottom: 5px">
 
<button type="compendium" name="attr_infoButton" accept="uniqueName"></button>
 
<button type="compendium" name="attr_infoButton" accept="uniqueName"></button>
 
</pre>
 
</pre>
  
 
You can also add a sub-section to this attribute via sheetworker, so if the item dropped from the compendium was a monster, and you want the button to open directly to the "Actions" section, you can set the value of the button to <code>uniqueName + "#Actions"</code>.
 
You can also add a sub-section to this attribute via sheetworker, so if the item dropped from the compendium was a monster, and you want the button to open directly to the "Actions" section, you can set the value of the button to <code>uniqueName + "#Actions"</code>.
 +
 +
===Default Sheet Settings===
 +
{{main|Default Sheet Settings}}
 +
 +
If you have NPC drag-n-drop integration, it can be good idea to add Default Sheet Settings that enables users to change the positions and values of how NPC [[token]] are set up. This can't be applied to normal character sheets.
 +
 +
===Charactermancer Development===
 +
{{main|Charactermancer Development}}
 +
 +
To be able to create a [[Charactermancer]] for a sheet, the data used in them needs to be stored in a Compendium, so a sheet requires some form of compendium-integration, before a Charactermancer can be implemented.
  
 
=See Also=
 
=See Also=
* [[Compendium]] - How to handle Compendiums in general
 
 
* [[Building Character Sheets]] - Other aspects of creating Character Sheets
 
* [[Building Character Sheets]] - Other aspects of creating Character Sheets
 +
** [[sheet.json]]
 +
** [[Default Sheet Settings]]
 +
* {{Compendium}} - How to handle Compendiums in general
 
* [[D&D 5E by Roll20]] A sheet which have Compendium access integrated to it
 
* [[D&D 5E by Roll20]] A sheet which have Compendium access integrated to it
<br>
+
 
<br>
+
 
[[Category:Character Sheet Creation]]
 
[[Category:Character Sheet Creation]]
 +
[[Category:Character Sheet Development/Advanced]]
 +
[[Category:Sheetworker]]
 +
[[Category:Repeating Section]]

Latest revision as of 17:44, 21 December 2023


The Roll20 Compendium feature is a repository of information such as rules, spells, items, and monsters for select open-license gaming systems. By designating that your sheet is compatible with a i Compendium, players will have direct access to that Compendium in the right sidebar during gameplay.

Contents

[edit] Designating Compatibility for Your Sheet

To designate compatibility with a Compendium, just include the Compendium's short name in the "compendium" field of your sheet.json file. For an example, see the D&D 5E by Roll20 sheet.json file on Github.


If you are using a Custom sheet, there is a Setting on the Game Settings page that will allow you to manually select a Compendium to use for your game.

[edit] Enabling Drag-and-Drop Functionality for Your Sheet

In addition to basic compatibility, you have the option of telling Roll20 how information from the Compendium can be included on your sheet directly. This allows players to drag-and-drop an entry from the compendium directly into your sheet, and Roll20 will fill in the values you specify. To do so, you must add the class compendium-drop-target to the div tag surrounding the section you want to fill in. For Repeating Sections, place this inside of the fieldset tag. Then, add the accept="Attribute Name" attribute to one or more input, select, textarea tags. Here's a simple example which would be compatible with the Fireball entry from the 5th Edition SRD Compendium.


<fieldset class="repeating_spells">
  <div class="compendium-drop-target">
    <input type="text" name="attr_SpellName" accept="Name" />
    <input type="text" name="attr_SpellDamage" accept="Damage" />
    <select name="attr_SpellSchool" accept="School">
      <option value="Abjuration">Abjuration</option>
      <option value="Conjuration">Conjuration</option>
      <option value="Divination">Divination</option>
      <option value="Enchantment">Enchantment</option>
      <option value="Evocation">Evocation</option>
      <option value="Illusion">Illusion</option>
      <option value="Necromancy">Necromancy</option>
      <option value="Transmutation">Transmutation</option>
    </select>
    <input type="checkbox" name="attr_SpellRitual" value="Yes" accept="Ritual">
  </div>
</fieldset>

  • The <Attribute Name> in accept="<Attribute Name>" must match the name of an Attribute from the bottom section of the Compendium entry. Consult each individual Compendium for a listing of what Attributes are available.
  • For input and textarea tags, the value from the Compendium will be directly inserted.
  • For input[type=checkbox] and input[type=radio] tags, the box will be checked/radio selected if the value from the compendium exactly matches the value attribute from the tag.
  • For select tags, the option that matches the Compendium value in either the value attribute OR the text inside the option tag will be selected
  • You can use accept="Content" if you wish to receive the plaintext content from the entry (the content located above the "Attributes" header).
  • You can use accept="data" of you want to receive all attributes from a compendium page in a json format.


Note that the process of changing these values will trigger local Sheet Worker and remote API events exactly as if the user themselves had entered the data by hand. So you can also create hidden inputs to accept data from the Compendium and then process that data further using Sheet Workers if you want more control over how the data is presented.

[edit] Compendium Buttons

Main Page: button

The compendium button can be used to open a compendium entry directly from a character sheet, in the same way as if you clicked on an entry in the in-app compendium. This can be used as a more convenient way to access rules and descriptions, for example, for a spell, the compendium button can be used to easily view the full description for that spell.

The syntax is <button type="compendium" value="<entryname>">. Here are a few valid examples:

<button type="compendium" value="Bard"></button>

This is valid syntax, but since there is both a Class and a Monster compendium entry titled "Bard", the resulting window will be present you with a choice of entries rather than going directly to one of them.


<button type="compendium" value="Classes:Bard"></button>

This is the preferred syntax. Specifying the category ensures that there will be only one match.


<button type="compendium" value="Classes:Bard#Spellcasting"></button>

Adding a # followed by a subhead title will cause the window to open directly to that section. This example will open the entry for the Bard class, pre-scrolled to the Spellcasting section. If no section with that name is found, the window will open scrolled to the top.


Dragging an entry from the compendium contains an attribute specifically for this button, uniqueName, a string containing both the category and entry name, which ensures there will be only one match in the compendium. So, the syntax for this button in a compendium drop section is as follows:

<button type="compendium" name="attr_infoButton" accept="uniqueName"></button>

You can also add a sub-section to this attribute via sheetworker, so if the item dropped from the compendium was a monster, and you want the button to open directly to the "Actions" section, you can set the value of the button to uniqueName + "#Actions".

[edit] Default Sheet Settings

Main Page: Default Sheet Settings

If you have NPC drag-n-drop integration, it can be good idea to add Default Sheet Settings that enables users to change the positions and values of how NPC token are set up. This can't be applied to normal character sheets.

[edit] Charactermancer Development

Main Page: Charactermancer Development

To be able to create a Charactermancer for a sheet, the data used in them needs to be stored in a Compendium, so a sheet requires some form of compendium-integration, before a Charactermancer can be implemented.

[edit] See Also