The Family Historian API

eFTF Syntax

Introduction

eFTF syntax is a superset of FTF syntax.  The name stands for 'Enhanced FTF'.  It incorporates all of the features of FTF syntax, but adds some additional ones.  eFTF syntax is only used in reports, books and website generation.  Before reading this page, you should first familiarise yourself with the FTF Syntax page as everything discussed in that page is applicable here too.  This page only discusses those features of eFTF syntax which are different from (and not supported by) ordinary FTF syntax.

For the convenience of plugin authors, there is also a text-only variant of eFTF syntax: tFTF syntax.  This is only currently supported in the context of the SetText method for RichText objects.

Enhanced Style Syntax

style
The <style=(params)> command allows you to specify a named style.  It takes one parameter which is the style name.  Use the </style> command to revert to the default style for the current context.  A named style is a combination of the following style attributes: bold, italic, underline, strike-out, text colour, font, and font size. The user can configure named styles in Report Options (in the Font area of the Format tab).  The style name must be one of the following:
hdg1
 Heading Level 1
hdg2
 Heading Level 2
hdg3
 Heading Level 3
seclabel
 Section Label
secdata
 Section Data
sublabel
 Subsection Label
subdata
 Subsection Data
caption
 Caption
indexhdg
 Index Heading
indexline
 Index Line

A style command can be used anywhere within a paragraph, but is most commonly used for an entire paragraph. For example: <style=hdg3>This entire paragraph uses heading level 3 style.</style>

Enhanced Formatting Options

multi-paragraph bullet
Ordinary bullets in FTF syntax (where a paragraph begins with an asterisk), apply only to one paragraph.  Sometimes you may want a bullet that applies to multiple paragraphs.  In that case, the text of all paragraphs is indented and a bullet is displayed next to the first line of the first paragraph only.  Use the <bullet> command (no parameters) at the start of the first paragraph.  Use the </bullet> command to end it.  Normally the </bullet> command will appear at the end of the last paragraph, but it can in fact appear anywhere within the last paragraph.

Example:

<bullet>This is line 1.  It has a bullet to the left of it.
This is line 2.  It has no bullet, but is left-aligned with the text in line 1.</bullet>
<bullet>This is line 3.   It has a bullet to the left of it.
This is line 4.  It has no bullet but is left-aligned with the text in all the other lines.</bullet>

body indent
An ordinary indent in FTF syntax applies to only one paragraph or table.  Using the <body-indent=(param)> command you can specify an indentation that applies to an entire section of a report.  It remains in operation until another body-indent command is encountered, or the end of the document is reached.   The sole parameter is a number that specifies the number of paragraph indents of the body indent.  The size of paragraph indents can be specified by the user in the Page Layout tab of Report Options.  Use <body-indent=0> to cancel a body indent.  Values are not cumulative, but any ordinary paragraph formatting will apply within the context of the body indent.  The body-indent command normally appears on a line of its own.  The line on which it appears is treated as a hidden line. 

Example:

Line 1.  This is line is not indented.
<body-indent=2>
Line 2  This line appears immediately below Line 1 and is indented by 2 paragraph indents.
Line 3. This line is also indented by 2 paragraph indents.
<body-indent=0>
Line 4.  This line is not indented but appears immediately below Line 3.

Enhanced Table Syntax

With FTF syntax, tables cannot contain other tables within them.  With eFTF syntax, a table can contain tables in its cells (but those tables cannot contain any further tables within them).  eFTF syntax also allows you to merge adjacent cells within a row.  The table command in FTF syntax has only one parameter.  In eFTF syntax, a table command can have up to 3 parameters.

merge cells
To merge cells within a row, simply put the cell separator character - the vertical bar - within angle brackets like this: <|>.  This removes the separation between the cells.  For example:

<table="800|800|800">
<row> ordinary (unmerged) cell | ordinary (unmerged) cell | ordinary (unmerged) cell </row>
<row> ordinary (unmerged) cell  | 2 cells merged <|></row>
<row> 2 cells merged <|> | ordinary (unmerged) cell </row>
<row> 3 cells merged <|><|></row>
</table>

table command parameters
The <table=(params>) command can have up to 3 parameters in eFTF syntax.  The parameters are the column specification, the table style and table flags. 

