Submit a Plugin for the Plugin Store

Overview

The best way to share a plugin with others is to add it to the Family Historian Plugin Store.  That way, any Family Historian user will be easily able to see it and install it.  All they will have to do is open the Import dialog within Family Historian (accessible from the File menu), click on the Plugin… option, and select a plugin file that they’ve downloaded from the Plugin store; or they can double-click on the file that they have downloaded within File Manager.

If you have written a new plugin, or even if you have adapted and significantly improved somebody else’s plugin, please consider submitting it to the Family Historian Plugin store. You can do so pseudonymously if you wish, or you can use your real name – it’s up to you.  Obviously if yours is the the first plugin for a particular purpose, it will be greatly valued.  But even if there are already plugins that do a similar job, please consider submitting yours anyway.  Different plugins may have different styles or benefits.  It’s good for users to have a choice.  Any user can download and install plugins for the same or similar purpose if they want to, and easily compare them; so there’s no problem about having overlapping plugins.  It’s also not a problem if you have created your plugins  by adapting someone else’s plugin – even if you previously downloaded that plugin from the plugin store.  More on this below.

You will be able to make as many changes and improvements as you want to your plugin after you have submitted it to the Plugin Store, so don’t assume that it has to be perfect before you submit it!

Submitting your plugin to the Plugin Store can be done in three steps:

  1. Apply to Become a Plugin Author (if you aren’t one already)
  2. Prepare the Plugin File
  3. Submit Your Plugin File
  4. Plugin Help
  5. Updating a Plugin

All submissions are subject to the Terms and Conditions of Use.

If you have any problems or are unable to follow these instructions, please email support@family-historian.co.uk.

1. Apply to Become a Plugin Author (if you aren’t one already)

