Report Plugins

FH_Requirements (entry-point)

Description

Add an instance of this function to a report plugin to specify the requirements of the plugin. If your report plugin does not have an FH_Requirements function, the plugin will use the default startup dialog with an Individual record selector. If the user opens the Report Options dialog in that case, the only tab showing will be the Page Layout tab.

Syntax

tblRequirements = FH_Requirements()

Parameters

none

Returns

tblRequirements: table: requirements of your plugin. All values are optional, and have defaults which apply if the value is not supplied. The table below gives the possible values you can set:

startup

String. Defaults to "default" if not supplied. Possible values are:

default = the default startup dialog is displayed
plugin = the startup dialog is implemented by the report plugin in a FH_Startup function.
options = the Report Options dialog is displayed as the startup dialog
none = there is no startup dialog. The report just opens.

record_type

String.

Many reports require the user to select one or more records. If you want your report to work like this, specify the 'record_type' here. Defaults to "INDI" if not supplied. The field specifies the tag of the record type required. For example, set record type to "INDI" for Individual records or "FAM" for Family records. The full list of available record tags are:

INDI = individual
FAM = family
SOUR = source
NOTE = note record
_PLAC = place record
_ADDR = address record
OBJE = media record
SUBM = submitter
SUBN = submission
REPO = repository
_RNOT = research note
_SRCT = source template

If you are using the default startup dialog (i.e. you have not provide an implementation of FH_Startup), the user will be prompted to select records of the required type. Also, once the report has opened, the user will be able to change the record selection by clicking 'Records' on the Report Window.

If your report does not require a record selection, set record_type to an empty string.

Reports that require a record selection are called 'record-driven reports'.

record_collection

Boolean. By default, in record-driven reports (see previous section), it is assumed that you want to produce one top-level section for each record that the user selects. To support this, Family Historian will call your implementation of FH_GetRecordSectionContent once for each record that the user selects. Sometimes however that's not what you want. Sometimes you may want to produce a report that is about a collection of records that the user selected, taken as a whole. In that case set 'record_collection' to true (the default, if not supplied, is false). If this setting is true, Family Historian will not call FH_GetRecordSectionContent. Instead your implementation of FH_GetMiscSectionContent will be called once for each miscellaneous section that your report requests (using your implementation of the FH_GetMiscSectionsRequired function), and the last parameter, 'reclist', will be a table containing a list of the selected records.

records_min

Integer. The minimum number of records the user may select. Defaults to 1 if not supplied. Ignored if the report does not require record selection (see 'record_type' above).

records_max

Integer. The maximum number of records the user may select. Defaults to -1 (no limit) if not supplied. Ignored if the report does not require record selection (see 'record_type' above).

title

String. The title to use for this report when it is included in a book. Defaults to the plugin name if not supplied. May contain an expression, such as "%INDI.NAME:ADORNED_FULL% (=LifeDates2())". If it does contain an expression, this must be appropriate for the record type (see 'record_type' above) of the report.

generations

Boolean. Defaults to false if not supplied. If you specify true for this value (note: no quotes around it!) the user will be prompted to specify the number of generations in the default startup dialog (if not overridden), and in the Report Options dialog main page. They will be able to choose a number or "All".

generations_default

String. Only applicable if you set generations equal to true. Defaults to "3" if not supplied. Specifies the default number of generations as a string. The reason that a string is needed rather than a number is that you can specify "all" if you wish. The value specified here will be the initial value for generations in your report, and the value that appears if the user clicks 'Restore Defaults' in Report Options.

options

String. Specifies the report-specific options required by your report.

When your report is displayed, the user will be able to choose (depending on the 'tabs' setting below) many of the standard options, normally available in Report Options. But you may also wish to specify your own options, in addition to these. There are two ways to do that. If you really need to, you can provide your own user options dialog and allow the user to choose options there. See FH_PromptUserOptions for more on this. That is not the normal, nor the recommended way of doing it. If at all possible, the preferred option is to specify the options you require in a text string here.

The text string allows you to specify as many distinct report options as you like using 'controls'. Each control can be:

an ordinary edit box, prefixed by a label
an edit box that will only accept numbers, prefixed by a label
a check box. Checkboxes do not have a separate label.
a dropdown list of items to select from, prefixed by a label.
an edit box with a dropdown list of suggested values, prefixed by a label.

In addition, you can also add plain text (e.g. as additional headings). Plain text is implemented by the static control type.

