Requirement	Form Layout
Section	3.2.1.1
JIRA Task	EIR-34 - Getting issue details... STATUS

Introduction

The Form Layout component of Form Designer enables the user to select and position user input fields, text and simple graphics (generically referred to as "fields") on a canvas to create questionnaires that facilitate accurate and systematic data collection. Mechanisms for receiving user input include simple text-entry fields configured for alphanumeric, numeric, multi-line text, images, as well as formatted fields for specific data types including date, time, and telephone numbers. Other input devices include menus and checkboxes that allow users to select a legal value from a list, checkboxes, which toggle Boolean variables, and even menus in which the value selected determines the available values in other menus. Form Designer also supports other "fields" that do not take user input but serve other functions. There are text boxes that can serve as form titles, labels or explanatory text, mechanisms to group other fields together so they can be addressed as a unit, and buttons that can trigger other actions using Check Code or load "related" forms, enabling the user to construct meta-forms from prefabricated components. Each form page serves as a template for populating a database table when used with the Enter module.

Create Project

Objective

The objective of the Create Project use case is to use Form Designer to create and save a new project.

Preconditions

To complete the Create Project use case, the Epi Info™ 7 menu program must be running. (Click on the Epi Info 7 program icon or type "EpiInfo.exe" from the command prompt in the installation directory.)

Postconditions

An Epi Info™ 7 project will be created in the Form Designer module and saved to a location accessible from the computer. The Epi Info™ 7 project file, <ProjectName>.prj, will be located in the <ProjectName> directory where the project was saved. The latter directory will also contain a <ProjectName>.mdb file, if the data repository that was selected at the time of project creation is Microsoft Access 2002-2003 (.mdb).

Stimulus/Response Sequence

Start Epi Info™ 7, open Form Designer, then Create, Save, and Close a New Project

1

Stimulus:

Response:

User selects the Form Designer tool by clicking on the Create Forms button on the Epi Info 7 main menu/splash screen.

A Form Designer window opens, containing a menu/button bar and two frames, divided vertically: a Project Explorer frame with a list of project and form templates, if any, and a frame containing a tabbed-page stack with a single unnamed tab.

2

Stimulus:

Response:

User selects File→New Project from the Form Designer menu or New Project from button bar.

A New Project dialog window opens with a number of fields for entering the name and location of the Project (.prj) and data repository (.mdb) files, and the form name.

3

Stimulus:

Response:

User populates the fields in New Project dialog and clicks "OK".

Dialog disappears; the Project Explorer frame is populated with the names of the project, the initial form, the new form’s initial page named “Page 1”, a list of field types, and a list of project, form, page and field templates. Canvas frame displays an empty canvas page with the name of the form prepended to the name of the page on the tab label (e.g., "Project 1/Page 1"). A new project is created and automatically saved.

Functional Requirements

The system shall enable the user to create a new project:
1. from scratch, starting with a blank form, or
2. using a project template or
3. using a form template.
The system shall enable the user to create and save a new project with the following properties:
1. project name (compatible with file naming requirements of the operating system),
2. location on filesystem where project meta-data is stored,
3. text description,
4. location for (and type of) project data repository (Microsoft Access or Microsoft SQL Server), and
5. initial form name.

Create Form

Objective

The objective of this Use Case Specification is to define the functional requirements of the Create Form Use Case. The requirements for the functionality that must be provided to users of the system are described in terms of use cases.

Preconditions

To complete the Create Form Use Case, the Epi Info™ 7 program must be running and the Form Designer module must be open.

Postconditions

An Epi Info™ 7 project has been created or modified to include a number of data-entry fields sufficient to constitute a useful Form. (The definition of "useful" is dependent on context. The example described below will suffice as an operational definition of "useful".) The structure of the Form has been saved to the filesystem and can be reopened for editing or data entry using "Open Existing Project", described below or published/uploaded to a companion tool for data entry such as Web Survey, Mobile Companion for Android, or Cloud Data Capture.

Stimulus/Response Sequence

Using Form Designer, Open an Existing Project

1

Stimulus:

Response:

User selects File→Open Project from menu or Open Project from button bar.

A Windows File Browser dialog opens on the Epi Info projects directory.

2

Stimulus:

Response:

User opens <ProjectName> directory and selects the Epi Info project file (<ProjectName>.prj) located inside.

File Browser Dialog disappears. Project Explorer frame is populated with project and form names, a list of field types, and a tree listing any existing project, form, page, or field templates. Canvas frame displays the canvas page and the fields on the page, if any. The canvas page has a tab labeled with the name of the form and the name of the page. The project is now open. (This is equivalent to the response in step 3 in the previous sequence.)

Adding Form Elements: Data Fields, Graphic Elements, Pages, etc.

