Requirement	Check Code
Section	3.2.1.2
JIRA Task	EIR-48 - Getting issue details... STATUS EIR-35 - Getting issue details... STATUS

Introduction

Check Code is a component of Form Designer that allows the user to specify the business logic behind the form, enabling smart navigation, data validation, and other useful features. Whereas Form Layout enables the user to select, place and define the properties of individual fields, Check Code controls the interaction and relationships between them. Check Code is most commonly used to skip or disable fields based on data entered but it can also assign values to variables, search for redundant entries, convert addresses to geospatial coordinates, trigger dialogs and execute external programs, all in response to user actions such as selecting a field, entering data into it, or clicking on a button or checkbox. Check Code greatly increases the power and potential of Epi Info™ 7 and is a logical entry point for future developers seeking to add new functionality.

Open Check Code Editor

Objective

Given a form ("questionnaire") that has been populated with fields using the form layout canvas of Form Designer, open the Check Code editor.

Preconditions

To complete the Open Check Code Editor use case, the Epi Info™ 7 Form Designer program must be open on a questionnaire.

Postconditions

After completing this Stimulus/Response Sequence, the Check Code Editor will be open.

Stimulus/Response Sequence

Opening an Existing Project
1	Stimulus: Response:	User clicks the "Create Forms" button from the Epi Info™ 7 main menu or executes the MakeView.exe program from the Epi Info 7 folder. Form Designer window opens.
2	Stimulus: . Response:	User clicks "Open Project" from button bar or selects File→Open Project from menu bar or types Ctrl-O or selects File→Recent Projects and selects an existing project from the list. A file browser opens on the <InstallationDirectory>\Projects\ directory, showing directories for existing projects.
3	Stimulus: Response:	From the file browser, user opens a Project directory, then selects and opens the <ProjectName>.prj file. File browser closes and Form Designer window opens, consisting of a menu bar and button bar along the top with the remainder of the window divided into a Project Explorer frame and a drawing canvas populated with the fields of the project's form.
4	Stimulus: . Response:	From the Form Designer window, the user clicks on the Check Code button on the button bar or selects Tools→Check Code from the menu bar or right-clicks a field on the canvas and selects Field Check Code from the context menu. A window opens containing the Check Code Editor.

Opening an Existing Project

Stimulus:

Response:

User clicks the "Create Forms" button from the Epi Info™ 7 main menu or executes the MakeView.exe program from the Epi Info 7 folder.

Form Designer window opens.

Stimulus: .

Response:

User clicks "Open Project" from button bar or selects File→Open Project from menu bar or types Ctrl-O or selects File→Recent Projects and selects an existing project from the list.

A file browser opens on the <InstallationDirectory>\Projects\ directory, showing directories for existing projects.

Stimulus:

Response:

From the file browser, user opens a Project directory, then selects and opens the <ProjectName>.prj file.

File browser closes and Form Designer window opens, consisting of a menu bar and button bar along the top with the remainder of the window divided into a Project Explorer frame and a drawing canvas populated with the fields of the project's form.

Stimulus: .

Response:

From the Form Designer window, the user clicks on the Check Code button on the button bar or selects Tools→Check Code from the menu bar or right-clicks a field on the canvas and selects Field Check Code from the context menu.

A window opens containing the Check Code Editor.

Adding Check Code to a Questionnaire

Objective

Given a questionnaire containing all field types, create an example of every applicable Check Code command, function, and operator using the data entry control points available in the form.

Preconditions

The Check Code Editor is open on a form.

Postconditions

Check Code will be added to the form, demonstrating their function including the arguments that govern their functionality and the fields and variables with which they interact.

Functional Requirements

Using the Check Code Editor, the system shall enable the user to complete the following operations on the form currently open in Form Designer:

view a list of Check Code Action Control Points (listed below)
view a list of Check Code Action Commands (listed below)
associate specific commands with specific Fields
program commands to execute at specific Action Control Points
define variables with specific scope and type
validate the Check Code commands associated with all Fields and variables in the form
Save the Check Code with the corresponding form

Action Control Points

Level	User Stories	Notes
Form	The user shall have the ability to program Actions to occur: when a form is opened in Enter (for data entry) when a form is closed.
SubRoutine	The user shall have the ability to program Actions to occur when invoked by the "Call" command.	Creates a subroutine code block with the user-supplied name.
Record	The user shall have the ability to program Actions to occur: when a record is opened when the record is closed.
Page	The user shall have the ability to program Actions to occur: when the cursor enters a page when the cursor leaves the page.	Relevant to multi-page forms
Field	The user shall have the ability to program Actions to occur: when the cursor enters the field before data entry when the cursor attempts leaves the field usually following data entry when the user clicks on the field or selects a listed item.	Most check code commands are used at the field level. The field type governs which of the three Action Control Points are available.

Action Commands

The table below lists the Check Code commands along with stories describing their actions. The command actions are defined by using the Check Code Editor. Once defined, the actions are expressed when the user interacts with the form during data entry using the Enter module.