For each non-static control, you need to specify 5 parts. Static controls have only 4 parts. The parts are:

a name (for static controls only the name can be left blank - i.e. a static control can begin like this: "~|...")
a label
the control type: edit, integer, dropdownlist, dropdownedit, checkbox, static. For dropdownlists and dropdownedits, the dropdown item list is specified in brackets after the control type name, using a semicolon to separate items. e.g. "dropdownlist(Ancestors;Descendants;All Relatives)"
the default value (non-static controls only! For non-static controls, it can be blank but cannot be excluded altogether as it is for static controls)
spacing

The specification of each control starts with a tilde character (~). Values are separated by a vertical bar. You can have as many control as you like on each line. It is recommended to leave at least one space between control specifications, for improved readability. Terminate the last item (spacing) with a newline character (\n) if the control is the last on its line. Use the escape character (\) in front of any vertical bar that is part of the text and should not be treated as a separator.

The spacing part - for all controls except checkboxes and statics - is in the format:

a:b(c)

... where a is the width of the label in horizontal dialog units, b is the width of the interactive part of the control in horizontal dialog units, and c is the width of the gap after the control, in horizontal dialog units. Horizontal dialog units are approximately one-quarter of the average character width, of dialog text, using the dialog's current font.

The last part "(c)" is optional. You should leave it out if the control is the last on the current line.

Checkboxes and statics do not have a separate label, so for them the format for spacing is:

a(c)

... where a is the width of the checkbox or static in horizontal dialog units and c is the (optional) gap after it.

You can also leave vertical line gaps by inserting additional new line characters.

As well as the example below, see plugin report samples for more examples of how to specify report options.

tabs

String. Tabs required in report options as a comma-separated list. Options are:

pictures
sources
index
format
privacy
language

