• Skill Level: Advanced and Intermediate
• FH versions: V5, V6, and V7
• In Topics: Writing plugins 

Family Historian Plugins

Family Historian 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. are a powerful tool for ordinary users to create and share additional functionality for processing user data. However, this also creates the potential for plugins to corrupt that data due to either the user misunderstanding what the plugin does or from a coding error by the plugin author.

Authors creating plugins for their own personal use can of course structure them as they wish. However, plugins made available to other users either via the Family Historian Plugin StorePublished plugins can be downloaded from the Family Historian Plugin Store. or via the 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. forum must comply with a minimum set of standards designed to protect the integrity and privacy of user data and minimise the risk of accidental data loss or system corruption.

It is intended that these standards are self-policing, and will not be proactively checked by either Plugin Store or FHUG admin. However, new plugins or revisions to existing plugins that are found to breach the standards may be subject to either required revision or removal.

Plugin Functions and Actions

1. Plugins may read the Windows Registry without restriction. They must not modify the Registry, apart from the two specific Family Historian keys, described in Understanding the Scope of Features, and then only if essential to the stated plugin functionA '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, such as restoring a backup of user settings.
2. Where a plugin makes a change to user data or files that cannot be reversed by selecting Edit > Undo Plugin Updates from the main Family Historian menu, this should proceed only after requesting confirmation from the user. The confirmation message should describe what the plugin is about to do in non-technical user language, and what the potential consequences of that action are. Typically, this would arise from any change to a file other than to the projectA Project is a Windows folder, created by Family Historian, which contains all your Family Tree information recorded in Family Historian. Normally located in the Documents\Family Historian Projects folder. GEDCOMGEDCOM, an acronym for GEnealogical Data COMmunication, is a specification for exchanging genealogical data between different genealogy software. It is a file format that most genealogical programs and online trees recognise. file made through FH API, such as MediaWhen you add a picture, video, sound recording, document file etc into a Family Historian project, a Media record is created to represent that media item within the project; the Media record includes a link to the actual Media file. files or Family Historian settings files (Fact SetsA Fact Set is a defined list of types of Facts - that is types of Events and Attributes., Source TemplateFamily Historian Version 7 introduced the ability to define sources using 'Source Templates' to aid precision and consistency in entering source-identifying information.   Definitions, etc). Changes to the plugin’s own settings data do not require specific user confirmation.
3. Plugins should not make changes to user files that make them unusable without a subsequent step to complete the action, such as breaking the link between the file contents and its file name extension, to prevent corruption if the subsequent step fails.
4. Plugins must not download any executable code such as LuaThe language in which Family Historian plugins are written. libraries, scripts written in any other programming language (including batch files/command scripts), or executable files. Non-executable files (typically documents, such as help files) may be downloaded if essential to the stated action of the plugin, documented, and proceeds only after the user has confirmed consent. (Plugins written for versions of Family Historian prior to version 7 may download Lua libraries from the Family Historian website only).
   Plugins may generate and execute text scripts (including batch files/command scripts) necessary to fulfil their function.
5. Plugins may upload user data to a published and publicly available API if essential to the stated action of the plugin (for example, a list of placesAccording to GEDCOM, a Place should hold "The jurisdictional name of the place where the event took place…"   uploaded to a mapping service), but only after the user has given specific consent. The process for requesting consent must include a link to the API website, including their privacy policy.
6. Where a plugin provides links to relevant external websites, such as more detailed help information, a family tree site, etc., these must be clearly labelled as such in the user interface.