To submit your plugin to the Plugin Store, you must first create an account in the Plugin Store as a Plugin Author.  It’s a good idea to do this part first because it can take a little while for your application to be processed.  To create the account, please do the following:

  • Go to https://pluginstore.family-historian.co.uk and click on “Authors Area” in the top-right.
  • Click on the “Author application form” link in the “New Authors” area, fill in the details and click “Apply”.  There’s no need to specify a website if you don’t have one or don’t want to mention it.
  • We will process your application and email you your login details.  This may take a little while.  While waiting for your account details to arrive, please get your plugin file ready for submission (see next section below).
  • When the email arrives (the Subject line will probably be “[Plugin Store] Login Details” or something similar), click on the link to set your password.  Be sure to keep a record of your username and password (and the login link to the Plugin Store, which is https://pluginstore.family-historian.co.uk/wp-login.php) for future reference.

2.  Prepare the Plugin File

The file you will submit to the Plugin Store is the file that you have created using a Lua editor.  But before you do that, please carefully check that the details in the header are correct.  The plugin should have a header at the top which looks something like this:

–[[
@Title:
@Type:
@Subtype: generic,”Civil Registration Certificate”,”Church Register”
@Author: Fred Bloggs
@Contributors: Jane Smith
@Version:
@LastUpdated:
@Licence: This plugin is copyright (c) 2020 Fred Bloggs & 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:
]]

Please check that you have all of these fields and that the values entered are all correct.  Here are notes on each of the fields:

  • @Title:  A brief unique identifier for the plugin, which should be the same as the plugin file name
  • @Type: must have the value ‘standard’, ‘report’ or  ‘Source-driven data entry’ and nothing else. If not included the plugin defaults to ‘standard’. (Not required for V6 and below)
  • @Subtype: only required for Source-driven data entry plugins for V7. Comma-separated text that identifies the sources that which the plugin will work, including: generic, all (which should be the only subtype if included), or specific source templates (within double quotes).
  • @Author: should have your name (it can be a comma-separated list of names if the plugin has multiple authors).  If you wish to be anonymous, use a pseudonym rather than your real name.  Bear in mind that your plugin could be downloaded all over the world!
  • @Contributors: comma-separated list of people who have contributed to the plugin one way or another.  So for example, if you have adapted someone else’s plugin, you should either list them as a second author, or add them to the comma-separated list of contributors (e.g. “@Contributors: Calico Pie Limited, Amanda Swan, Nigel Jones”).  It’s up to you.
  • @Version: If this is your first submission, set the value to “1.0” as in the example above.  If you later make a minor improvement, you could change it to “1.1”.  A major enhancement could be “2.0”.  And so on.
  • @LastUpdated: put today’s date here. This must match the date you upload the file to the plugin store.
  • @Licence:  Required.  We recommend that you enter this exactly as shown in the 3-line example above (just changing the year if necessary).  All Family Historian plugins are subject to the MIT license, which means that anyone is free to adapt them and use them in any way they want.  The licence also asserts that each plugin or language pack comes with no warranties of any kind and that you (and we) are not responsible for anything that might arise in connection with it. See https://pluginstore.family-historian.co.uk/fh-plugin-licence for more details.
  • @Description: Brief description of the purpose of the plugin.

Once you are satisfied that the header information is correct, save changes to the plugin in your editor.  Then install it in FH for testing, and check that the header information is displaying correctly by selecting Tools > Plugins via the menu, select the plugin and review the details displayed at the bottom of the Plugins window to ensure they are displaying correctly.

Once happy with the header (and the plugin) save the plugin file ready for submission in the next step.

3. Submit Your Plugin

You are now ready to submit your plugin to the Plugin Store.  Go to https://pluginstore.family-historian.co.uk/wp-login.php and login to your account.  Down the left-hand side of the window, you should see a “Plugins” link.  Click on this and then click “Add New” (careful! It’s the Add New link under “Plugins” you want and not the Add New link under “Language Pack”).  The “Add New plugin” window opens.

Enter the Plugin Title (which must match the @Title field within the plugin) into the Title field.

In the main text field, enter a description of the plugin. This can be copied from the plugin @description field, but you have more space available, so you may wish to add more helpful detail. Do not clutter this with a Version History – there is a separate field later for this.  Important note: the first sentence of this description is used to summarize the plugin in various places with the Plugin Store, so ensure it makes sense and accurately represents your plugin as a standalone sentence.

In the area labelled “More Fields”, click on the Add File button to add your plugin file.

Still in the “More Fields” area, select the Plugin Type; you will not be able to save your plugin entry until you have done this.

Still in the “More Fields” area, set the compatibility for FH versions 5, 6 and 7, depending on whether you have coded your new plugin to support older versions of FH.  If you don’t complete one or more of these fields, your plugin will not be approved.

Still in the “More Fields” area, consider adding a Screenshot to illustrate your plugin’s capabilities/look and feel.

Still in the “More Fields” area, specify a version number for your plugin (matching the @Version field within the file).

Still in the “More Fields” area, specify a version release date for your plugin (matching the @LastUpdated field within the file); you will not be able to save your plugin entry until you have done this.

Still in the “More Fields” area, you should document your plugin’s Version History if any.

Finally click the Submit for Review button (in the right hand side bar).  Your plugin will be reviewed by Calico Pie before it is accepted. You will receive an email telling you when the plugin is accepted, or if there are any problems (e.g. missing fields in the plugin header or plugin store entry).

4. Plugin Help

Unless your plugin is very simple, please consider adding Plugin Help. Down the left-hand side of the window, you should see a “Help” link.  Click on this and then click “Add New” . The “Add New Help” window opens.

Enter a Title that matches your plugin name exactly.

Use the main text field to enter your Help content.

If you need to add more than one Help page, add them using Related Pages. We recommend the title of each Related Page includes the Plugin name as a prefix.

The fhUtils module supplied with Family Historian provides a routine helpButton to invoke a particular plugin store Help page.

5. Updating a Plugin

Once you have submitted your plugin, you may find that you want to release fixes/changes.

Navigate to the plugin you want to update and Edit Plugin.

You can update any or all of the fields you entered when you submitted your plugin. If you need to update the plugin file, delete the existing file before adding a new one.

You can also mark a Plugin as Superseded by another Plugin (including a New Plugin that you contribute) and document the FH version from which it is superseded.