Stat Sheet: Difference between revisions

From RPTools Wiki
Jump to navigation Jump to search
m (Added link to @Rev's new tutorial)
m (Changed "source" to "pre" (source is deprecated))
 
(2 intermediate revisions by the same user not shown)
Line 1: Line 1:
{{Languages|Stat Sheet Customization}}
{{Languages|Stat Sheet Customization}}
{{Intermediate}}[[Category:Feature Guide]]
{{Intermediate}}[[Category:Feature Guide]][[Category:Tutorial]]
= Stat Sheet Customization =
= Stat Sheet Customization =
As of version 1.14.3, MapTool has support for using HTML5 and CSS3 to display the stat sheet.
As of version 1.14.3, MapTool has support for using HTML5 and CSS3 to display the stat sheet.
Line 30: Line 30:
Stat Sheets are added to MapTool via an [[Add-On Library]] which has the following structure (at minimum):
Stat Sheets are added to MapTool via an [[Add-On Library]] which has the following structure (at minimum):


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


=== Defining the Stat Sheet ===
=== Defining the Stat Sheet ===
Line 40: Line 40:
Individual stat sheets are defined in a file called {{code|stat_sheets.json}} within the Add-On.  Here's an example of the contents:
Individual stat sheets are defined in a file called {{code|stat_sheets.json}} within the Add-On.  Here's an example of the contents:


<source language="json">
<syntaxhighlight lang="json">
{
{
   "statSheets": [
   "statSheets": [
Line 51: Line 51:
   ]
   ]
}
}
</source>
</syntaxhighlight>


The {{code|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:
The {{code|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:
Line 63: Line 63:
Because our {{code|entry}} referred to a file named {{code|sheets/stats/basic/index.hbs}}, our final structure for the Add-on would be at the following:
Because our {{code|entry}} referred to a file named {{code|sheets/stats/basic/index.hbs}}, our final structure for the Add-on would be at the following:


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


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.
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.
Line 80: Line 80:
Stat Sheets must include this stat sheet CSS.  It defines various constants that MapTool makes available to the stat sheet:
Stat Sheets must include this stat sheet CSS.  It defines various constants that MapTool makes available to the stat sheet:


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


(See the discussion regarding [[Technical definition of Add-on Libraries#MTScript_macros|the technical definition of add-on libraries]] for information on the URI format used above.)
(See the discussion regarding [[Technical definition of Add-on Libraries#MTScript_macros|the technical definition of add-on libraries]] for information on the URI format used above.)
Line 91: Line 91:
The HTML content of the stat sheet must be inside a container element with {{code|id{{=}}"statSheet"}}, and which also has the class {{code|statSheetLocation}} (it can have other classes as well).  For example:
The HTML content of the stat sheet must be inside a container element with {{code|id{{=}}"statSheet"}}, and which also has the class {{code|statSheetLocation}} (it can have other classes as well).  For example:


<source language="html">
<syntaxhighlight lang="html">
<div id="statSheet" class="{{statSheetLocation}}">
<div id="statSheet" class="{{statSheetLocation}}">
   <!-- Stat Sheet contents go here -->
   <!-- Stat Sheet contents go here -->
</div>
</div>
</source>
</syntaxhighlight>


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 {{code|statSheetLocation}} class) as that is where the user wanted the stat sheet to be positioned.
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 {{code|statSheetLocation}} class) as that is where the user wanted the stat sheet to be positioned.
Line 129: Line 129:
Note: The {{code|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):
Note: The {{code|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):


<source language="handlebars">
<syntaxhighlight lang="handlebars">
<ul class="propertyList">
<ul class="propertyList">
   {{#each properties}}  
   {{#each properties}}  
Line 147: Line 147:
   {{/each}}
   {{/each}}
</ul>
</ul>
</source>
</syntaxhighlight>


=== CSS Variables ===
=== CSS Variables ===
Line 153: Line 153:
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).
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).


<source language="css">
<syntaxhighlight lang="css">
   --mt-theme-color-actions-blue: ...;
   --mt-theme-color-actions-blue: ...;
   --mt-theme-color-actions-blue-dark: ...;
   --mt-theme-color-actions-blue-dark: ...;
Line 191: Line 191:
   --mt-theme-color-button-pressed-background: ..;
   --mt-theme-color-button-pressed-background: ..;
   --mt-theme-color-button-background-hover: ..;
   --mt-theme-color-button-background-hover: ..;
</source>
</syntaxhighlight>


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

Latest revision as of 18:45, 22 March 2024

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.