Command	User Stories
Assign	Command shall assign a value or expression result to its argument (variable).
AutoSearch	Command shall query previously entered records for those with values in the current field matching the current record. If matching records are identified by AutoSearch, the user interface shall open a list of matching records and display the variables listed as arguments for the DISPLAYLIST parameter. One listed record may be opened for viewing, editing, or deleting thereby discarding any changes to the current record. No listed record may be opened and current record changes are preserved when using the CONTINUENEW keyword.
Call	Command shall execute a subroutine by name.
Clear	Command shall set the variable to NULL/Missing or in the case of a check box field type, the field is set to false (unchecked).
Define	Command may define the Type of the specified variable (this is optional for backward compatibility but strongly recommended). The following variable Types shall be supported (see table Variable Type and Scope, below): TEXTINPUT (string or text) NUMERIC (integer and floating-point) DATEFORMAT (formatted date value such as "9/11/2001") YN (allowed values: "(+)", "(-)" and "(.)" for "Yes", "No", "Missing", respectively) Command shall define the Scope of the specified variable. The command shall define the following values for variable Scope (see table Variable Type and Scope, below): Standard: the variable (and its value) shall persist as long as the record remains current. Global: the variable shall persist for the duration of program execution. Permanent: the variable shall persist through multiple program invocations.
Dialog	Command shall display a dialog box when executed. Dialog box shall support one of three modes of operation: Simple: displays an Input Dialog window with title and a prompt, both provided during configuration Get Variable: displays title and prompt and populates a previously-defined variable with user input through the dialog List of Values: displays title and prompt and populates a previously-defined variable with a user-selected item from the list.
Disable	Command shall disable data entry into one or more listed fields or fields contained within a group field. Command shall "gray out" the field for the specified variable.
Enable	Command shall enable one or more listed fields or fields contained within a group field that were previously disabled. Command shall reverse the "gray out" of the field or fields.
Execute	Command shall execute an external MS Windows program. Command shall have an option to pause the Epi Info process and wait for the program to terminate or to fork off the program and return to Epi Info immediately.
Geocode	Command shall determine geo-spatial coordinates (latitude and longitude) given an address, postal code, or registered place.
GOTO	Command shall move the cursor to the indicated field, regardless of tab order, or other mouse events provided that the indicated field is a field that can receive data (not a label field or disabled).
Help	Command accepts a URL or name of an HTML file and a value for the "anchor" parameter. When activated, the document is rendered in the default browser.
Hide	Command shall render the field and caption or prompt of the indicated field invisible.
Unhide	Command shall render the field and caption of the previously-hidden field visible again.
Highlight	Command shall highlight the field and caption of the specified field with a yellow background.
Unhighlight	Command shall remove highlighting on the field and caption of the specified, previously-highlighted, field.
If	Command shall create a logical construct to conditionally execute one of potentially two blocks of code based on the evaluation of a Boolean expression. Command(s) in the Then block are executed if the expression returns "TRUE" (1); command(s) in the optional Else block are executed if the expression returns "FALSE" (0).
NewRecord	Command shall save data from the current record, close it, then open a new record. If there are unsaved edits to the record, a confirmation dialog is raised, asking whether the record should be saved.
Quit	Command shall generate a dialog box with a "yes" button and a "no" button and a prompt asking whether the record should be saved before closing, if the record has unsaved changes. Command shall respond to a "yes"-button-click by saving the current record, then exiting Enter. Command shall respond to a "no"-button-click by exiting Enter program immediately without saving.
Set-Required	Command shall set the property of the specified field to "required". During data entry (using Enter, Web Survey, Mobile Companion for Android, or Cloud Data Capture), a required variable shall be set to a value before the record can be saved. Note: A required field must be satisfied even if it is disabled or hidden. This is required since disabled/hidden fields can received data through an Assign statement in Check Code.
Set-Not-Required	Command shall set a field to be optional ("not required").
GoToForm	Command shall open the named form, assuming form is related to the current form.

Variable Types and Scope

Pragma	Description	Mnemonic
Variable Scope
STANDARD	Values persist as long as a record is current and are reset when a new record is loaded.	Record
GLOBAL	Values are robust to changing records and forms but are reset when the program is closed and restarted.	Program
PERMANENT	Values are stored between invocations of Epi Info™ 7 and are shared between modules.	Persistent
Variable Type
TEXTINPUT	Variables of this data type can receive any alpha-numeric characters including symbols and the output of functions.	Text
NUMERIC	Variables of this data type can receive numbers, including the output of functions that return numbers.	Number
DATEFORMAT	Variables of this data type can receive date values, including the output of functions that return dates.	Date
YN	Variables of this data type can receive the Boolean values of (+) for Yes and (-) for No. Until an assignment is made, YN type variable values are (.) or missing.	Boolean

User Interaction and Design

The Check Code Editor is designed to support both direct entry of Check Code (text in the Check Code "language") and assisted entry using menus and interactive dialog windows. The interface consists of a large code editor panel, a tree display corresponding to the Check Code Action Control Points, and a list of Check Code Action Commands. Selecting a terminal node from the Action Control Points tree, such as Page 1:Page→<field>→after causes the cursor to be placed at the designated code block in the editor if the block exists. If the block does not exist, selecting a terminal node from the Action Control Points tree enables a button that generates a code block for that control point. Double-clicking a terminal node from the Action Control Points tree also generates a code block for that control point if one does not exist. The user may either type the desired command(s) inside the block or choose a command from the list. Selecting a command from the list opens a command-specific interface which enables the user to select the appropriate arguments and functions to complete the desired operation. This process of selecting Control Points and choosing Action Commands may be repeated as many times as necessary to accomplish the desired Check Code tasks.

Check Code can be commented using the editor for the purpose of documentation or to disable specific commands while debugging. Two comment forms are recognized. A single line can be commented by starting it with a "//" (double slash). A block of lines can be commented using the C-like convention of placing a "/*" in the first column at the starting line for the comment block and ending the block with "*/". All lines between "/*" and "*/" are ignored.

Browser not supported