functions
fhCreateItem
Description
Creates a data item - either a record or a child item - and returns an item pointer to it.
Note: If this function is called by a plugin running in the Plugin Editor/Debugger in Debug Mode, a warning message will be output to the Output pane if the function returns NULL.
To create a new custom fact type, use the fhGetFactTag
function with the bCreateIfNone parameter set to
true. To create a new type of flag (either a record flag or a fact
flag) use the fhGetFlagTag
function, again with the bCreateIfNone parameter set
to true. In both cases, however, once you have created the
new item type (new type of fact or new type of flag), you can
use fhCreateItem to create actual instances of that item type.
Syntax
ptrItem = fhCreateItem(strTagOrShortcut [, ptrParent [, bReuseEmpties]])
Parameters
- strTagOrShortcut
- String: Tag of Item to create, or shortcut of Item to create. Support for shortcuts was introduced in version 7.0. Currently shortcuts are only supported for metafields. For all other item types, you must use a tag. For metafields however, you cannot use a tag and must use a shortcut - see the discussion of Metafields and Shortcuts below.
- ptrParent
- Item Pointer (optional). Must be NULL or omitted if creating a record item. If creating a child item, this must point to its parent item.
- bReuseEmpties
- boolean (optional). From version 5.0.2. Default is false. If true, and if there is an 'empty' data item of the required type (no value and no child items), will return a pointer to this data item instead of creating a new one. Has no effect when creating record items or metafields. If you are creating a metafield, an empty metafield that matches the specified shortcut, will always be re-used, whether or not this flag is set.
Returns
- ptrItem
- Item Pointer: for the created Item, or a NULL pointer if the
create fails for any reason.
Metafields and Shortcuts
Metafields are a special kind of field that can be defined and created on an as-needed basis. They all have the same tag ("_FIELD"), but this tag cannot be used to create a metafield. Instead you have to use a shortcut.
Family Historian metafields are used to hold the field data specified by Source Templates. These fields are created either as children of Source records, or as children of links to Source records (citations). Every metafield needs a field definition, which specifies the type of data that the metafield can hold, and other aspects of it. Family Historian metafields can have the following data types: text, name, date, place, address, repository, enumeration and URL. The field definitions are stored as fields within Source Template records. Source records have a field called 'Template' (with tag '_SRCT') which can store a link to a Source Template record. A Source record which has such a link is called a templated Source record (as opposed to a generic or free form Source record which has no such link). Before you can create a metafield for a Source record, or for a link to a Source record, the Source record itself must be linked to a Source Template record. When you create the metafield for the Source record, you must specify a metafield shortcut. The value of this shortcut must match a field definition within the linked Source Template record. If no field definition matches the metafield shortcut, or if the Source record is not linked to a Source Template record, the function will fail.
A shortcut to a metafield normally looks something like this: "~TX-DOCUMENT_TITLE". The first character (a tilde) indicates that what follows is a shortcut. The next 3 characters specify the field type. The values are:
| Field Type |
3-letter Type Prefix |
| Text |
TX- |
| Name |
NM- |
| Date |
DT- |
| Place |
PL- |
| Address |
AD- |
| Repository |
RP- |
| Enumeration |
EN- |
| URL |
UL- |
The remainder of the shortcut text is the code for the field definition (e.g. "DOCUMENT_TITLE" in our example) which is normally the field label, with spaces and non-alphanumeric characters replaced by an underscore.
Once you have created a metafield, you can get and set its value in the usual way. For example, you can use fhGetValueAsText and fhSetValueAsText to get and set the values of Text, Name, Place and Enumeration metafields. You can use fhGetValueAsDate and fhSetValueAsDate to get and set the values of Date metafields. And you can use fhGetValueAsLink and fhSetValueAsLink to get and set the values of Repository metafields.
It is possible, though not usually a good idea, to clear or delete the link from a Source record to a Source Template record after you have created metafields for the Source record or for one or more links to it. If you do this, the metafields will not be automatically deleted. They will be visible on the All tab of the Property Box, for the Source record or citation in question, as orphaned metafields.
Metafields can be deleted like any other field, using the fhDeleteItem function.
Creating Source Records of Different Types
We saw in the previous section that what makes a Source record a templated Source record is that it has a link (using the _SRCT tag) to a Source Template record. Free form and generic Source records have no such link. So if you want to create a templated Source record, you need to create this link. If, for whatever reason, this link were somehow deleted, the Source record would revert to being a generic Source record. If it had metafields, it would still be a generic Source records. In that case it would be a generic Source record with orphaned metafields (see previous section).
To create a free form Source record, you need to add a child item to the record item with tag "_FREE". This is a hidden tag. Users will not see it - not even in the 'All' tab of the Property Box. If a Source record has a '_FREE' tag (and doesn't have a '_SRCT' tag), it is a free form Source record.
A generic Source record is simply any Source record which has no _SRCT link to a Source Template record, and no _FREE child tag.
With free form sources, users can specify footnotes, short footnotes and bibliography entries. These are stored in child fields within the Source record, with tags _FOOT, _SHRT, and _BIBL respectively. These fields can contain style codes for enabling or disabling italics, bold and underline (<i>,</i>,<b>,</b>,<u>,and </u>).
Example
Create a new Family Record and attach a Husband.
ptrFam = fhCreateItem("FAM") -- now create the family record ptrLink = fhCreateItem("HUSB", ptrFam ) -- create a HUSB field in the family record fhSetValueAsLink(ptrLink, ptrDad)
See Create Family Script for a full example.