This plugin introduces several new concepts. Enter each line in turn as you work through the section. Remember that the text which makes up a plugin is known as 'script' or 'code'; so whenever you see 'code' mentioned, this is the text shown in the Text Pane of the Plugin Editor.
Open the plugin editor and create a new plugin.
-- Calculate a Birth Year from an age and a year
Lines in your plugins prefixed with '--' (two dashes) are comments. You can put comments on a line of their own as has been done here or you can add them to the end of a line. You can put whatever you like as a comment, but at a minimum, a comment to remind you, and tell others what your plugin does, is highly recommended.
You cannot put too many comments in your plugins, so feel free to add as many as you like to any plugin you write, especially as you work through this guide. That way when you come back to your plugins to amend them, you will be able to see at a glance what they are doing.
iYear = 1911 iAge = 21 iBirth = iYear - iAge
iYear, iBirth and iAge are all variables. Variables are containers which hold values for the plugin to work with. In Lua, a variable contains information and that information has a type, such as number or string.
Variables can be any combination of letters and numbers provided that
they start with a letter. It is suggested to aid your memory, that
they are prefixed with a few letters to identify the type of
information you have in them. So for numbers the examples will prefix
them with the letter 'i' and strings will be prefixed with 'str'.
There are other prefixes which you will meet as you progress.
When picking a name for your variables, always try to use ones which make it clear what they hold. You could call the variables a, b and c and the code would still work, but it would be more difficult to understand what it does.
In the example iYear, iAge and iBirth are set to contain the value shown after the equal sign. So once these lines are run, they all contain numbers.
You can perform maths on numbers. In this example, we take an age value (21) away from a year (1911) to calculate a year of birth. When you run the plugin, the result (1890) is stored in the iBirth variable.
Take the time to play with this example, and try some of the different maths functions available to you. These include:
print(iAge,iYear,iBirth)
The print function is a standard Lua function, and, when used in Family Historian, will send its output to the Output Pane of the editor. If you run the plugin direct from the Plugins Window you will not see the any output from the print function, so the latter is primarily only useful for debugging in the Plugin Editor. You can pass more than one variable to the print function by separating them with commas.
strMessage = "Birth Year is: " .. tostring(iBirth)
Here strMessage is assigned a string value. The first part of the string will be "Birth Year is: ". The next part of the line uses the concatenation operator '..' to append the value of the iBirth variable to the end of the string. As iBirth is a number, another standard Lua function tostring() is used to create a string version of iBirth. In fact, the use of this function is not strictly necessary in this case, as Lua can convert numbers to strings automatically.
fhMessageBox(strMessage)
Finally we use strMessage as a parameter for the fhMessageBox function introduced in the first lesson. Notice that because strMessage is a string variable, it is not in quotes. If you do put it in quotes your message box would display "strMessage" rather than "Birth Year is: 1890".
Save this example plugin under the name "Calculate Birth Date".
-- Calculate a Birth Year from an age and a year iYear = 1911 iAge = 21 iBirth = iYear - iAge print(iAge,iYear,iBirth) strMessage = "Birth Year is: " .. tostring(iBirth) fhMessageBox(strMessage)
Based on the example just completed, try to add the values of iYear and iAge to strMessage. Hint: if you want to include a new line just include \n in a string.
There are lots of different ways to complete this. Click on Show Exercise Answer to see one possible method. There are often many different ways to get to the same end result when writing a plugin. As long as you get the answer correct in the message box, the exact method you used does not matter.