- 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%")}