Developer's Instrument Guide

This guide reflects a typical workflow and best practices used by Loris developers at the MNI. Some specifics such as git workflow steps may not apply to all projects and implementations.

##What is an Instrument? An instrument should likely be coded manually in PHP if it involves:

• dependencies between fields (rules)
• special data formats or restricted types
• special scoring
• look-up tables (t-scores etc)
• age-dependencies in administering the instrument

##Developer Workflow

1. Get the entire PDF/paper copy, including any “lookup” tables used for scoring/normalization. Key questions to ask before starting are:
2. Has it been coded before? [link to instruments list]
3. Clarify requirements: which sections of the questionnaire to include/omit. Typically, administrative details included on the original form can be ignored, but instructions that will be helpful for the examiner might be included.
4. PHP or Linst: Simple instruments can use Linst (see above).
5. How will all your fields map to the element types allowed by Loris form (beta!) (also see here for a list of allowed elements)
6. Does your instrument require certification? Are there certified examiners? Can/should users be certified as examiners for this instrument using the Training module?
7. Create a new git branch based off the up-to-date branch for your project-specific repo. For any Git inquiries, consult → link
8. Create an instrument in the project/instruments/ directory
9. Make a copy of the template instrument (from docs/instruments/ directory).
10. Rename it to “NDB_BVL_$TABLE_NAME$.class.inc”
11. 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.
12. Add pages ( if necessary )
13. Usually the number of pages corresponds to the number pages in the pdf.
14. Create a new function for every page i.e. function _page2(), function _page3()...
15. Add questions to each page using $this->addType() wrappers or use $this->createType() wrappers (in case of table/groups)
16. Run PHPCS on the instrument, and use PHPCBF to fix them. How? → link
17. Insert the Instrument
18. Add database records for your new instrument
19. Create and source the instrument sql file into your database.
20. Front end testing: Populate a record for a dummy candidate using assign_missing_instruments Test in your virtual machine to see if it works.
21. Push branch and create pull request to your project-specific repo, how → link. Assign relevant tags and tester.
22. Update any management document that you may be required to update.