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.

##Should this instrument be coded?

1. 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

2. Has it been coded before? [link to instruments list]

##Developer Workflow

1. Before getting started...
2. Get the entire PDF/paper copy, including any “lookup” tables used for scoring/normalization.
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. How will all your fields map to the element types allowed by Loris form (beta!) (also see here for a list of allowed elements)
5. Does your instrument require certification? Are there certified examiners? Can/should users be certified as examiners for this instrument using the Training module?
6. Create a new git branch based off the up-to-date branch for your project-specific repo.
7. Create an instrument in the project/instruments/ directory
8. Make a copy of the template instrument (from docs/instruments/ directory).
9. Rename it to “NDB_BVL_$TABLE_NAME$.class.inc”
10. 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.
11. Add pages ( if necessary )
12. Usually the number of pages corresponds to the number pages in the pdf.
13. Create a new function for every page i.e. function _page2(), function _page3()...
14. Add questions to each page using $this->addType() wrappers or use $this->createType() wrappers (in case of table/groups)
15. Run PHPCS on the instrument, and use PHPCBF to fix them. How? → link
16. Insert the Instrument
17. Add database records for your new instrument
18. Create and source the instrument sql file into your database.
19. Front end testing
20. Populate a record for a dummy candidate using assign_missing_instruments
21. Test in your virtual machine to see if it works.
22. Push branch and create pull request to your project-specific repo, how → link. Assign relevant tags and tester.
23. Update any management documents, add a category to your bug tracker utility.