Functions (all)

GetContextItem

Function Name:
GetContextItem
Description:
This function is depreciated - that is, it is no longer needed and you are recommended not to use it.  You are recommended to use an appropriate contextual data reference instead (see Understanding Data References to learn about 'contextual data references').  The GetContextItem function was designed to allow a reference to a data item to be inserted in a particular context (such as the current witness, in a witness sentence template). Typically this function was used in conjunction with the GetField or GetFieldText functions.  However, using a contextual data reference instead achieves the same result with less complexity.
Minimum FH Version:
6
No. of Parameters:
1
Return Type:
Data item
Parameter 1:

Value that determines the data item required.  This function will only return references to data items in the specified contexts of use.  In all other contexts, nothing will be returned.

WITNESS
This value can only be used when constructing sentences for use in narrative reports; in fact it will only return a value if the sentence is a sentence for a Witness to an event (see "Witness Roles" for any given fact definition).  The value returned is the current Witness.  For example, if you have recorded the bridesmaids at a wedding, a person, Mary, might be described like this within a narrative report: "She was a bridesmaid at the marriage of John Smith and Susan Jones in Paris, in May 1957".  The witness sentence template for the role 'bridesmaid', might look like this: "{individual} was a bridesmaid at the marriage of {principals} {place} {date}".  Suppose you wish to insert her given name.  You could use the expression {=GetFieldText(GetContextItem(WITNESS),"%~.NAME:GIVEN%")} to do that.  For example, the sentence template might look like this:

The bridesmaid's first name was {=GetFieldText(GetContextItem(WITNESS),"%~.NAME:GIVEN%")}

Note that the use of relative data references - that is, data references which start with a single '~' character on its own - is permitted with the GetFieldText function.

However, you can achieve the same result more easily using a contextual data reference - that is, {%CUR~WITN>NAME:GIVEN%} - which is simpler.  The sentence would then look like this:

The bridesmaid's first name was {%CUR~WITN>NAME:GIVEN%}

When used in sentence templates, both functions and data references must be enclosed in curly brackets.

WITNESS_LINK
This value can also only be used when constructing witness sentences for use in narrative reports.  It is similar to WITNESS above, but whereas that parameter will cause the function to return a reference to the current witness, WITNESS_LINK will return a reference to the current link to this witness, from within the Fact data item.  This is useful because it means that you can access sub-fields for the link - which include role, note and source citations.  For example, to reference the note for the current witness you could use this expression:  {=GetFieldText(GetContextItem(WITNESS_LINK),"%~.NOTE2%")}".  However, again, you can use a contextual data reference as an alternative and better way of achieving the same thing.  For example, {%CUR~WITN.NOTE2%} can be used to  reference the same note.


Example (narrative sentence for witness):

The witness's first name was {=GetFieldText(GetContextItem(WITNESS),"%~.NAME:GIVEN%")}

The witness's role was: {=GetFieldText(GetContextItem(WITNESS_LINK),"%~.ROLE%")}