Plugin scripts are written in LuaThe language in which Family Historian plugins are written., a lightweight scripting language that is ideal for embedding into more complex applications such as Family Historian.  The scripts themselves are simple plain text files that can be created readily in either a dedicated or general-purpose text editor.  Compared with a full programming language, the syntax is relatively simple and well-placed for beginners with no previous programming experience to create useful scripts with a bit of practice.

It is not the intention of this KB page to teach readers how to write plugins.  Rather, it contains pointers to the various support resources available and their overall context.

The Plugins Window

You open the Plugins dialog using Tools > Plugins.  By default, it shows options for installing and running plugins. Click on the More>> button to display an extra set of buttons that are more relevant for creating and managing plugin scripts.  Click on the <<Less button to hide the additional options again.

How to Write Plugins opens the Plugin Help.  As well as detailed help on individual aspects of plugins, it includes some short introductory tutorials that provide the ideal starting point for learning to write Lua scripts in a ƒh context.  (Note: in ƒh6 those tutorials mistakenly say use /n for new line instead of \n).

The Plugin Help also describes the ƒh data structure and syntax, and how records are accessed and links.  There are many similarities between accessing record fields in QueriesQuerying is a very powerful feature that allows you to specify and save criteria for identifying a set of records of a given record type. and Plugins, but also some important differences.

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.  Another resource recommended by people who are new to programming and/or Lua is this Lua Tutorial.

Note that all plugins are “open source”, meaning that any user can read the full details of the plugin script, and create modified copies to tailor the detailed application to their own requirements.

Elements of a Typical Plugin

A typical plugin contains some or all of the following elements

1. The core Lua scripting language, which is common to all Lua installations.  As well as the learning resources described here, plenty of help is available online from sites such as Stack Overflow.
2. Built-in Lua libraries that provide additional functionsA 'function' is an expression which returns values based on computations. Typically, functions require data to be supplied to them as 'parameters'. A function in Family Historian is similar to a 'function' as used in spreadsheet applications (such as MS.  The most common libraries are string (for handling string expressions), table (for data tables) and io (for basic file input and output).
3. The ƒh Application Program Interface (API).  These are functions written by Calico PieCalico Pie Limited is a UK software house, and the publishers of Family Historian. for accessing and manipulating ƒh data.  They are documented in the Plugin Help, and context-sensitive help is available by pressing the F1 key while the cursor is on the function name.
4. Dedicated ƒh libraries provided by Calico Pie to simplify common operations in ƒh that would otherwise require complex scripting.
5. General Lua libraries.  These are publicly available libraries that provided additional functionality.  The most commonly used for ƒh plugin authors is probably the IUP library, which builds Windows user interfaces from structured text commands.  There are many other such libraries, some of which are described in the plugin help text, but most of these are only relevant for more advanced authors and are not required for most general user plugins.

Other Resources

An overview of more detailed Knowledge Base pages on dedicated topics is given below, along with links to complementary material available elsewhere

The Snippets section of this Knowledge Base provides many useful Functions that are often needed in Plugins, and provide example of how to write Lua code.  These range from general introductory material of interest to all authors to complex and highly specialised functions for advanced users.

ƒh uses Unicode text encoding (UTF-8) to enable support for the additional characters required by many languages other than English.  This can cause complications for plugins that need to handle text or file names that contain these characters as not all of the required tools have been updated to support Unicode.  The additional factors that need to be considered are described in International Character Handling for Plugin Authors.

Separate Knowledge Base pages provide more detailed descriptions of building a user interface with IUP, and using pattern matching for manipulating text strings.  These will be of interest to developing and intermediate authors.

There are a number of key differences in the scripting language and libraries used in various versions of ƒh.  These are mostly of interest to existing authors of store plugins that need to run in different versions of ƒh, and are described in pages covering Lua References and Library Modules, and cross-version compatibility.

The ƒh7 plugin help is also available online.

Publishing Your Plugin

Plugin authors usually start by developing plugins for their own use, driven by the need to do something that is outside the native scope of FH,  As you develop your skills, you may wish to consider making your plugin available to other users if it is likely to be of more general interest.

Brand new plugins are best published in the Plugin Discussions Forum first, where their context and function can be discussed and user testing and comment invited.  Most non-trivial new plugins will contain the occasional bug that the author had not spotted or tested for, and it is usual for updated versions to be posted as bugs are resolved and the scope refined.  There is no requirement or expectation that new plugins should be compatible with previous versions of ƒh, or necessarily support all features of the current version.  Frequently, there are simpler ways of doing things in later versions due to improvements in the supplied libraries and API, and new authors are likely to find the ƒh7-compatible version simpler to use and understand.

If a plugin is likely to prove to be of general interest, rather than a niche application for a handful of users, the next stage is to offer the plugin to the Family Historian Plugin StorePublished plugins can be downloaded from the Family Historian Plugin Store. using an account via Submit a Plugin for the Plugin Store.  The plugin will be reviewed by Calico Pie prior to publication to ensure that it does not contain any harmful code and conforms to basic style guidance, but is not checked for function or bugs.

Experience has demonstrated that published plugs are more useful if they follow a number of basic principles:

1. When designing plugin interfaces or help files, ensure that terminology is consistent with that used in the main Family Historian application to aid user understanding of what the plugin is intended to do.
2. Use language appropriate for the intended plugin users. For example, a complex plugin aimed at advanced users may require a very technical description or help file, but a general-purpose plugin likely to be used by relative newcomers to Family Historian should avoid technical jargon.
3. Plugins that are readily understood by other authors are of greater long-term value, as they can be supported and adapted once the originator is no longer able to do so.
4. When posting a draft of a new plugin on FHUGThe Family Historian User Group is a group of user with wide-ranging experience, from newcomers to very experienced users, all of whom are very willing to shared their knowledge about the programme. for user beta-testing, it is beneficial to state clearly whether the plugin changes user data or is purely read-only so users can assess whether there is any risk associated with testing the plugin.