Introduction to Add-on libraries: Difference between revisions

From RPTools Wiki
Jump to navigation Jump to search
VisualWikitext
m (added beginner banner)
m (Added note about how setLibProperty() stores persistent data)
 
(7 intermediate revisions by 3 users not shown)
Line 1: Line 1:
{{stub}}
{{Beginner}}
{{Beginner}}
[[Category:Tutorial]]
[[Category:Tutorial]]
== 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 {{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.)
== 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.




== 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.


== First Add-on Library ==
== Things still to be addressed ==
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].
*There is only minimal checking of data when importing add-ons so error reporting is not great.
* [https://www.gnu.org/software/emacs/ Emacs]
*Expanding the JavaScript API which will make this much more useful (part of another change set).
* [https://neovim.io/ Neovim]
*Better replacement for user defined functions.
* [https://www.vim.org/ Vim]
*Providing an equivalent to [[Library Token]]s buttons.
* [https://code.visualstudio.com VS Code]
*Ability to check URL for later version and update from that (most likely GitHub to start with)
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.
*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.


=== Creating library.json ===
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
  {
    "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 ==
Return to: [[Add-On Library]]

Latest revision as of 23:59, 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

Add-on Library dialog

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

Retrieved from "https://rptools.hyperbooks.com/index.php?title=Introduction_to_Add-on_libraries&oldid=33945"