Stat Sheet

Languages:  English

INTERMEDIATE
THIS IS AN INTERMEDIATE ARTICLE

Stat Sheet Customization

As of version 1.14.3, MapTool has support for using HTML5 and CSS3 to display the stat sheet.

In essence, this means that any HTML content that you can dream up can appear when a token receives the onMouseOver event, ie. when the user hovers over a token on the Token layer.

The original documentation and a simple stat sheet (used for testing) can be found in this GitHub repo. That documentation and example are recreated here with additional notes.

The stat sheets that come with 1.14.3 (that were provided by @Reverend, on Discord) can be found in this GitHub repo, if you want more examples showing advanced techniques. You can also review @Reverends tutorial on creating custom stat sheets.

If you have a custom stat sheet that you think others might find useful and you want to share, you may either attach them to this article of the wiki, or contact @Craig on Discord to have them added to one of the two above GitHub repos.

Overview of Stat Sheets

One of the first features of MapTool (circa 2006) was the ability to hover over a token to see the properties of that token. For a long time, it was very simple: no HTML content inside the property names or values was interpreted, and the stat sheet was always displayed.

One of the early enhancements was holding down the Shift key to prevent the stat sheet from appearing while hovering. Later, a Preferences setting was added so that the stat sheet could be turned off by default and the Shift key used to turn it back on.

But HTML was never allowed for controlling the visual look. This is partly a limitation of Java Swing and partly due to the nature of how the stat sheet was displayed. But that changed with JavaFX — now the stat sheet could use full HTML5 and CSS3 (including JavaScript, if desired) to produce an HTML snippet that MapTool would then display on demand.

The stat sheet has access to most of the data available that is part of the token: name (and GM name), label, properties, and so on. See below for details.

Simple Example MapTool Stat Sheet Add-On

Here is a really simple example of how to create a MapTool Stat Sheet.

Add-On

Stat Sheets are added to MapTool via an Add-On Library which has the following structure (at minimum):

library.json                  <-- File that provides the Add-On details
library/                      <-- Directory that contains the Add-On contents  
stat_sheets.json              <-- File that defines the stat sheets

Defining the Stat Sheet

Individual stat sheets are defined in a file called stat_sheets.json within the Add-On. Here's an example of the contents:

{
  "statSheets": [
    { 
        "name": "Basic",
        "description": "Basic Stat Sheet",
        "propertyTypes": [ "Basic" ],
        "entry": "sheets/stats/basic/index.hbs" 
    }
  ]
}

The statSheets property of the JSON should contain a list of stat sheet definition blocks, each of which is a JSON Object. There must be four fields in the Object:

• name - a unique name to identify the stat sheet.
• description - A one-line description of the stat sheet.
• propertyTypes - Which token property types may use this stat sheet (token property types are defined in the Campaign Properties). An empty JSON Array indicates all token property types may use this stat sheet. In general, stat sheets that are independent of a specific framework should likely have an empty array.
• entry - the filename within the Add-On that contains the HTML for the stat sheet. (This is actually a Handlebars template file which is processed into HTML. See below.)

As the statSheets field is an array, you can define multiple stat sheets in the same Add-On.

Because our entry referred to a file named sheets/stats/basic/index.hbs, our final structure for the Add-on would be at the following:

library.json                  <-- File that provides the Add-On details
library/                      <-- Directory that contains the Add-On contents  
stat_sheets.json              <-- File that defines the stat sheets
sheets/stats/basic/index.hbs  <-- File referenced by "stat_sheets.json"

Note that the directory used to contain the handlebars template is arbitrary. You can create any logical organization of files and directories that you like, as long as they are referenced by the correct name elsewhere in your Add-on.

Creating the Stat Sheet

Use a Handlebars Template

A Handlebars template is used to create the HTML which is displayed as the stat sheet. See the Handlebars Guide for more information about the template syntax.

Stat Sheets must include this stat sheet CSS. It defines various constants that MapTool makes available to the stat sheet:

<link
  rel="stylesheet"
  href="lib://net.rptools.maptool/css/mt-stat-sheet.css?cachelib=false"
/>

(See the discussion regarding the technical definition of add-on libraries for information on the URI format used above.)

The HTML content of the stat sheet must be inside a container element with id="statSheet", and which also has the class statSheetLocation (it can have other classes as well). For example:

<div id="statSheet" class="{{statSheetLocation}}">
  <!-- Stat Sheet contents go here -->
</div>