The Page Layout tab is always displayed (unless the report has been added to a book, in which case it will be displayed as part of book options). Also, there is no need to specify the main options tab (indeed you can't). If you have set generations to true, and/or if you have provided options in an options string, there will be a main tab with these, in Report Options. If not, there won't be.

Note: Regardless of what you specify here, the sources, index, privacy and language tabs will not display as options for your report if you add the report to a book, and click on the 'Settings' button, when editing book details, to view the report options. This is because sources, index, privacy and language are handled as part of book options, in a book context. The Format tab will display even in a book context, but shows reduced information. The font and heading style parts are configured within book options.

fonts

String. Comma-separated list of font types that the user should be able to configure in the Format tab of the Report Options dialog (i.e. the font types that are applicable to your report). The labels to use for each font category are those specified for the Style command in eFtf Syntax. For example, the string "secdata,seclabel" would mean that your report needs the "Section Data" and "Section Label" font types to be configurable by the user in Report Options.

This command has no effect on fonts which are explicitly specified by font name (e.g. using the Font command in Ftf Syntax). It only affects those fonts that the user can configure in the Format tab of Report Options. The use of some of these fonts (index heading, caption etc) are obvious. The applicability of others is less obvious. Some of them are the default fonts used in sections at various heading levels. A top-level section has heading level 1. If it has child sections, they have heading level 2. Their children have heading level 3. These sections can in turn have child sections, and so on indefinitely, but they will all be treated as heading level 3. The default font types used in the various sections are as follows:

A heading level 1 section will use "Heading Level 1" for its heading (by default), and will use "Section Data" by default for body text.
A heading level 2 section will use "Heading Level 2" for its heading (by default), and will use "Section Data" by default for body text.
A heading level 3 section will use "Heading Level 3" for its heading (by default), and will use "Subsection Data" by default for body text.

If your report includes a table with style "auto", the first column of the table will have the "Section Label" font by default, and all other columns will use the "Section Data" font by default. For more information, see eFtf Syntax.

Font types can also be explicitly selected using the eFTF Syntax Style command (see eFtf Syntax)

picture_categories

String. Comma-separated list of labels to use for picture categories in the Pictures tab of Report Options.

In the pictures tab of report options, a report can have up to 5 different categories of picture. Having different categories allows the user considerable flexibility in choice of size and location for pictures of each category. When designing your report, you can use these 5 categories in any way you like. If you do not specify a value for "picture_categories", 5 categories of picture will be listed in the Pictures tab of report options, and the default labels will be used. These are: "Individual", "Spouse Family", "Spouse", "Children" and "Other". The "picture_categories" setting allows you to specify the number of categories you require and the labels to use for them. You supply the labels in a comma-separated list (e.g. "Person,Parent,Grandparent"). The number of items in the list determines the number of categories shown to the user, up to a maximum of 5.

The last category, "Other", can include Facts, Places and Addresses. There is a separate section with 3 checkboxes which allow the user to choose which of these to include in the 'Other' category.

The 5 categories are stored in the report options file (.fhr suffix) using the fields described in the following table.

Picture Category in Order (with default labels)	Field Names
1. Individual	"Max Pics Individuals", "Pic Opts Individuals"
2. Spouse Family	"Max Pics Families", "Pic Opts Families"
3. Spouse	"Max Pics Spouses", "Pic Opts Spouses"
4. Children	"Max Pics Children", "Pic Opts Children"
5. Other	"Max Pics Other", "Pic Opts Other"

If none of the categories you supply are labelled 'Other', the section of the dialog with check boxes, which allow the user to choose which subcategories to include in 'Other' (i.e. "Facts", "Places" and "Addresses") will be hidden. The field names corresponding to the checkboxes for the 3 'Other categories' (if used) are called "Pic Facts", "Pic Places" and "Pic Addresses".

Important: If you change the label of any picture category, this does not affect the associated field name. If you opt to only have 2 categories, and rename the second category to be "Other" (say), the actual 'max' value chosen by the user for this second category will still be stored in the Report Options file using the field "Max Pics Families" - i.e. this is the field name used for the second category, however labelled. This could potentially make your script code confusing. For this reason, you are recommended to have a single mapping table where field name mappings are recorded, and isolated from the rest of the code.

heading_levels

Integer (1-3). Determines the number of "Hdg Style" lines displayed in the Format tab of Report Options.

column_indents

Integer (0-4). Determines the number of column indent values shown to the user in the Page Layout tab of Report Options. This will only be applicable if your report has one or more tables that use the ConfigColWidths flag (see eFtf Syntax). The values specified by the user are not the width of the columns, but the indentation of each column (including the first) from the left margin.

column_gap

Boolean. If you specified a column_indents value greater than 1, column_gap is treated as true automatically. If column_gap is set to true, the 'Gap' field in the 'Column Indents' section of the Page Layout tab of Diagram Options, is displayed to the user. This gap field is used in any table that has the ConfigColWidths flag. It is also used if even if the ConfigColWidths flag is not set, if the ConfigColGap flag is specified (see eFtf Syntax).

para_indent

Boolean. Set this to true if your report uses any para-indents (see eFtf Syntax). This will cause the "Para. Indent" setting to be visible in the Page Layout tab of Report Options, allowing the user to specify the width of para-indents.

Example

-- Add this entry-point function to your report plugin to specify its requirements
function FH_Requirements()
	local t = {};

	-- default startup options
	t.record_type = "INDI";	-- ignored if FH_Startup is overridden.  Specifies the record type of the record selector
	t.generations = false;		-- ignored if FH_Startup is overridden.  Do you want the default startup dlg to prompt for no. of gens?

	-- report options dialog requirements
	t.options = 	"~title|Title:|edit||32:60(20) ~alt_title|Alt. Title:|edit||32:60\n" ..
			"~count|Number:|integer|6|32:28\n" ..
			"\n" ..
			"\n" ..
			"~|MORE STUFF!|static|50\n" ..
			"~fruit|Fruit:|dropdownlist(Apples;Oranges;Bananas;Cherries)|Apples|50:49\n" ..
			"~country|Country:|dropdownedit(America;France;Germany;UK)|Germany|50:49\n" ..
			"~notes|Include Notes|checkbox|true|70(20) ~places|Include Places|checkbox|false|70(20) ~occups|Include Occupations|checkbox|false|80\n" ..
			"~rels|Relatives:|dropdownlist(Ancestors;Descendants;All Relatives)|Ancestors|41:70";
	t.tabs = "sources,index,pictures,format";  -- report options tabs required (may not show in rpt opts when report is part of a book)
	t.fonts = "hdg1,hdg2,hdg3,secdata,seclabel,sublabel";	-- fonts shown in format tab of report options
	t.picture_categories = "Individuals";		-- max 5 labels for picture categories in pictures tab.  Defaults (all 5) if not supplied
	t.heading_levels = 3;		-- affects no. of heading levels shown in format tab of report options
	t.column_indents = 4;		-- no. of column indent value required in layout tab of rpt opts
	t.para_indent = true;		-- para indent value required in layout tab of rpt opts

	return t;
end