Library Token
Introduced in MapTool version 1.3b46, the Library Token is a special token type that acts as a library of properties and trusted macros that may be accessed and called by other macros.
Note while Library Tokens will continue to function the way that they currently do from MapTool 1.11 onwards, they will not be getting a lot of the new features that add-on libraries will get, so it is recommended that framework developers transition to add-on libraries if supporting MapTool 1.11 and above. See: Add-On Library.
Library Token Naming
All library tokens must have a name in the format "Lib:name", to indicate that they are to serve as a Library Token and not a "normal" token. Example library token names might be:
- Lib:test
- Lib:combat
- Lib:gamemaster
Creating a Library Token
To create a Library Token, do the following:
- Drag a new token on to one of the maps in your campaign. The map does not need to be visible to players.
- Rename it with a name in the format Lib:name (e.g., Lib:DnD, Lib:GameRules, etc.).
- Right click on the token and make sure that Visible to Players is checked.
- Set the token type to NPC (upper right corner of the Token Configuration dialog).
After that, you have a Library Token. Note that you cannot have two library tokens with the same name in the same campaign (even if they're on different maps!).
Once again, the requirements are:
- The library token must be visible to players (make sure Visible to Players is set in the right-click context menu).
- The library token need not be on the "Token" layer (you can keep it on the "Hidden" layer to hide it from players, although "Visible to Players" must still be set to true).
- The library token must have a name in the format "Lib:name".
- The library token must be present on only one map in the campaign file.
Library Tokens and Trusted Macros
Library Tokens may run Trusted Macros or utilize trusted macro functions provided they meet one of the following criteria:
- The library token is not owned by any players, OR
- The macros on the library token are not player-editable.
If the Library Token does not meet at least one of those criteria, it cannot run trusted macros. This allows players to create their own personal library tokens for various untrusted macros they wish to run, while at the same time preventing players from altering or manipulating any token or other element of the campaign for which they do not have permission to do so.
Library Token Macros
Library token macros are created and edited like macros on any token. Macros on a library token may be called using the [MACRO(): ] roll option. Since Library token macros are trusted, they may perform operations not available to regular tokens.
Library Token Properties
Library token properties should be set and retrieved by using the setLibProperty() and getLibProperty() functions.
Note that getLibProperty() does NOT return default campaign property values, instead returning an empty string if the property is not set on the Library token. This is often useful for library tokens to prevent unintended errors that could be caused by unexpected default property values.
The 'libversion' property
The special 'libversion' property can be set on a library token to be output with getInfo("client"). The library token's name and the libversion will be a key/value pair in the nested "library tokens" object of the resulting getInfo() JSON object. The libversion property value will be displayed 'as-is'; any macro code in libversion will be displayed instead of processed.
To edit libversion, you can either add libversion to the Library Token's property list in the Campaign Preferences and then edit the token's properties directly, or set it via the chat panel or a macro using the setLibProperty() function.
When creating and improving upon a library token as a 'plugin' others use in their games, updating libversion with new releases is good practice. You may consider using Semantic Versioning to help give version numbers meaning for your users.
Library Token onCampaignLoad
Most users will find it worthwhile to add an onCampaignLoad macro to your Lib token that will use defineFunction() to make your Lib macros accessible like the built-in macro functions and recognized by the macro editor.
Library Token URI Access
As of version 1.10.0 the properties and macros on Lib:Tokens can be accessed via a URI from within MapTool. URI access can be enabled for a Lib:Token from the token edit dialog.
Once this has been enabled you will be able to access the macros and properties on the Lib:Token with
- lib://<token name>/macro/<macro name>
- lib://<token name>/property/<property name>
Where <token name> is the token after the lib: part, for example lib://myjs/macro/scripts/script1.js would point to the a macro named scripts/script1.js on the token lib:myjs.
These URIs can be used in the following places.
- script tags for including JavaScript in frame5/dialog5/overlay
- link tags for including CSS in frame5/frame/dialog5/dialog/overlay
- As an argument to the js.evalURI() macro function.
- As an argument to the html.dialog() / html.dialog5() macro functions.
- As an argument to the html.frame() / html.frame5() macro functions.
- As an argument to the html.overlay() macro function.
Note:
Since the WebView component does its own internal caching which cant be influenced by the usual methods in the JVM for turning off caching of certain URI a work around needed to be introduced. To ensure that JavaScript/css picks up the latest version the query string cachelib=false needs to be used and the code will do some finagling to ensure it turns into a URL that wont be cached for example
lib://Test/macro/test/test.js?cachelib=false