Getting Started Writing Plugins

Introduction

Plugins are written in Lua, 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.

Plugin Dialog
Tools > PluginsPlugins are small programs that allow new features to be added without upgrading Family Historian itself; some plugins are written by Calico Pie and others are written by users.… opens the Plugins dialog. If you use the More>> button, an extra set of buttons appears on the right. (You can hide these again with the <<Less button.)

How to Write Plugins has some short tutorials to get you started (Note: in ƒh6 those tutorials mistakenly say use /n for new line instead of \n). The links at the bottom of this article 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 Snippets section of this Knowledge Base provides many useful Functions that are often needed in Plugins, and which also illustrate how to write Lua code. Open a Plugin for editing via the Plugins dialog 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 announce its availability in the Plugin Discussions Forum for FHUG members to test.

Eventually, you could publish it in the Family Historian Plugin Store using an account via Submit a Plugin for the Plugin Store. Subsequently, to update your Plugin, login to via the Authors Area of the Store page, and use the Edit option.

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.

FH V6 Unicode

ƒh6 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.

 

Last update: 11 Dec 2020