{"id":10702,"date":"2020-07-07T12:51:39","date_gmt":"2020-07-07T12:51:39","guid":{"rendered":"https:\/\/fhug.org.uk\/kb\/?post_type=kb_article&#038;p=10702"},"modified":"2026-10-06T11:23:34","modified_gmt":"2026-10-06T11:23:34","slug":"getting-started-writing-plugins","status":"publish","type":"kb_article","link":"https:\/\/www.fhug.org.uk\/kb\/kb-article\/getting-started-writing-plugins\/","title":{"rendered":"Getting Started Writing Plugins"},"content":{"rendered":"<p>Plugin scripts are written in Lua, a lightweight scripting language that is ideal for embedding into more complex applications such as Family Historian.\u00a0 The scripts themselves are simple plain text files that can be created readily in either a dedicated or general-purpose text editor.\u00a0 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.<\/p>\n<p>It is not the intention of this KB page to teach readers how to write plugins.\u00a0 Rather, it contains pointers to the various support resources available and their overall context.<\/p>\n<h2>The Plugins Window<\/h2>\n<figure id=\"attachment_10703\" aria-describedby=\"caption-attachment-10703\" style=\"width: 300px\" class=\"wp-caption alignleft\"><img decoding=\"async\" class=\"size-medium wp-image-10703 lazyload\" data-src=\"\/kb\/wp-content\/uploads\/2020\/07\/Screenshot-2020-07-07-13.15.13-300x259.png\" alt=\"\" width=\"300\" height=\"259\" data-srcset=\"https:\/\/www.fhug.org.uk\/kb\/wp-content\/uploads\/2020\/07\/Screenshot-2020-07-07-13.15.13-300x259.png 300w, https:\/\/www.fhug.org.uk\/kb\/wp-content\/uploads\/2020\/07\/Screenshot-2020-07-07-13.15.13-150x129.png 150w, https:\/\/www.fhug.org.uk\/kb\/wp-content\/uploads\/2020\/07\/Screenshot-2020-07-07-13.15.13.png 602w\" data-sizes=\"(max-width: 300px) 100vw, 300px\" src=\"data:image\/svg+xml;base64,PHN2ZyB3aWR0aD0iMSIgaGVpZ2h0PSIxIiB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciPjwvc3ZnPg==\" style=\"--smush-placeholder-width: 300px; --smush-placeholder-aspect-ratio: 300\/259;\" \/><figcaption id=\"caption-attachment-10703\" class=\"wp-caption-text\">Plugin Dialog<\/figcaption><\/figure>\n<p>You open the <em>Plugins<\/em> dialog using <a href=\"#!\" class=\"cs_tooltip\" fhugtt=\"This is the menu across the top of the main Family Historian windows. The &gt; denotes a submenu\">Tools&nbsp&gt;&nbspPlugins<\/a>.\u00a0 By default, it shows options for installing and running plugins. Click on the <em>More&gt;&gt;<\/em> button to display an extra set of buttons that are more relevant for creating and managing plugin scripts.\u00a0 Click on the <em>&lt;&lt;Less<\/em> button to hide the additional options again.<\/p>\n<p><em>How to Write Plugins<\/em> opens the Plugin Help.\u00a0 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 <span class=\"fh\" style=\"font-size: 17px !important; line-height: 21.4286px !important;\">\u0192<span style=\"color:#73B262; font-weight: bold;\">h<\/span><\/span> context.\u00a0 (Note: in <span class=\"fh\" style=\"font-size: 17px !important; line-height: 21.4286px !important;\">\u0192<span style=\"color:#73B262; font-weight: bold;\">h<\/span><\/span>6 those tutorials mistakenly say use \/n for new line instead of \\n).<\/p>\n<p>The Plugin Help also describes the <span class=\"fh\" style=\"font-size: 17px !important; line-height: 21.4286px !important;\">\u0192<span style=\"color:#73B262; font-weight: bold;\">h<\/span><\/span> data structure and syntax, and how records are accessed and links.\u00a0 There are many similarities between accessing record fields in Queries and Plugins, but also some important differences.<\/p>\n<p>The links at the bottom of this article<em>\u00a0<\/em>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.\u00a0 Another resource recommended by people who are new to programming and\/or Lua is this <a href=\"https:\/\/www.tutorialspoint.com\/lua\/index.htm\">Lua Tutorial<\/a>.<\/p>\n<p>Note that all plugins are &#8220;open source&#8221;, 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.<\/p>\n<h2>Elements of a Typical Plugin<\/h2>\n<p>A typical plugin contains some or all of the following elements<\/p>\n<ol>\n<li>The core Lua scripting language, which is common to all Lua installations.\u00a0 As well as the learning resources described here, plenty of help is available online from sites such as <a href=\"https:\/\/stackoverflow.com\" target=\"_blank\" rel=\"noopener\">Stack Overflow<\/a>.<\/li>\n<li>Built-in Lua libraries that provide additional functions.\u00a0 The most common libraries are string (for handling string expressions), table (for data tables) and io (for basic file input and output).<\/li>\n<li>The <span class=\"fh\" style=\"font-size: 17px !important; line-height: 21.4286px !important;\">\u0192<span style=\"color:#73B262; font-weight: bold;\">h<\/span><\/span> Application Program Interface (API).\u00a0 These are functions written by Calico Pie for accessing and manipulating <span class=\"fh\" style=\"font-size: 17px !important; line-height: 21.4286px !important;\">\u0192<span style=\"color:#73B262; font-weight: bold;\">h<\/span><\/span> data.\u00a0 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.<\/li>\n<li>Dedicated <span class=\"fh\" style=\"font-size: 17px !important; line-height: 21.4286px !important;\">\u0192<span style=\"color:#73B262; font-weight: bold;\">h<\/span><\/span> libraries provided by Calico Pie to simplify common operations in <span class=\"fh\" style=\"font-size: 17px !important; line-height: 21.4286px !important;\">\u0192<span style=\"color:#73B262; font-weight: bold;\">h<\/span><\/span> that would otherwise require complex scripting.<\/li>\n<li>General Lua libraries.\u00a0 These are publicly available libraries that provided additional functionality.\u00a0 The most commonly used for <span class=\"fh\" style=\"font-size: 17px !important; line-height: 21.4286px !important;\">\u0192<span style=\"color:#73B262; font-weight: bold;\">h<\/span><\/span> plugin authors is probably the <a href=\"https:\/\/www.tecgraf.puc-rio.br\/iup\/\" target=\"_blank\" rel=\"noopener\">IUP library<\/a>, which builds Windows user interfaces from structured text commands.\u00a0 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.<\/li>\n<\/ol>\n<h2>Other Resources<\/h2>\n<p>An overview of more detailed Knowledge Base pages on dedicated topics is given below, along with links to complementary material available elsewhere<\/p>\n<p>The <a href=\"\/kb\/kb-article\/lua-code-snippets\/\">Snippets<\/a> section of this Knowledge Base provides many useful Functions that are often needed in Plugins, and provide example of how to write Lua code.\u00a0 These range from general introductory material of interest to all authors to complex and highly specialised functions for advanced users.<\/p>\n<span class=\"fh\" style=\"font-size: 17px !important; line-height: 21.4286px !important;\">\u0192<span style=\"color:#73B262; font-weight: bold;\">h<\/span><\/span> uses Unicode text encoding (UTF-8) to enable support for the additional characters required by many languages other than English.\u00a0 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.\u00a0 The additional factors that need to be considered are described in <a href=\"\/kb\/kb-article\/character-handling-for-plugin-authors\/\">International Character Handling for Plugin Authors.<\/a><\/p>\n<p>Separate Knowledge Base pages provide more detailed descriptions of <a href=\"\/kb\/kb-article\/iup-gui-builder-hints-and-tips\/\" target=\"_blank\" rel=\"noopener\">building a user interface with IUP<\/a>, and <a href=\"\/kb\/kb-article\/understanding-lua-patterns\/\" target=\"_blank\" rel=\"noopener\">using pattern matching for manipulating text strings<\/a>.\u00a0 These will be of interest to developing and intermediate authors.<\/p>\n<p>There are a number of key differences in the scripting language and libraries used in various versions of <span class=\"fh\" style=\"font-size: 17px !important; line-height: 21.4286px !important;\">\u0192<span style=\"color:#73B262; font-weight: bold;\">h<\/span><\/span>.\u00a0 These are mostly of interest to existing authors of store plugins that need to run in different versions of <span class=\"fh\" style=\"font-size: 17px !important; line-height: 21.4286px !important;\">\u0192<span style=\"color:#73B262; font-weight: bold;\">h<\/span><\/span>, and are described in pages covering <a href=\"\/kb\/kb-article\/lua-references-and-library-modules\/\" target=\"_blank\" rel=\"noopener\">Lua References and Library Modules<\/a>, and cross-version compatibility for <a href=\"\/kb\/kb-article\/writing-plugins-compatible-with-versions-5-6-7\/\" target=\"_blank\" rel=\"noopener\">Versions 5, 6 &amp; 7<\/a> and for <a href=\"\/kb\/kb-article\/writing-plugins-compatible-with-versions-7-8\/\" target=\"_blank\" rel=\"noopener\">Versions 7 and 8<\/a>.<\/p>\n<p>The <span class=\"fh\" style=\"font-size: 17px !important; line-height: 21.4286px !important;\">\u0192<span style=\"color:#73B262; font-weight: bold;\">h<\/span><\/span>7 plugin help is also <a href=\"https:\/\/www.family-historian.co.uk\/help\/fh7-plugins\/hh_start.htm\" target=\"_blank\" rel=\"noopener\">available online<\/a>, as is the <span class=\"fh\" style=\"font-size: 17px !important; line-height: 21.4286px !important;\">\u0192<span style=\"color:#73B262; font-weight: bold;\">h<\/span><\/span>8 <a href=\"https:\/\/www.family-historian.co.uk\/help\/fh8plugins\/\">plugin help.<\/a><\/p>\n<h2>Publishing Your Plugin<\/h2>\n<p>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,\u00a0 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.<\/p>\n<p>Brand new plugins are best published in the <a href=\"https:\/\/fhug.org.uk\/forum\/viewforum.php?f=42\">Plugin Discussions Forum<\/a> first, where their context and function can be discussed and user testing and comment invited.\u00a0 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.\u00a0 There is no requirement or expectation that new plugins should be compatible with previous versions of <span class=\"fh\" style=\"font-size: 17px !important; line-height: 21.4286px !important;\">\u0192<span style=\"color:#73B262; font-weight: bold;\">h<\/span><\/span>, or necessarily support all features of the current version.\u00a0 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 <span class=\"fh\" style=\"font-size: 17px !important; line-height: 21.4286px !important;\">\u0192<span style=\"color:#73B262; font-weight: bold;\">h<\/span><\/span>7-compatible version simpler to use and understand.<\/p>\n<p>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 Store using an account via <a href=\"https:\/\/pluginstore.family-historian.co.uk\/how-to-submit-a-plugin-to-the-plugin-store\">Submit a Plugin for the Plugin Store.<\/a>\u00a0 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.<\/p>\n<p>Experience has demonstrated that published plugs are more useful if they follow a number of basic principles:<\/p>\n<ol>\n<li>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.<\/li>\n<li>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.<\/li>\n<li>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.<\/li>\n<li>When posting a draft of a new plugin on FHUG 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.<\/li>\n<\/ol>\n<p>&nbsp;<\/p>\n","protected":false},"template":"","fh_version":[14,15,739],"skill_level":[17],"topic":[73],"class_list":["post-10702","kb_article","type-kb_article","status-publish","hentry","fh_version-v5","fh_version-v6","fh_version-v7","skill_level-intermediate","topic-writing-plugins"],"_links":{"self":[{"href":"https:\/\/www.fhug.org.uk\/kb\/wp-json\/wp\/v2\/kb_article\/10702","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/www.fhug.org.uk\/kb\/wp-json\/wp\/v2\/kb_article"}],"about":[{"href":"https:\/\/www.fhug.org.uk\/kb\/wp-json\/wp\/v2\/types\/kb_article"}],"wp:attachment":[{"href":"https:\/\/www.fhug.org.uk\/kb\/wp-json\/wp\/v2\/media?parent=10702"}],"wp:term":[{"taxonomy":"fh_version","embeddable":true,"href":"https:\/\/www.fhug.org.uk\/kb\/wp-json\/wp\/v2\/fh_version?post=10702"},{"taxonomy":"skill_level","embeddable":true,"href":"https:\/\/www.fhug.org.uk\/kb\/wp-json\/wp\/v2\/skill_level?post=10702"},{"taxonomy":"topic","embeddable":true,"href":"https:\/\/www.fhug.org.uk\/kb\/wp-json\/wp\/v2\/topic?post=10702"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}