[instruments] Display Candidate Age at Death if postMortem is true (#8362)

- fixes the Candidate Age at Death field label and Data Dictionary item for LINST instruments
- adds postMortem functionality for LINST instruments
- solidifies workflow for when Candidate Age at Death is displayed vs. Candidate Age (only when postMortem variable is set to true, and is independent of whether candidate has DoD or not - it is truly an instrument configuration and not dependent on instrument/candidate data)
- adds this workflow/configuration to the instruments module testplan and readme

Author: zaliqarosli

modules/instruments/README.md

@@ -34,6 +34,14 @@ and put in the `project/instruments`.
 Individual instruments may contain their own configurations (such
 as requiring tables to be created or lookup tables.)
 
+If the instrument is administered after the candidate's death,
+the `postMortem` variable can be set to true within the
+`NDB_BVL_Instrument` class or the `postmortem` tag set to true
+within the linst instrument meta file. This configuration
+determines which candidate age is displayed as part of the
+metadata fields: `Candidate Age (Months)` or
+`Candidate Age at Death (Months)`.
+
 ## Interactions with LORIS
 
 The survey module uses instruments of the same format as data entry

modules/instruments/test/TestPlan.md

@@ -21,9 +21,10 @@ saved data stays the same. The data that wasn't saved should be lost.
 6. Make sure that the 'Delete instrument data' button on the left pane is only visible when the user
 has the 'Send to DCC' permission.
 7. Click on the 'Delete instrument data' button and check if the instrument's data is cleared.
-8. Select a candidate with a Date Of Death (DoD) or put one in for a candidate as needed, then select an
-instrument for that candidate. Enter a date (same a step 4) posterior to the DoD. Refresh the page and check that the 
-'Candidate age' label change to 'Candidate Age at Death'.
+8. Check that an instrument with the `postMortem` variable set to true displays the label
+'Candidate Age at Death (Months)' instead of 'Candidate Age (Months)'. To set the `postMortem` variable
+for PHP instruments, assign the variable within the instrument's PHP class; for LINST instruments,
+include `postmortem{@}true` in the instrument's meta file.
 9. Check that access restriction in `config.xml` work.
  - In the `<instrumentPermissions>` section of `config.xml`
  - set the `<useInstrumentPermissions>` to `true`

php/libraries/NDB_BVL_Instrument_LINST.class.inc

@@ -108,7 +108,7 @@ class NDB_BVL_Instrument_LINST extends \NDB_BVL_Instrument
                     $this->dictionary,
                     [
                         new DictionaryItem(
-                            $this->testName.'_Candidate_age',
+                            $this->testName.'_Candidate_Age',
                             'Candidate Age (Months)',
                             $scope,
                             new \LORIS\Data\Types\Duration(),
@@ -120,14 +120,14 @@ class NDB_BVL_Instrument_LINST extends \NDB_BVL_Instrument
             } else {
                 $this->addScoreColumn(
                     'Candidate_Age',
-                    'Candidate_Age_at_Death'
+                    'Candidate Age at Death (Months)'
                 );
                 $this->dictionary = array_merge(
                     $this->dictionary,
                     [
                         new DictionaryItem(
-                            $this->testName.'_Candidate_age',
-                            'Candidate Age At Death (Months)',
+                            $this->testName.'_Candidate_Age',
+                            'Candidate Age at Death (Months)',
                             $scope,
                             new \LORIS\Data\Types\Duration(),
                             new Cardinality(Cardinality::SINGLE),
@@ -923,6 +923,9 @@ class NDB_BVL_Instrument_LINST extends \NDB_BVL_Instrument
             case 'jsondata':
                 $this->jsonData = trim($pieces[1]) === 'true';
                 break;
+            case 'postmortem':
+                $this->postMortem = trim($pieces[1]) === 'true';
+                break;
             default:
                 break;
             }