3

Stimulus:

Response:

Select element (Text) from field list in Project Explorer frame and drag element to position on canvas or right-click the canvas near where the new field should be and select New field→element (Text) from the list.

Field-specific (i.e., Text-specific) dialog opens over canvas.

4

Stimulus:

Response:

User populates fields and selects attributes and other options in a field-specific dialog box, then clicks "OK".

The caption and field drop onto the canvas in the approximate location of drag destination or right-click.

5

Stimulus:

Response:

User clicks and holds a field's input field and repositions the pointer (applies only to fields with separate caption and user-input field, not to fields with only text and/or graphics).

The input field moves in relation to the caption text, which remains stationary.

6

Stimulus:

Response:

User clicks and holds a field's caption and repositions the pointer (see Stimulus in previous row for caveats).

The caption and input field move as a unit (i.e., together) when repositioned.

7

Stimulus: .

Response:

User selects Insert→Page→Add Page from menu bar or right-clicks the form name in the Project Explorer and selects Add Page from the context menu

A dialog opens to receive the name of the new page with the label "Page n" by default (where n is the total number of pages in the Form plus one). After clicking OK, an empty page canvas appears in the right frame and a Page icon, is added to the end of the page list for the current form in the Project Explorer tree.

8

Stimulus:

Response:

User selects Insert→Page→Insert Page from menu bar or right-clicks a <PageName> in the Project Explorer and selects Insert Page.

A dialog opens to receive the name of the new page with the label "Insert Page" by default. After setting the new page name and clicking OK, an empty page canvas appears in the right frame and a page icon is added under the active form and before the current page in the Project Explorer tree.

9

Stimulus: .

Response:

User selects a page template from Templates→Pages in the Project Explorer and drags the icon to a position immediately above or below a <PageName> in the Explorer (<ProjectName>→<FormName>→<PageName>).

A dialog window appears labeled "Set Page Name" that prompts for "Page Name:" with the default value of "Page n+1", where n is the total number of pages in the form.

10

Stimulus:

Response:

User types a new page name in the "Page Name:" field and clicks "OK".

A new page based on the template appears in the canvas frame with the tab labeled <FormName>\<PageName> and a new line appears in the Project Explorer, <ProjectName>→<FormName>→<PageName>, where the location of <PageName> relative to the other page(s) is in accordance with the terminal position of the mouse-drag event.

11

Stimulus:

Response:

User selects Edit→Delete Page from menu bar or right-clicks the page in the Project Explorer and selects Delete Page.

The page currently in focus is removed from the Form [1].

12

Stimulus:

Response:

User selects Edit→Rename Page from menu bar.

The user is prompted for a new page name which is assigned to the page when the name is entered.

Note:

If the data table has been created (see Initialize Data Table, below), a confirmation dialog is given asking if you are sure you want to delete the page; that the action cannot be undone. Any data collected with the fields on the page will be permanently lost.

Functional Requirements

The system shall enable the user to:

open an existing project,
create a data-entry form in a new or existing project,
populate the form with data-entry fields and other graphical elements chosen from a collection of supported form elements[1],
remove, reposition or modify the properties of fields,
for a given field, change the font and modify its style and size for:
1. the prompt text, and
2. the field text,
specify the default font and its size and style for:
1. the prompt text, and
2. the field text,
specify the default label-field alignment as:
1. vertical (labels are placed above fields), or
2. horizontal (labels are placed to the left of fields),
align and evenly distribute selected fields into one (1) or more columns, with a maximum of five (5),
align and evenly distribute selected fields on a single row,
select a group of fields and make their height, width or size (both height and width) uniform based on the largest or smallest selected field,
specify the parameters for a "snap-to" grid to facilitate the regular placement of fields on the page canvas, including:
1. toggle the "snap-to" function of the grid,
2. toggle the display of the grid,
3. grid square size (integer),
4. toggle snap prompt to grid, and
5. toggle snap entry field to grid,
add additional pages to the form and reorder them as needed,
specify the dimensions of each page using:
1. standard American sizes (Letter, Legal, Executive),
2. standard European sizes (A0, A1, A2, ..., A6),
3. standard mobile device screen sizes (e.g., Android Galaxy Tablet), or
4. a custom size defined in millimeters,
specify a solid color or image for the background of one or more pages in the form and control whether the image is:
1. placed in the upper-left or center of the page, or
2. stretched or tiled across the entire page,
cut/copy/paste fields within and between pages in the same project,
save a group of fields as a Fields Template,
use a Fields Templates to add a group of fields to a form,
save a form as a Form Template,
save a project as a Project Template,
create a project from an existing Project Template,
create a project from an existing Form Template,
place and reposition a fields template in the same manner as an individual field when adding it to a form,
carry over field values from the previously-viewed record to a new record for certain fields with the "repeat last" option enabled,
prevent records from being saved and generate a warning for fields with the "required" option enabled,
view and edit the Tab Order of fields on a form,
view and print the field names (variable names) on, or adjacent to, each field on a page,
open the Epi Info™ 7 log file directory for selecting and viewing individual files,
create a new blank form page and insert it at an arbitrary position in the sequence of pages for that form,
delete an arbitrary page from a form containing two or more pages,
rename an arbitrary page from a form containing one or more pages,
add a form,
relate a form,
delete a form,
view the data dictionary, and
undo and redo previous actions.