The first parameter, column specification, is the same in eFTF syntax as the column specification in FTF syntax (that is, for specifying the number of columns and their widths), but there are some extra unit types that you can use to specify the column widths.  If the unit is not specified, it defaults to twips.  A twip is one-twentieth of a point or 1/1440 of an inch (a point is 1/72 of an inch).  In eFTF you can also specify the unit as 'em'  (average character width of the current font), 'tab' (no. of tab widths), or '%' (percentage of the available page width).  You can use different units with different columns if you wish.  Decimal points are supported (up to 3 significant digits) for ems and percentages.  If you use 'tab' as a unit, bear in mind that tab widths are configurable in Page Layout of Diagram Options, by the user.  If you fail to specify a column width at all, it defaults to 800 twips (unless you specify 'configcolindents' as a flag - see below).  If you specify one or more column widths as 'auto' (no value - just 'auto'), these columns will be adjusted to fit the remaining available space, after the width of all other columns has been calculated.  So, for example, this is a value column specification for a table with 6 columns: "3.25em|14|23%|auto|1tab|auto".  The second column is 14 twips wide.  The two column widths marked 'auto' will be the same size and will share all remaining space once other column widths have been calculated.  Finally, if you set the 'configcolindents' flag in the table flags specification, this affects the interpretation of the column specification - see table flags below.
The 2nd parameter for the table command is table style.  This allows you to specify a default style that applies to the entire table.  The possible values for this are the values for the <style=(params)> command (see "Enhanced Style Syntax" above).  Additionally, you can also specify 'autostyle' as the table style.  In that case, the default style depends on the heading level.  If the heading level is 1 (highest) or 2 (second highest), the default style used for the first column will be 'seclabel', and 'secdata' will be used for all other columns.  If the heading level is 3 or greater, the default style used for the first column will be 'sublabel', and 'subdata' will be used for all other columns

The 3rd parameter for the table command is table flags.  The following flag values are supported:
noborder
 Unless this flag is set, there is a border round the table, and each cell.  Setting this flag removes all of these borders.

Note: the last column of a table that has no border is normally of variable width.  The text width will be automatically adjusted to accommodate any pictures that may be displayed on the right-hand side.  This does not happen with tables that have a border.  Consequently setting the noborder option is often the preferred choice.
responsive Has no effect unless the report is saved as a page in HTML.  In that case, the table will be implemented in a way that makes the page responsive - i.e. it will adjust automatically and find new ways to layout the data, if the page is viewed on a tablet, or smart phone, where space is limited.

Note: This flag is ignored (and not needed) if the class is 'deflist' (see below).
configcolindents If this flag is set, and if the column widths are not specified in the column specification (i.e. the column specification consists of vertical bars alone, indicating the number of columns but not their widths), the start of each column is given by the column indent values of the Page Layout tab of Diagram Options (for up to 4 columns).  If your table has fewer than 4 columns, the end position of the last column is also determined by the column indent values.  For example, if your table has one col, its start position will be given by Col Indent 1.  Its end position will be given by Col Indent 2.  If your table has two columns, Col Indent 1 gives the start of the first column, Col Indent 2 gives the start of the second column, and Col Indent 3 gives the end of the second column.  And so on.

Column indents are configurable by the user in Report Options, Page Layout tab.

If you wish, you can also specify some column widths but leave others unspecified.  Once the width has been specified for a column in the table, the column indent values will thereafter no longer be used for later columns in the same table.  So, for example, if you specified the column widths with "|600|auto", the column indents of the first two columns would be taken from Page Layouts.  The second column width would be 600 twips, and the last column would autofit the available space.  If instead you had used "|600|" as the column specification, the last column would have been given the normal default column width, which is 800 twips.

If you specify the column width of the first column, the first column would start at the first column indent as specified in the Page Layout tab, but thereafter no other column indents would be used.
configcolgap By default, if a table has a border (i.e. the noborder flag is not set), there will be a margin of 108 twips between the text and the border, to the left and the right of the text in each cell.  You can override this by setting the configcolgap flag.  In that case, the 'Gap' value, specified in the Page Layout tab of Diagram Options, will be used as the cell margin.

You can also set configcolgap flag even if the table has no border.  In that case, the 'Gap' value will be used as the cell margin - but only on the right edge of each allocated column (except the last which doesn't need a margin).  The left edge of each cell is treated as having no margin.

The 'Gap' value will also be used as cell margin, whether or not the configcolgap flag is also set, if both the configcolwidths and noborder flags are set.
dontsplitrows
 Rows are not split across page ends, if this can be avoided.
deflist
 The deflist flag has no effect except when a report is saved as a web page (in HTML format).  In that case, it affects the HTML used.  The table will be saved as an html DefList.

The deflist flag is incompatible with the configcolwidths flag, and is ignored if the latter is set.  If the deflist flag is enabled, the responsive flag has no effect.
Table flags must be specified with double quotes.  If you specify more than one value, the different values must be separated by spaces.

For example, this 3-column table (with 2nd and 3rd cells merged in each row) is a borderless table, table with column widths that are configurable by the user, and that will adjust its layout automatically (be 'responsive') if viewed as a web page on a phone or tablet:

<table="||auto","autostyle","noborder configcolwidths responsive">
<row> Name: | Ian Stephen Munro <|></row>
<row> Sex: | Male <|></row>
</table>

Indexing Syntax

index
The Index command is used in reports and books, when generating the index for the report or book.  To insert an index entry anywhere in the text, use the <index=(param)> command.  The single parameter is the text as you want it to appear in the index.  For example: <index="Munro, Ian Stephen">Ian Munro was born on January 5th 1953.  The index at the end of the report or book will have an entry "Munro, Ian Stephen" followed by the page number of the page of the text on which the index marker is located.  The index marker is always deemed to be located on the page of the text that immediately follows it.