Introduction

When you start creating Plugins for yourself or for the Plugin Store it really helps to be able to manage the files and the file levels.

These notes are intended to help Plugin authors make use of available tools as well as produce consistent Plugins.

Using a Main Function

Although not required, it can be a good idea to use a main function for any more complex 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. that use extra 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, as it allows you to keep the main code at the top of the source code.

A simple example would be

function main()
print(hello())
end

function hello()
return 'hello'
end
---------------------------- call main function
main()

The Script Header

When starting a Plugin it’s a very good idea to add a Plugin Header which can easily be done from the Edit » Insert Script Header option.

In ƒh6 This will insert the following to the top of your file.

--[[
@Title: 
@Author: 
@Version: 
@LastUpdated: 
@Description: 
]]

and in ƒh7:

--[[
@Title: 
@Type: Standard
@Author: [YOUR NAME HERE]
@Version: 
@Keywords: 
@LastUpdated: 
@Licence: This plugin is copyright (c) [YEAR AND YOUR NAME HERE] and contributors, and is licensed under the MIT License
which is hereby incorporated by reference (see https://pluginstore.family-historian.co.uk/fh-plugin-licence)
@Description: 
]]

Consult the Plugin Store for information on how to complete the fields, but take particular care that:

• The @Title: exactly matches the Plugin name and Plugin File name.
• The @LastUpdated: date matches the dateWhen an Event happened, or an Attrribute was true. you upload the file to the Plugin StorePublished plugins can be downloaded from the Family Historian Plugin Store..
• You include the mandatory licence.

It’s a good idea to start with a @Version: number of 0.1.0 for the prototypes and then move up to 1.0.0 when you are ready to release the Plugin to the Plugin Store as explained in more detail below.

The @Description: field can span multiple lines; leave a blank line to mark paragraphs.

It is recommended that a log of changes is recorded in the header after the Description, using a format such as:

@Description: This plugin provides various date conversions.
@ChangeLog:
@V0.1.0: First prototype attachment to the FHUG Forum.
@V0.1.1: Fixed double date conversion problem.
@V1.0.0: First published release into the Plugin Store.
]]

Version Numbers

Each distinct version of your plugin should have a different version number (as recorded in the @Version: section in your plugin header. It is recommended that you adopt Semantic Versioning, which uses a three part numbering system (and is used byƒh itself):

• MAJOR version (incremented when significant new features are released, or changes are released that are not backwards compatible with previous versions – e.g. file/data formats in a new version will not be readable in previous versions)
• MINOR version (incremented when minor new features are released and there are no backwards-compatibility issues)
• PATCH version (incremented when bug fixes are released without new features)

Each element of the version number is an integer starting from 0, without leading zeroes.

MAJOR version 0 is reserved for development/testing before the first release of your plugin. Whenever the MAJOR version is incremented, MINOR AND PATCH levels are initially set to zero.

The authors of very simple plugins may decide not to use the PATCH version component, although it can be very useful for tracking bug-fix releases.

Version Control

In the commercial programming world, version control systems are very important as they allow a fairly easy way of tracking changes over time.

There are many different ones and some need a dedicated server. However, there are several systems for Windows which are suitable for home Plugin writers.

A fairly easy to use Windows control system is Git for Windows, which once installed allows the easy creation of a repositoryA repository is a place (physical or online) where collections of original source data are stored and maintained. (where all the changed code lives) inside your Plugins folder and allows files to be managed easily using right click on the files in the folder or using Git Gui. There is a nice (if somewhat out of date) guide to getting started with git at NathanJ: An Illustrated Guide to Git on Windows; for home use you can ignore the Putty section.

The latest version can be downloaded from Git for Windows.nathanj.github.io/gitguide/tour

A version control system will help you keep control of your version numbers.