Note:

In requirement 3, a distinction is made between traditional data-entry "fields", menus, options, checkboxes and other non-field elements. For simplicity, Epi Info 7™ considers all items that can be placed on a form (with the exception of templates) as fields. This SRS will use the word "field" in this more general sense, except where indicated.

Initialize Data Table

Objective

The objective of this Use Case is to create a data table based on the form design (including field variables and their types) for each page of the current form in Form Designer.

Preconditions

An uninitialized form, just created, loaded from a project file or created from a form template, is open in Form Designer.

Postconditions

The form's data table(s) has been initialized in the project's database and is ready to accept data using the application, Enter.

Stimulus/Response Sequence

Initialize Data Table for Form

1

Stimulus:

Response:

User clicks on the Enter Data button on the button panel, or selects Tools→Create Data Table or Tools→Enter Data from the menu bar.

Create New Data Table dialog opens, which reads: "A data table has not been created for this form. Would you like to create a data table?"

2

Stimulus:

Response:

User click on the "Yes" button.

Create New Data Table dialog closes. New Data Table dialog opens, containing two fields labeled "Data table name:" and "Starting ID:", populated with <ProjectName> and "1", respectively.

3

Stimulus: .

Response:

User may change the default values for "Data table name:" and "Starting ID:", for example, to facilitate merging into the database of a central data collection center. User clicks on the "OK" button.

The dialog closes. If the initialization process was started using the Enter Data button or Tools→Enter Data menu item, Form Designer closes and the Enter application opens with <ProjectName> already loaded and the form opened for data entry.

Functional Requirements

The Form Designer user interface shall enable the user to:

create a data table for the current form when:
1. the user selects an appropriately-labeled button or menu item, and
2. the user attempts to open Enter on a previously-uninitialized form;
delete the data table (and all corresponding data) from an initialized form.

Description of Form Elements

