Introduction to Add-on libraries: Difference between revisions

Latest revision as of 01:09, 15 February 2024

BEGINNER
THIS IS A BEGINNER ARTICLE

What Is An Add-on Library?

An Add-on Library is an extension to MapTool that may contain code, images or more. These were introduced in MapTool 1.11, and are intended to be a replacement for Library Tokens that are easier to work with while offering more functionality.

Add-on libraries are generally distributed as .mtlib files, which are just renamed .zip file with a specific structure.

Add-on Libraries are added to a campaign and are saved as part of the campaign file.

When the setLibProperty() function is called on an add-on, the property name and value are stored in a campaign area. That area is NOT cleared when the add-on is removed. This allows the data to persist across add-on updates. (Currently (as of v1.14.3), there are no corresponding functions to clear this data, so the only way to erase it is to create a new campaign.)

Managing the Add-On Libraries for Your Campaign

The dialog to manage the add-on libraries for your campaign can be reached using the File > Add On Libraries... menu option.

This dialog can be used to add or remove add-on libraries, view the details of all add-ons in the campaign and view their license/read me files.

As of MapTool 1.12, add-on libraries can be dragged and dropped onto the map from your system's file explorer. This will either add the add-on library to the campaign or replace it if it is already in the campaign.

Things still to be addressed

There is only minimal checking of data when importing add-ons so error reporting is not great.
Expanding the JavaScript API which will make this much more useful (part of another change set).
Better replacement for user defined functions.
Providing an equivalent to Library Tokens buttons.
Ability to check URL for later version and update from that (most likely GitHub to start with)
Link maps to required add-ons when exporting/importing.
Documentation / procedures for creating a GitHub release for your add-on.
The data store could be slightly smarter about large text blocks that remain static and attempt to cache them.

Return to: Add-On Library

@@ Line 1: / Line 1: @@
-{{stub}}
+{{Beginner}}
 [[Category:Tutorial]]
-[[Category:Beginner]]
 == What Is An Add-on Library? ==
-An Add-on library is an extension to Maptool that may contain code, images or more. they generally are distributed as .mtlib files, but they actually are just a zip file with a specific structure.
+An Add-on Library is an extension to MapTool that may contain code, images or more. These were introduced in MapTool 1.11, and are intended to be a replacement for [[Library Tokens]] that are easier to work with while offering more functionality.
-== First Add-on Library ==
+Add-on libraries are generally distributed as .mtlib files, which are just renamed .zip file with a specific structure.
-firstly you will need a text editor there are many of them mentioned below if in doubt just use [https://code.visualstudio.com/ VS Code].
-* [https://www.gnu.org/software/emacs/ Emacs]
-* [https://neovim.io/ Neovim]
-* [https://www.vim.org/ Vim]
-* [https://code.visualstudio.com VS Code]
-after choosing a text editor create a new directory to hold your Add-on. Top level files in the add-on are metadata files, they hold information about your add-on. the only file your add-on needs to be accepted by Maptool is library.json. You may have other non metadata files in a subdirectory which must be named library. for macro code you may have a mtscript directory inside library, both of those subdirectories may have a public directory which must be named public.
-=== Creating library.json ===
+Add-on Libraries are added to a campaign and are saved as part of the campaign file.
-the only required fields are
-* a name string
-* a authors array
-* a short description string
-* a namespace string
-the other fields are described in [[Creation of add-on libraries #Configuration File Format: library.json]] most of these are self explanatory just remember '''bad''' '''things''' will happen if you use the same namespace as someone else so try to use at least 3 words or a reversed host name.
-an example of a minimal library.json could be
+When the {{func|setLibProperty}} function is called on an add-on, the property name and value are stored in a campaign area.  That area is '''NOT''' cleared when the add-on is removed.  This allows the data to persist across add-on updates.  (Currently (as of v1.14.3), there are no corresponding functions to clear this data, so the only way to erase it is to create a new campaign.)
-  {
-    "name": "test",
-    "authors": ["you"],
-    "namespace": "test.test.test",
-    "shortDescription":"test"
-  }
-and that is it. you made an add-on those 6 lines are enough, just zip this file and then it rename so that it ends with .mtlib and have fun.
-== Achieving Common tasks ==
+== Managing the Add-On Libraries for Your Campaign==
+[[File:addon-dialog.png|400px|thumb|Add-on Library dialog]]The dialog to manage the add-on libraries for your campaign can be reached using the {{ui location|File > Add On Libraries...}} menu option.
+This dialog can be used to add or remove add-on libraries, view the details of all add-ons in the campaign and view their license/read me files.
+As of MapTool 1.12, add-on libraries can be dragged and dropped onto the map from your system's file explorer. This will either add the add-on library to the campaign or replace it if it is already in the campaign.
+== Things still to be addressed ==
+*There is only minimal checking of data when importing add-ons so error reporting is not great.
+*Expanding the JavaScript API which will make this much more useful (part of another change set).
+*Better replacement for user defined functions.
+*Providing an equivalent to [[Library Token]]s buttons.
+*Ability to check URL for later version and update from that (most likely GitHub to start with)
+*Link maps to required add-ons when exporting/importing.
+*Documentation / procedures for creating a GitHub release for your add-on.
+*The data store could be slightly smarter about large text blocks that remain static and attempt to cache them.
+Return to: [[Add-On Library]]

Introduction to Add-on libraries: Difference between revisions

Latest revision as of 01:09, 15 February 2024

What Is An Add-on Library?

Managing the Add-On Libraries for Your Campaign

Things still to be addressed

Navigation menu