Main Help → GENerel Introduction → Template Example
Consider an INDIVIDUAL Record with the following raw GEDCOM data:
0 @I11@ INDI 1 NAME John /Smith/ 1 SEX M 1 BIRT 2 DATE 06 May 1892 2 PLAC Philadelphia, PA 1 FAMS @F124@ 1 OCCU Blacksmith
GEDCOM files are organized into a series of text lines where each line begins in a level number. These level numbers divide the file into GEDCOM structures where a structure is a collection of lines beginning on one level number (the first line in the structure) and all subsequent lines with a higher line level. All data within a single GEDCOM Structure are logically related. In the above example, the entire record is a GEDCOM structure. It begins with the first line (0 @I11@ INDI) and includes all other lines because they are all at a higher level number. But a structure can begin on other lines too. The line 1 NAME John /Smith/ is a single line name structure. It begins at level 1 and there are no subsequent higher-level lines. In contrast, the birth structure begins with the line 1 BIRT and includes the two subsequent lines at level 2.
When GEDitCOM II is asked to display any GEDCOM Record, it breaks the record into its GEDCOM Structures and looks for a template which gives the instructions on how to display each type of data. The first GEDCOM Structure found is always the full GEDCOM Record itself. For this structure, which is the entire record, GEDitCOM II will look for a special record-editing template called "INDI Record Editing" which is the template for how to display INDIVIDUAL Records (INDI is the GEDCOM tag for INDIVIDUAL Records). GEDitCOM II will execute that template with the data from the current record as input data to the template.
A simple, but possible, "INDI Record Editing" template could contain the GENerel Commands:
Show NAME Show SEX Show BIRT Show DEAT ShowAll FAMS ShowAll FAMC
The Show command is a template command that tells GEDitCOM II to show the data in the NAME GEDCOM Structure. The argument to this template command is a GEDCOM tag name.
When GEDitCOM II encounters a Show command, it will look for a GEDCOM Structure in the currently loaded data with a GEDCOM tag of NAME in the first line. If it finds such a structure, it will load that data and look for a template called "(Tag_Name) Editing" where (Tag_Name) is the GEDCOM tag name in the Show command; here GEDitCOM II will look for a "NAME Editing" template. This template will have instructions on how to display data in a NAME GEDCOM Structure.
The above "INDI Record Editing" template does not define any cells. Although record editing templates may define cells, in this example all cells get defined in the "(Tag_Name) Editing" templates. Beginning with the first Show command, GEDitCOM II will extract all the data in the NAME GEDCOM Structure. Here that data is just the single line.
1 NAME John /Smith/
In other records the Personal Name Structure might include other data such as a nickname, sources, notes, or multimedia. A possible template for NAME data could be
! label for the field
cell static local(@tag)&":"
set width 200 alignment right
! edit field with value
cell EditName
set Width -1 Offset -2
set help local("Enter the person's name")
The first line beginning with "!" is a comment. All lines beginning in "!" are ignored and can be used to comment your templates. Blank lines are also ignored and can be inserted for easier reading.
The next two lines define a cell to contain a text label for the field. The cell static command sets the cell to display text and its argument is the text label to display. In good browser styles, you should never hard-code specific language text in templates. Instead, you should retrieve a string from the browser style's string properties. By default, the strings are found in the English properties, but if a user chooses a different language, the string many come from a different language instead. Here the function local(@tag) retrieves a string. First, @tag is a GEDCOM expression that that can be used to determine the GEDCOM tag for any template. Here @tag would evaluate to "NAME". Next passing "NAME" to the local() function will retrieve the string corresponding to the key "NAME". The English strings may simply return "Name". A French set of strings might return "Nom" instead.
The set command sets cell properties; here the cell width and text alignment are set. Notice that this cell has no height. When no height is specified, the default cell height is used. Notice also that no font style is specified. When no font style is specified, the cell will use the default font for its cell type.
The remaining lines define a second cell. First, the cell EditName command sets a cell where the user can edit one line of text. For such a cell GEDitCOM II will display an editing field where the user can enter a name or change the current name. An EditName cell is a special cell for editing names and taking care of the slashes used to specify surnames in GEDCOM files. The slashes will be removed before displaying the name and will be reinserted when the data is saved. Most other templates will use EditValue cells for generic editing of one line of text.
The last two commands set the dimensions of the cell and define a help string. The help text is displayed if the user hovers over the cell with the mouse. Again, rather than hard code text, good browser styles will use a key to look up a string in any language for the help. As done here, the key can be the actual English text for the help string. This method makes it easier to translate strings to a new language. Furthermore, if no string is found, local() will return the string itself and thus this template would revert to at least displaying clear help in English. Setting the width to -1 means to extend the cell to the right edge of the display area. The offset is a vertical offset that is sometimes needed to align the text in different classes of cells.
The "SEX Editing" template may be similar to the "NAME Editing" template, but you should only display the sex and not allow the user to change it in an editing field. If the user changes sex in an editing field, it could corrupt links to family records as a spouse. The solution to allow changing the sex is set up a LinkButton cell linked to the Attach→Changed Sex menu command.
Some new things occur when GEDitCOM II proceeds to the BIRT and DEAT GEDCOM Structures. On finding the Show BIRT command GEDitCOM II will load all the data in the BIRT structure including the subordinate data at higher level numbers. Here that data is
1 BIRT 2 DATE 06 May 1892 2 PLAC Philadelphia, PA
GEDitCOM II will interpret this data using the "BIRT Editing" template. A possible "BIRT Editing" template could be
! label for the field NewLine cell static local(@tag)&":" set tabwidth 1 alignment right ! show date and place Show DATE Show PLAC
The NewLine command starts a new line to insure that the birth record will begin on a new table row. The next two commands define a text cell with a label. As in the "NAME Editing" template, the label is taken from a keyed string based on the GEDCOM tag, which is now "BIRT".
The last two lines call more templates to display the subordinate data in the BIRT structure that give the date and place of the birth. These templates will not be given here, but they would probably be similar to the "NAME Editing" template by having one label cell and one editing cell to let the user edit the date and place of birth (although for dates, you would use the special type of editing cell for dates called an EditDate cell). You should think of each template as providing formatting and editing capabilities for a single GEDCOM line which corresponds to the first line of a GEDCOM Structure. If that structure has more lines and you would like to allow editing, the first template must call other templates for that data using Show or ShowAll commands.
The next command in the "INDI Record Editing" template is Show DEAT, but this example record has no death data. When GEDitCOM II gets a Show command and there is no corresponding GEDCOM Structure in the currently loaded data, GEDitCOM II will call the relevant template anyway with empty data. This procedure can be used to place empty editing cells in your window to provide a place for entering new information once it is known.
The next command in the "INDI Record Editing" template is ShowAll FAMS where FAMS is a Spouse To Family Link that provides a link from this individual to a FAMILY Record (GEDCOM record type FAM) where he is the husband. ShowAll is like Show except that it will show all the FAMS data structures (including showing nothing if there are none) while Show will always show exactly one (even if there are none or more than one). Here GEDitCOM II will extract the one line in the FAMS structure.
1 FAMS @F124@
and interpret this data using the "FAMS Editing" template. The value of the FAMS tag is a GEDCOM Record Pointer. In this case the pointer @F124@ is a link to a FAMILY Record. Templates for structures that link to other records should usually create a button that will open the linked record when clicked. For FAMS templates, it might be nice to have an additional button to open the wife's INDIVIDUAL Record when that button is clicked. A possible two-button template could be:
! marriage button
NewLine
cell LinkButton local("Marriage Record")
set RecordLink @contents
set help local("Click to see family record")
cell static
set tabwidth alignment right
#sex=@this.SEX
if #sex="F"
text local("HUSB")&":"
#spouse=@contents.HUSB
else
text local("WIFE")&":"
#spouse=@contents.WIFE
endif
if #spouse is validlink
cell LinkButton @#spouse.NAME
RecordLink #spouse
else
cell static local("Unknown")
endif
The first section defines a button to link to a FAMILY Record that has John Smith as the husband. The cell is a LinkButton; the text of the button is a keyed string using "Marriage Record". The RecordLink property links the button to the record such that when the user clicks the button, the FAMILY Record will open. The argument to the link command is the contents of the FAMS line which is extracted using a GEDCOM expression. A GEDCOM expression begins with an "@" sign and has a series of tags or special words to extract data from GEDCOM records. They are needed often in templates. The GEDCOM expression @contents extracts the data for the first line of data being formatted in the current template. Here @contents evaluates to @F124@. Because @F124@ is a valid link to a FAMILY Record, a click on the defined button will open the correct FAMILY Record.
The second section defines a button that links to John Smith's wife's record. For this editing template to work for males and females, it is best to make it general. The line #sex=@this.SEX uses a GEDCOM expression to extract the sex of the current individual and load it into the variable #sex. If sex is "F" for female, a label keyed from "HUSB" is printed and the variable #spouse is set to the record ID of the husband's record (found using a GEDCOM expression). The complementary settings are made if the person is a female. Next a LinkButton is created to display the name of the spouse and to link to the spouse's individual record if the button is clicked. If the spouse is not known, the #spouse variable will not have a valid link. The conditional checks if the link is valid. If the link is not valid, the LinkButton is replaced by a static label stating the spouse is unknown.
The next command in the "INDI Record Editing" template is ShowAll FAMC where FAMC is a Child to Family Link that provides a link from this individual to a FAMILY Record where he is a child. John Smith's INDIVIDUAL Record has no FAMC lines. Because ShowAll will show all FAMC lines (including possibly none), in this example, the ShowAll FAMC command will show nothing.
The "INDI Record Editing" template is done, but there is still one remaining GEDCOM Structure in the example INDIVIDUAL Record. The one remaining structure is
1 OCCU Blacksmith
When there is genealogical data remaining after finishing a template (either a Record Editing template or a (Tag_Name) Editing template), GEDitCOM II will, by default, read through the remaining data structures and for each data structure look for the appropriate "(Tag_Name) Editing" template and try to display the remaining data. In effect, it will automatically execute a ShowAll command for all unread GEDCOM Structures.
The default treatment for dealing with remaining GEDCOM Structures can be altered by using the HideExcess command. There may also be times you want to show all excess data but then still be able to add more cells after the last data is output. This problem can be solved by using the ShowAll command with no arguments.
If no template is found for some loaded GEDCOM Structure, GEDitCOM II will instead use the default template named "_Unknown_ Editing" to display a GEDOM structure or the default template named "_Unknown_ Record Editing" to display a full record. All browser styles have these templates and you can write them to handle unexpected data or records. If, for example, you want GEDitCOM II to ignore all genealogical data that you do not specifically include in your templates, the "_Unknown_ Editing" template can be empty or display nothing.