Element	VarType	Arguments	Attributes	Compatibility
Element	VarType	Arguments	Attributes	Web Survey	Mobile App	Cloud Capture
Label/Title	n/a	Question or Prompt (LongText) Field Name (Text) Font (dialog)		x	x	x
Text	String	Question or Prompt (LongText) Field Name (Text) Maximum Number of Characters	Read Only `[ ] * see footnote 1 ` Repeat Last `[ ]` Required `[ ] see footnote 1 *` Prompt Font (font dialog) Field Font (font dialog)	x	x	x
Text (Uppercase)	String	Question or Prompt (LongText) Field Name (Text) Maximum Number of Characters	Read Only `[ ]` Repeat Last `[ ]` Required `[ ]` Prompt Font (font dialog) Field Font (font dialog)		x
Multiline	String	Question or Prompt (LongText) Field Name (Text)	Read Only `[ ]` Repeat Last `[ ]` Required `[ ]` Prompt Font (font dialog) Field Font (font dialog)	x	x	x
Number	Float	Question or Prompt (LongText) Field Name (Text) Pattern (options below) None # ## ### #### ##.## ##.### User Defined	Read Only `[ ]` Repeat Last `[ ]` Required `[ ]` Range `[ ]` Lower (Float) enabled if Range == `True` Upper (Float) enabled if Range == `True` Prompt Font (font dialog) Field Font (font dialog)	x	x	x
Phone Number	String	Question or Prompt (LongText) Field Name Pattern (options below) None Numeric ###-#### ###-###-#### ###-###-###-#### #-###-###-###-#### User Defined	Read Only `[ ]` Repeat Last `[ ]` Required `[ ]` Prompt Font (font dialog) Field Font (font dialog)
Date	Date	Question or Prompt (LongText) Field Name (Text)	Read Only `[ ]` Repeat Last `[ ]` Required `[ ]` Range `[ ]` Lower (Date with Calendar) enabled if Range == `True` Upper (Date with Calendar) enabled if Range == `True` Not Future Date `[ ]` Prompt Font (font dialog) Field Font (font dialog)	x	x	x
Time	Time	Question or Prompt (LongText) Field Name (Text)	Read Only `[ ]` Repeat Last `[ ]` Required `[ ]` Prompt Font (font dialog) Field Font (font dialog)	x	x	x
Date/Time	Date/Time	Question or Prompt (LongText) Field Name (Text)	Read Only `[ ]` Repeat Last `[ ]` Required `[ ]` Prompt Font (font dialog) Field Font (font dialog)
Checkbox	Boolean	Question or Prompt (LongText) Field Name (Text) Place Box on Right `[ ]`	Read Only `[ ]` Repeat Last `[ ]` Prompt Font (font dialog)	x	x	x
Yes/No	Boolean	Question or Prompt (LongText) Field Name (Text)	Read Only `[ ]` Repeat Last `[ ]` Required `[ ]` Prompt Font (font dialog) Field Font (font dialog)	x	x	x
Option	Text	Question or Prompt (LongText) Field Name (Text) List Options ... (Choose One) Vertical Horizontal Start Listing on ... (Choose One) Left Right Option Definition(s) (Text), One for Each Choice	Show Label on ... (Choose One) Right Left Number of (Mutually Exclusive) Choices (`Integer`) Prompt Font (font dialog) Field Font (font dialog)	x	x	x
Command Button	n/a	Question or Prompt (LongText) Field Name (Text)	(Prompt) Font (font dialog)		x
Image	File	Question or Prompt (LongText) Field Name (Text) Retain Image Size `[ ]`	(Prompt) Font (font dialog)		x
Mirror	n/a (displays value from another field in form)	Question or Prompt (LongText) Field Name (Text)	Assigned Variable (Choose from all Form Variables) Prompt Font (font dialog) Field Font (font dialog)
Grid	Composite	Question or Prompt (LongText) Field Name (Text) Column Definitions (Grid Columns dialog) Column Header Name for Grid (Text) Column Name (Text) Size (Integer; select 1 - 5) Column Type (Select from List) Text Number Phone Number Date Time Date/Time Checkbox Yes/No Legal Values Comment Legal	Grid Column Dialog Attributes Read Only Required Repeat Last Range Unique Field Note: Column Type selection determines enabled attributes
Legal Values	Selected Values from List	Question or Prompt (LongText) Field Name (Text)	Read Only `[ ]` Repeat Last `[ ]` Required `[ ]` Prompt Font (font dialog) Field Font (font dialog) Data Source (Set Up Code / Legal Links dialog) Data Source (blank field) Do not sort `[ ]` Buttons Create New Creates List-Entry UI in Data Source field Create New from Existing Prompts user to select from list of stored arrays Prompts user to select field (column) to use Selected array is loaded into List-Entry UI New Items can be added to List Use Existing Prompts user to select from list of stored arrays Prompts user to select field (column) to use Selected array is loaded into List-Entry UI Delete Link Allows user to remove array after it has been loaded	x	x	x
Comment Legal	Selected Values from List	Question or Prompt (LongText) Field Name (Text)	Identical to Legal Values except that list items must have following structure: Coded Value (value entered in DB when corresponding comment is selected) '-' (hyphen separator) Comment (appears in menu on form)	x	x	x
Codes	n × m table	Question or Prompt (LongText) Field Name (Text)	Read Only `[ ]` Repeat Last `[ ]` Required `[ ]` Prompt Font (font dialog) Field Font (font dialog) Select field(s) to be linked to List of text variables from other fields with enumerated values Data Source (Codes dialog) Similar to "Set Up Code / Legal Links" dialog However, it creates/uses a list of key-value pairs instead of a simple list of individual choices
Relate	Form	Question or Prompt (LongText) Field Name (Text) Font (for Prompt) Related Form (choose) Another Form in Project (create new form)	Radio Buttons Accessible Always Accessible only the following conditions are true Define Condition from (choose) Pull-down list of available variables Relational and logical operators Return to parent after one record ... `[ ]` Related to NutStat Module `[ ]`			x
Group	Alias	Question or Prompt (LongText) Field Name (Text)	Prompt Font (Font dialog) Color (Windows 7 Color Chooser dialog) Group creates a region on the canvas for which the Field Name serves as an alias for all of the fields contained within the region. This enables the user, for example, to enable or disable all fields in the region by referencing the group's Field Name.	x	x	x
Unique Identifier	String	Question or Prompt (LongText) Field Name (Text)	Read Only [×] see footnotes 2 & 3 Repeat Last [ ] Required [ ] Prompt Font (font dialog) Field Font (font dialog)

Notes:

The attributes "Read Only" and "Required" are mutually exclusive for all elements.
Attributes shown in fixed font cannot be modified by user.
The Unique Identifier field last appeared in Epi Info™ version 7.1.5. It was removed from the list of available fields beginning with version 7.2.