How To Write A Plugin

In order to write a plugin, first open the Plugins Window by clicking 'Plugins' on the Tools menu. Next click the More>> button to show the additional buttons, and click on the New button to create a new plugin. The new plugin will open in the Plugin Editor.

The Plugin Editor window is split into three areas: the Text Pane (top), the Output Pane (bottom-left), and the Variable Pane (bottom-right). The Text Pane is where the actual plugin 'script' (also called 'code') is entered. The Output Pane will display information about any syntax errors with your code. If your script uses the Lua standard 'print' command (sometimes useful for debugging), output from this command is also displayed in the Output Pane. The Variable Pane in the bottom right will show the currently available variables in the plugin, when the debugger is active and the script is at a breakpoint (see Debugging for more information about breakpoints).

For this guide, and throughout the help, Lua code will be shown in a box similar to the one below.

fhMessageBox("Hello World")

You will notice that the code above is colour-coded.  This is just to make it easier to read in the Help. The Plugin Editor does not colour the code.

You can now write your first plugin script. Type the code shown above into the Text Pane in the Plugin Editor. You can copy and paste the code directly from the help if you wish, but many people find it useful to type the examples.

It is important to note that Lua (the language used by plugins) is case-sensitive; so fhMessageBox is valid, but fhmessagebox is not. If you type it in incorrectly you will get an error in the Output Pane when you run the code.

Once you have entered your code, press the Go button to run it. When you do this, the code will be checked and, if it is valid, it will be executed. If you entered the code correctly, a window should pop up on the screen saying "Hello World".  You can click OK to clear the message. Once the message is cleared you should see the message "Plugin completed successfully" in the Output Pane of the Plugin Editor.

That's it.  You have now completed your first Lua script.

You displayed the string "Hello World" using the fhMessageBox function.

"Hello World"

This is a string. Strings can be made up of any characters and are enclosed by either single quotes, double quotes, or in special cases double square brackets - e.g [[ ]].

fhMessageBox

This is a function supplied by Family Historian (part of its 'API'). For now it will simply be used to output any results from your plugins. As used above it displays a box containing the message provided in the string.
functions will be covered in more detail later.

Now select 'Save' from the File menu and save your plugin as "Hello World".

Try modifying the plugin to say "Good Job" in the message box and press the Go button (or press F5) to see the message box. If you are stuck, click Show Exercise Answer to see the modified plugin.

fhMessageBox("Good Job")