Doing these two things will allow MapTool to correctly size and position your stat sheet as well as set the colours, fonts, etc, to match the current theme. If you are going for a custom look, you can override the colours, fonts, etc, but you should respect the positioning (the statSheetLocation class) as that is where the user wanted the stat sheet to be positioned.

Values that MapTool will predefine

The following values will be predefined for the handlebars template to use when creating the stat sheet:

• name - the name of the Token
• gmName - The GM name of the Token (only if player is GM)
• label - The label of the Token
• portraitWidth - The width of the portrait, e.g. 175px. This value is derived by the preference settings of the user, so should be respected.
• portraitHeight - The height of the portrait, e.g. 150px. This value is derived by the preference settings of the user, so should be respected.
• statSheetLocation - The location of the stat sheet. This is the class that must be added to the container. It can also be used to make your stat sheet react to its position on the Map View. Valid values are:

• statSheet-topLeft
• statSheet-top
• statSheet-topRight
• statSheet-right
• statSheet-bottomRight
• statSheet-bottom
• statSheet-bottomLeft
• statSheet-left

• notes - The Token notes
• gmNotes - The Token gmNotes (only if player is GM)
• speechName - The Token speech bubble name
• tokenType - The Token type, PC or NPC
• gm - true if player is GM; otherwise, false
• propertyList - The Token property list, which contains:

• displayName - The name of the property
• shortName - The short name of the property
• value - The value of the property
• gmOnly - true if property is marked as gm only in the property dialog

Note: The propertyList respects the settings of the token property type in the campaign settings. Only the values that the GM has denoted as appearing on the stat sheet will be in this list, and only if they meet the requirements such as owner or GM. This allows the user to still define what they want on the stat sheet. A handlebars template like the following can be used to display a dynamic properties list (although this is by no means the only way to do so):

<ul class="propertyList">
  {{#each properties}} 
    {{#if this.gmOnly}}
      {{#if this.shortName}}
        <li class="gmProperty">{{this.displayName}}({{this.shortName}}): {{this.value}}</li>
      {{else}}
        <li class="gmProperty">{{this.displayName}}: {{this.value}}</li>
      {{/if}}
    {{else}}
      {{#if this.shortName}}
        <li class="playerProperty">{{this.displayName}}({{this.shortName}}): {{this.value}}</li>
      {{else}}
        <li class="playerProperty">{{this.displayName}}: {{this.value}}</li>
      {{/if}}
    {{/if}} 
  {{/each}}
</ul>

CSS Variables

Including the MapTool-provided stat sheet CSS will make the following variables available to your CSS (assuming you include the MapTool stat sheet CSS before you include yours).

  --mt-theme-color-actions-blue: ...;
  --mt-theme-color-actions-blue-dark: ...;
  --mt-theme-color-actions-green: ...;
  --mt-theme-color-actions-green-dark: ...;
  --mt-theme-color-actions-grey: ...;
  --mt-theme-color-actions-grey-dark: ...;
  --mt-theme-color-actions-grey-inline: ...;
  --mt-theme-color-actions-grey-inline-dark: ...;
  --mt-theme-color-actions-red: ...;
  --mt-theme-color-actions-red-dark: ..;
  --mt-theme-color-actions-yellow: ..;
  --mt-theme-color-actions-yellow-dark: ..;
  --mt-theme-color-objects-black-text: ..;
  --mt-theme-color-objects-blue: ..;
  --mt-theme-color-objects-green: ..;
  --mt-theme-color-objects-green-android: ..;
  --mt-theme-color-objects-grey: ..;
  --mt-theme-color-objects-pink: ..;
  --mt-theme-color-objects-red: ..;
  --mt-theme-color-objects-red-status: ..;
  --mt-theme-color-objects-yellow: ..;
  --mt-theme-color-objects-yellow-dark: ..;

  --mt-theme-font-size: ..;
  --mt-theme-font-family: ..;

  --mt-theme-color-foreground: ..;
  --mt-theme-color-background: ..;
  --mt-theme-color-foreground-disabled: ..;

  --mt-theme-color-button-start-background: ..;
  --mt-theme-color-button-end-background: ..;
  --mt-theme-color-button-foreground: ..;
  --mt-theme-color-button-background-disabled: ..;
  --mt-theme-color-button-foreground-disabled: ..;
  --mt-theme-color-button-pressed-background: ..;
  --mt-theme-color-button-background-hover: ..;

These values can be used to make your stat elements match the current selected theme in MapTool by referencing them inside CSS rules via var(--mt-theme-font-size), for example.