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

Alternatively, create a Plugin Help and Advice entry with screenshots and link one of those to the Family Historian Plugin Store URL Screenshot field similar to above.

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

Published Plugins

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" )

See the Module Require With Load (code snippet).