Special Plugin Types

Source-Driven Data Entry Plugins

A source-driven data entry plugin is a special kind of plugin that can be run from the Citation Window, when it is displaying a Source record and a prepared citation.  The actual function of this type of plugin is variable, but typically it might facilitate entering data extracted from a source, and attaching citations to the entered data.  Unlike report plugins and language plugins, source-driven data entry plugins have no special entry-points and are not read-only.  They can add, update and delete fields and records.

If you are not familiar with source templates or prepared citations, please see the main Help for more information on these.

A source-driven data entry plugin can be designed to work with any kind of Source, but more usually will be designed to work with either a generic source, or with one or more types of templated source (a source linked to a Source Template record), or with a combination of both.

Source-driven data entry plugins are created in the Plugin window, like a normal plugin.  The key important difference is that they must have a header, and the '@Type' field of the header, must be 'Source-driven data entry'.  In addition to the '@Type' field however, there must also be a '@Subtype' field.  The subtype field contains a list of the source templates that the plugin is designed to support, each within double quotes, and comma-separated.  If the plugin can handle generic sources, the list should include (or consist of) the word 'generic', without quotes.  If the plugin is designed to support all sources, the @Subtype value should consist of the word 'all', again without quotes.  For example, the following header would specify a source plugin that is designed to support generic sources, and sources linked to the "Civil Registration Certificate" and "Church Register" source templates:

      --[[
      @Type: Source-driven data entry
      @Subtype: generic,"Civil Registration Certificate","Church Register"
      ]]

A typical scenario of use, might be this:

The user wants to add a marriage certificate.  This means, typically, that they want to create a source record for the marriage certificate.  They also want to add all the information contained within the marriage certificate, and to add a source citation for each item of information added, back to the new source record.  They might also want to attach citations to the same Source record, to facts that they have already recorded, which are confirmed by the marriage certificate.  There are various ways that they could set about doing all of this, but for present purposes, we will assume that they click on the Start button on the main application toolbar, and then choose Create Source from Template / Prepare Citation from the dropdown menu.  Assuming they already have source templates installed in the current project, they will be presented with a list of templates.  Let us suppose that they pick 'Civil Registration Certificate' and click Create Source. At this point, the Citation Window will be displayed showing the new Source record and a prepared citation.  Along the bottom of the Citation Window will be 3 buttons: Enable Automatic, Copy Citation, and Data Entry Assistant.  If the user clicks on the last of these, a dropdown menu will be displayed, listing all the source-driven data entry plugins that can be run in the current context.

At this point, a new Source record, linked to the Civil Registration Certificate Source Template record has been created, and a very minimal prepared citation to the new Source record has also been created.  The user might enter Source details, and possibly also prepared citation details (possibly even including Text from Source, or media for either the citation or Source record, or both).  Or the user might just click on the Data Entry Assistant button and run a plugin immediately.  The plugin could be designed to put up a form, inviting the user to enter source data there, with the intention of populating source and/or citation fields.  Or it could be designed on the assumption that the user has already done this, and it wants to use this data to add facts and citations.  Here are just some of the things it could do:
Before it does anything, however, it should put up a message, telling the user what it is about to do, and if appropriate, what it expects the user to have already done.  It should give the user the opportunity to cancel.  Also, it should check the circumstances in which it is being called, and inform the user if information it needs is missing.  If it is run from the Citation Window, the prepared citation field in the header (which also contains a pointer to the relevant source record) will not be blank; but if it is run from the Plugin window, that information may be blank.  The plugin must not make any assumptions.  It needs to check everything.  If it is designed to work with a particular source template, it cannot assume that the user's Source Template record is anything like the one that it is expecting.  If it is expecting, and requiring, that the Source Template consists of particular field definitions, with particular field types, it must check that these are there, and match expectations.  If they don't, it must inform the user what the problem is, and take appropriate action (which will normally mean exiting without doing anything further).

Crucially, the plugin must be designed so that if the user, for whatever reason (or by mistake), runs it more than once, nothing bad will happen.  If possible, it should detect that it has already been run and do nothing other than put up a message to the user, telling them that no changes have been made, because everything has already been done.

If the user opts not to cancel, but to proceed, the plugin should make whatever data changes it needs to make, and inform the user, when it has finished, that it has completed successfully (or put out an appropriate error message if it fails).  If possible, the message to the user should summarize what the plugin has done.