Stat Sheet: Difference between revisions
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): | ||
< | <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 | ||
</ | </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: | ||
< | <syntaxhighlight lang="json"> | ||
{ | { | ||
"statSheets": [ | "statSheets": [ | ||
Line 51: | Line 51: | ||
] | ] | ||
} | } | ||
</ | </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: | ||
< | <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" | ||
</ | </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: | ||
< | <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" | ||
/> | /> | ||
</ | </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: | ||
< | <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> | ||
</ | </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): | ||
< | <syntaxhighlight lang="handlebars"> | ||
<ul class="propertyList"> | <ul class="propertyList"> | ||
{{#each properties}} | {{#each properties}} | ||
Line 147: | Line 147: | ||
{{/each}} | {{/each}} | ||
</ul> | </ul> | ||
</ | </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). | ||
< | <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: ..; | ||
</ | </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 TokengmName
- The GM name of the Token (only if player is GM)label
- The label of the TokenportraitWidth
- 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 notesgmNotes
- The Token gmNotes (only if player is GM)speechName
- The Token speech bubble nametokenType
- The Token type, PC or NPCgm
- true if player is GM; otherwise, falsepropertyList
- The Token property list, which contains:
displayName
- The name of the propertyshortName
- The short name of the propertyvalue
- The value of the propertygmOnly
- 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):
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.