Compendium for Publishers

The purpose of this document is to serve as an appendix to our Compendium documentation for Publishers. The following contains information specific to Publishers on the Roll20 marketplace.


Building Compendiums

As of December 1st, 2016, Roll20 has opened the ability for publishers and creators to build their own Compendiums for available OGL systems outside of D&D 5th Edition SRD and the Pathfinder SRD. These new Compendiums have all of the features of the original two Compendiums, including Character Sheet integration and drag and drop functionality. Publishers and creators will be working to help push content to our users and are expected to respect the rules of the site - any violation or vandalism of the Compendium will result in removal.

Editors should have a firm grasp of the rule system they would like to prepare and ideally have some familiarity with HTML, wiki writing, and/or authoring Structured Data. At this time, Structured data is discouraged as we are retooling our Compendium creation. Our update will update existing data structures however, so structured data compendiums may still be manually created.

If a database of structured data already exists for your project, please contact us through our web form for further information on data migration.


Building A Compendium Manually

Page Creation

Upon becoming a Creator/Publisher, you will be given access to a blank Compendium book to start editing and fill with content. During the process of creating the staging area for the book, you'll want to assemble a list of Categories needed for your game system (Rules, Monsters, Items, Spells, etc). You will want to have the organization structure straightened out before work on the Compendium begins.

Once you're given the URL for the new Compendium book by the Roll20 Team, you create new pages by tacking on the name of the new page at the end of the URL in the address bar and hitting Enter. (example: https://roll20.net/compendium/MyBook/Test Page) For special characters like spaces, parenthesis, and apostrophes: once you hit Enter, the page name will be adjusted to use HTML Code for the needed ASCII characters automatically.

NOTE: Please do not use colons ":" in page URLS. These are read as categories by the URL and will make your page unusable

Since the page does not yet exist, the Compendium will display a page that says:

Not Found: [page name]

We don't currently have a page that matches that name. Try again?

Or maybe you'd like to create this page?

Below this will be a drop down menu for the Category you wish to add the page to. If this is the very first page, you'll not have any available Category to choose from in the drop-down other than Miscellaneous to start with, so this is where you should start adding your own Categories.

NOTE: Pages created in Miscellaneous and BookIndex categories cannot be edited by anyone but a Roll20 developer. Please avoid these categories.

Once you've set or added a Category to the page, click on the blue Create Page button to create it. This will drop you onto the newly created page to start editing it.

Editing a Page

Once created, a Compendium page will be split up into two distinct parts: A Text Editor and then an Attributes Table underneath.

Text Editor

The text editor can switch between a WYSIWYG and an HTML version by clicking on the </> button which is the last button on the right side of the text editor's toolbar. Be sure to click the </> button after inputting your HTML to let the page update before saving. The text editor is where you include monster/class/race bios, feats, and abilities. Page content is readable outside of any created statblocks. Use heading tags (<h1>, <h2>, <h3>, Etc.) in a consistent manner to split your content up for efficient integration. It is incredibly important that text formatting is also kept consistent throughout the entirety of the Compendium book.

Uploading Images

Most editing can be done at the standard "roll20.net" web address. For uploading images, URLs must be edited on "app.roll20.net". Images can then be dragged into the appropriate area and will upload automatically. The Roll20 compendium automatically resizes and resamples images. If this is not desired, the HTML tag for each image needs to be edited.

Dynamic Linking

You do not need to manually create page links within the text copy of your Compendium pages. Page linking is done automatically after Roll20 initiates a Compendium build. This automated process scans through the text contents of every single entry of the Compendium to match strings up with any available page titles. When a match is found (the page name and string must be identical save for Capitalization), the string is automatically hyperlinked to the matched page. This process will happen when the Compendium is live.

Note: The autolinker can be gregarious. Take care in naming pages with a common phrase such as "Magic"

Creating List Pages

