Source-Driven Data Entry Plugins

How to Write Source-Driven Data Entry Plugins

With very few exceptions, the starting-point for a source-driven data entry plugin is a prepared citation which the user has created in the Citation Window.  A prepared citation is very similar to an ordinary citation, so let us quickly review what an ordinary citation is.  In the real world, a citation is a little superscript that appears immediately after some text in a document, which is linked to a footnote or endnote, which in turn provides enough information for the user to be able to locate the source of the factual claims made in the text.  Within Family Historian, a citation is the software correlate of this - the thing that makes real-world citations possible.  More specifically, it is a link from an ordinary item of data to a Source record.  The link may itself have various items of data (fields) attached to it.  For example, it you were citing a book, you would probably have a Source record for the book.  If the citation included the page number within the book, the page number would typically be stored as a field on the link (rather than as a field on the Source record itself).

A prepared citation is the same thing except with one difference.  Instead of the link being attached to an actual item of real data, a prepared citation is kept in the Header record of a Family Historian project.  It is a real link, to a real Source record.  But it will never be used to generate any real-world citations in documents.  The purpose of a prepared citation, as the name suggests, is to allow the user to prepare a citation, in advance of actually deploying it.

To access the prepared citation if there is one (every project has at most one), a plugin could locate it in the ordinary way within the Header record.  The tag for a header record is 'HEAD'. The prepared citation is kept within a tag called '_PCIT' within the header record.  And the actual link's tag is 'SOUR' (the same tag as the Source record itself).  So, for example, the following code could be used to locate the prepared citation:

If this code executes, the piPc data item will reference the prepared citation source link, or be NULL if there isn't one.  From then on, you could navigate around the citation to access all fields linked to it, or access the Source record that it is linked to.  The Source record itself contains a link to the Source Template record that it is associated with in its '_SRCT' child field (this field will be blank if it's a generic Source record).

To make life easier, a special Lua module, called fhutils, is included as part of the Family Historian API.  This module implements an object called PCite, which represents a prepared citation.  To load a prepared citation, you need only call the LoadPreparedCitation module function, which returns a PCIte object.  The PCite object provides methods which allow you to easily check that the Prepared Citation contains the various metafields (fields defined in Source Template records) you were expecting, and to retrieve the values as required.  The fhutils module also contains other useful functions for performing various tasks.

See The fhUtils Module to learn more.