How to Code an Instrument

As an example: follow along with NDB_BVL_Instrument_TEMPLATE.class.inc or NDB_BVL_Instrument_mri_parameter_form.class.inc from docs/instruments/ directory.

// Basic Instrument structure
class NDB_BVL_Instrument_$TABLE_NAME$ extends NDB_BVL_Instrument
{
    // Content goes here
	
    function setup($commentID, $page)
    {
        // Update the testName and tableName
    }		
} 

Copy and rename the file into your project/instruments/ directory, and ensure it is apache-readable.
Edit the contents of the file to replace all template placeholders such TEST_NAME, <TEST_NAME>, <INSTRUMENT TITLE> and <FIRST QUESTION OF EACH PAGE>. Note that TEST_NAME within the file must match the TEST_NAME in the file name.

1. Make a copy of the template instrument (from docs/instruments/ directory).
2. Rename it to “NDB_BVL_$TABLE_NAME$.class.inc”
3. Find-replace the template’s instrument name (e.g. TEST_NAME, ABC, etc.) with the proper instrument name in the form of “VisitLabel_TestName”. eg. Clinical_Biosample_Collection.
4. Add pages ( if necessary )
5. Usually the number of pages corresponds to the number pages in the pdf.
6. Create a new function for every page i.e. function _page2(), function _page3()...
7. Add questions to each page using $this->addType() wrappers or use $this->createType() wrappers (in case of table/groups)
8. Run PHPCS on the instrument, and use PHPCBF to fix them. How? → link

An example of an uploader instrument (*.linst file) can also be found in the docs/instruments directory.

1. For a single-page instrument, include all questions in main() and delete functions _page[1-9]{}. If the instrument has multiple pages, add QuickForm elements inside functions _page[1-9].

2. Wrappers are included in NDB_BVL_Instrument.class.inc e.g. addTextElement(), addYesNoElement(), addTextAreaElement(). See http://pear.php.net/ for Quickform documentation. Many wrappers also use XinRegisterRule.

3. Element names must be lowercase and fewer than 64 characters (e.g. q07_mother_maiden_name). Never use hyphens - confused with MySQL minus sign. Element names "_status" are reserved for select boxes accompanying text fields

4. Use addDateElement wrapper for dates. Modify dateTimeFields array to include all date elements for proper conversion to database date/timestamp format.

5. For multiple-select elements, use _selectMultipleElements array

6. To ensure instrument completeness for all pages, modify _requiredElements() array to include 'Examiner' field and first question of each page, e.g. $this->_requiredElements=array('Examiner', 'q1', 'q19', 'q37', 'q55')); Array items must be entered to mark instrument as 'Complete'

7. It may be desirable to exclude certain instrument columns from the Conflict Resolver module, such as Comment fields. These fields should be added to the instrument class array _doubleDataEntryDiffIgnoreColumns within the instrument php file. By default, the base class already excludes the following fields: CommentID, UserID, Testdate, Window_Difference, Candidate_Age, Data_entry_completion_status

8. Any date elements used should be added to the dateTimeFields array (so that they will be converted between HTML_Quickform and MySQL formats automagically).

9. Any multiple select elements should be added to the _selectMultipleElements array. This way they will be transferred between the database and the QuickForm smoothly.

10. For question dependencies, use XIN Rules.

11. For scoring functionality, implement scoring through a separate script or a function within the instrument class.

NEXT: (3) Instrument Insertion