For large lists of relevant pages, many game systems may benefit from a searchable list.

  • Create a new page. For a naming convention, we suggest: <Category> List. Feats, Spells, Monsters, etc. pages should generally fall under the Lists category. Example: Spell List
  • Click on "Edit Attributes" and set "data-List" to {"searchTerms":[], "columns":[], "filters":[], "sortables":[]}. This attribute should already be created by default, but you may need to Edit/Save the contents of the page for it to appear.
  • Go to "Edit Content", set "List for Category" to the desired value, and add a new Search Attribute: Attribute = “Category”, Value = <Name of Category>, and Match = “Exact”. Be sure to save your edits.
  • Editing the list
    • "List Display Columns" - This controls what appears under each item column. This is not used if an item card has been defined for the category.
      • "Attribute" - The name of the attribute to be displayed.
      • "Order" - The order in which this attribute is displayed.
      • "Value Replacement" - A .json formatted string of key/value pairs for replacing certain values.
      • For example, {"0":"Cantrip"} makes 0 level spells display as "Cantrip" in the results list.
      • "Sortable" - This is deprecated. Sorting is now controlled in the "Sort Buttons" section
    • "Filter Attributes" - This controls the predefined filters available.
      • "Any" - Returns any result where the filter value matches any part of the attribute value.
      • "Exact" - Only returns results where the filter value matches the attribute value exactly.
      • "Inverse" - Only returns results where the filter value does not match the attribute value.
      • "Attribute" - The name of the attribute to be filtered by.
      • "Order" - The order in which this filter is displayed.
      • "Filter Type" - The type of input for the filter.
      • "Default Value" - The default value for the filter.
      • "Match" - How the filter returns the result.
      • "Filter input values" - For select and multiselect filter types, this is a .json formatted string which determines what values are available. If blank, it will populate the selection with all of the possible values.
    • "Sort Buttons" - For defining the sortable attributes.
      • "Alphabetical" - The results are sorted alphanumerically, with numbered results returning first. "19 ft." and “40 Winks” would be listed first before “Ale of Drunkening” and "Potion of Sobering", etc.
      • "Numerical" - The results are sorted numerically. The code will find the first numerical value and use that for sorting i.e. "Speed 30 ft. (15 ft. flying)" would then parse out as "30".
      • "Attribute" - The name of the attribute to be sorted by.
      • "Order" - The order in which this button is displayed.
      • "Display Title" - The text to be displayed in the button, if different from the attribute name.
      • "Type" - How the results are sorted.

 


Attributes Table

Below the Text Editor is the Attributes Table. This area is to input traditional statblock content that is consistent throughout your Categories: Armor Class, Languages, Weaknesses, Immunities, HP, XP, Passive Perception, etc., for Monsters. Weight, Item Type, Armor Class, Stealth rating for Items. Damage Type, Weight, Properties, Damage Die for Weapons. Commonly these Attributes are already broken down into a table within your rule book to carry it over into your Compendium entries.

Adding Attributes

When you're starting off with a new page, there will be no Attributes assigned to it. To start adding Attributes, click on the Edit Attributes link to the right of the Attributes heading. This will not only reveal hidden Attributes (if there are any), but also add a new link at the bottom of the Attributes Table labeled + Add New Attribute.

A drop down menu labeled Choose an attribute... will appear on a new table row. If you have created Attributes previously on other entries, those Attributes will appear as options on this drop down menu. The first option on the menu is Create new attribute... and likely will be what you'll be using mostly until you have all of your desired Attributes created.

Once selected, an empty field will appear to the right of the drop down menu and a smaller field directly below the drop down menu with the temporary text ,"New Attr Name", within it. As you might expect, the "New Attr Name" field is for the name of the Attribute you wish to create. The blank field on the right is the value the current entry has for this new Attribute. In the example image above, the attribute being created keeps track of an entry's "Element". I am assigning the Element for this entry the value of "Fire". An Attribute's value can be numerical or it could be a string.

Continue adding Attributes as you need in this fashion, either creating them from scratch or choosing from the drop down menu. When you are done, scroll up to the Attributes heading and where the Edit Attributes link used to be. While in Edit Mode, this link's label will change to Save Attributes. Clicking on this not only saves your changes, but it also logs any newly created Attributes so they can be brought up again on a new page.

Editing or Deleting Attributes

You can't delete Attributes until they're saved down first. Once saved, you can click on the Edit Attributes link again to return to Edit Mode. Any previously added/created Attributes will have a pen and trash can icon appear on the right side of the Attribute row when you hover your mouse over any one of them. Clicking on the pen icon will open the Attribute up once more so it can be edited, while the trash can icon will delete the Attribute. Remember to click on Save Attributes to exit out of Edit Mode and save your changes.


Compendium Integration

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 Compendium, players will have direct access to that Compendium in the right sidebar during gameplay.

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 sheet.json file of the 5th Edition OGL Sheet by Roll20 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.

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. See the Spells section in the 5th Edition OGL sheet for an advanced example of this process.

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.

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".


See Also

Was this article helpful?
3 out of 6 found this helpful