Getting Started Writing Plugins
Plugins are written in Lua (currently release 5.1), a language which is becoming more common, and can currently be found in programs as diverse as Adobe Lightroom, World of Warcraft, and several development tools for Smartphones and iOS devices such as Corona.
The Family Historian Tools > Plugins > More > How to Write Plugins has some short tutorials to get you started (beware those tutorials mistakenly say use /n for new line instead of \n). The links below list a range of Lua related sites, including the Programming in Lua book, which is advanced, but well worth exploring if you are interested in developing more advanced Plugins.
The Code Snippets section provides many useful Functions that are often needed in Plugins, and which also illustrate how to write Lua code. Open a Plugin for editing and place the cursor in any FH Function or Method and then press F1 to get context sensitive help for it. For the definition of the tilde (~) please see the Family Historian help on How to Write Plugins > The Family Historian API > Understanding the Data Structure and also the Understanding Data References link.
Once you have written and tested your Plugin you may wish to offer it to other users. Initially, it may be advisable to add it to the Work In Progress Plugins section just for FHUG members to try. Eventually, you could publish it in the Family Historian Plugin Store using an account via the Submit a Plugin to the Store page link. Subsequently, to update your Plugin, login to the View your Plugins page, and use the Edit option (Do NOT use the Submit a Plugin page again).
Beware that some characters in the Family Historian Plugin Store text may need to be escaped in much the same way as in Lua Plugin scripts ( i.e. \' \" \\ \% \_ ). A backslash \ on its own will vanish. This is due to the MySQL database as explained in https://dev.mysql.com/doc/refman/8.0/en/string-literals.html Table 9.1 Special Character Escape Sequences.
To add a screenshot for your Plugin, add its image to the Screenshots for Plugin Store page to ensure it will not get deleted via the Media Manager. Then link it to the Family Historian Plugin Store URL Screenshot field using such as
FH V6 Unicode
fh V6 introduced Unicode UTF-8 encoding, which can have an impact on Plugins. If a Plugin edits any textual fields, they may contain Unicode UTF-8 characters and to prevent their corruption the Plugin must use UTF-8 encoding and use appropriately modified functions and possibly modified Lua patterns. See Unicode String Functions (code snippet) and Unicode UTF-8 Encoding patterns.
Online References & Library Modules
There are also prototype Plugins attached to Forum threads for new features or dedicated operations.
Lua Language References
Note Lua 5.3 released in Jan 2015 was updated in Jul 2018 but fh has not incorporated that version.
See Lua version history for details of all versions and links to free online Reference Manuals.
|Lua 5.1 Reference Manual free online||fh V6 and V5 incorporate Lua 5.1.5|
|Programming in Lua Paperback editions||1st Lua 5.0, 2nd Lua 5.1, 3rd Lua 5.2, 4th Lua 5.3|
|Programming in Lua (first edition) free online||Lua 5.0|
|Lua Wiki ~ Main Page and Lua Wiki ~ Sample Code||programming language information & resources|
|e.g. SaveTableToFile||save table to file & load table from file|
|e.g. StringRecipes||various common string manipulations|
IUP GUI Builder References
Note IUP 3.28 was released on 13 Dec 2019 but fh has not incorporated that version.
|A Basic Guide to using IupLua|
|IUP Portable User Interface V3 Manual||require( "iuplua" ) -- v3.11.2 in fh V6, v3.5 in fh V5|
|IupControls||require( "iupluacontrols" )|
|IupGLCanvas||require( "iupluagl" )|
|IupGLControls||require( "iupluaglcontrols" )|
|IupMglPlot||require( "iuplua_mglplot" )|
|IupOleControl||require( "iupluaole" )|
|IupScintilla||require( "iuplua_scintilla" )|
|IupWebBrowser||require( "iupluaweb" )|
Other Lua Library Modules
The versions of these Library Modules supported by fh are often not the latest available, and sometimes it is not easy to determine which version is supported.
|Lua File System Library Manual||require( "lfs" )|
|LuaCOM User Manual Version 1.3||require( "luacom" )|
|IM - Digital Imaging Tool Version 3.12|| require( "imlua" ) require( "imlua_process" )
-- v3.8.2 in fh V6, v3.4.2 in fh V5
|MD5: Cryptographic Library for Lua||loadrequire( "md5" )|
|LuaSocket: Network support for Lua||loadrequire( "socket" )|
|LuaZip: Reading files inside zip files||loadrequire( "zip" )|
|LuaSQL: DBMS interface for Lua||loadrequire( "luasql", "luasql.sqlite3" )|
|Penlight Lua Library Modules||loadrequire( "pl", "pl.init" )|