Skip to content

How to Code an Instrument

christinerogers edited this page May 16, 2017 · 26 revisions

HOME > SETUP > DEVELOPER'S INSTRUMENT GUIDE > 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.

Code an Instrument in PHP

  1. Make a copy of the template instrument (from docs/instruments/ directory) in your project/instruments/ directory, and ensure it is apache-readable.
  2. Rename it to “NDB_BVL_$TEST_NAME$.class.inc”
  3. 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; this will also be the name of the MySQL table for this instrument.
  4. Add pages (if necessary). 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].
  5. Add questions to each page using $this->addType() wrappers or use $this->createType() wrappers (in case of table/groups). 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.
  • Element names must be lowercase and fewer than 64 characters (e.g. q07_mother_maiden_name). Never use hyphens, as it is confused with the MySQL minus sign. Element names *_status are reserved for select boxes accompanying text fields.
  • Use addDateElement wrapper for dates. Modify dateTimeFields array to include all date elements for proper conversion to database date/timestamp format.
  • Any date elements used should be added to the dateTimeFields array (so that they will be converted between HTML_Quickform and MySQL formats automagically).
  • Any multiple select elements should be added to the _selectMultipleElements array. This way they will be transferred between the database and the QuickForm smoothly.
  • For question dependencies, use XIN Rules.
  • For formatting questions into tables, see Instrument Groups.
  1. 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')); These array items must be entered to mark instrument as 'Complete'
  1. 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
  2. For scoring functionality, implement scoring through a separate script or a function within the instrument class.
<?php
// Basic Instrument structure
class NDB_BVL_Instrument_$TABLE_NAME$ extends NDB_BVL_Instrument
{

    function setup($commentID, $page)
    {
        // Update the testName and tableName
        // Update dateTimeFields, _selectMultipleElements, _requiredElements,
        // _doubleDataEntryDiffIgnoreColumns arrays
    }	

    function _setupForm()
    {
        // Update preg_match function for multi-paged instruments
    }

    function _main()
    {
        // First page of instrument
    }

    function _page1()
    {
        // Another page
    }

    function _page2()
    {
        // Another page
    }
	
} 

NEXT: (3) Instrument Insertion


See also:

Clone this wiki locally