Designer Guide

Author : Ashley G Trüter
Updated: 18-Jul-2007
Purpose: Describes the use of the RecordMan Form*Designer.

Contents:

1. Introduction

This guide introduces some basic terminology and concepts, discusses the file format used by forms, then explains how to create and modify your own forms with RecordMan's built-in Form*Designer.

1.1 What is a form?

A form is a piece of paper, digital in the case of RecordMan, with boilerplate text and associated fields and boxes where responses are noted. The “things” on a form are referred to as elements, broadly divided into text elements and data elements. Our sample “Patient Details” form is depicted below.

1.1.1 Text elements

“Particulars” and “Title”, even though they appear different, are both text elements. Text elements appear beside (or above) the data elements they are related to, and are designed to group information and provide a suitable prompt for the desired response(s).

1.1.2 Data elements

The pick-list next to “Title” and the field next to “Firstname” are both examples of data elements. While different types of data elements are available (Field, Check and Diagram), they all have a common purpose; to collect a specific type of response.

1.1.3 Form files

The elements described above are stored in a plain ASCII file with a .frm extension (which is a fancy way of saying that you can look at the contents with Notepad or similar).

Let's take a closer look at the Patient Details.frm file that describes the above form.

Form 0x0 12x13 [2.0 "Ashley"]
Field 3x1 3x1 ["" "titles.txt"]
Field 9x1 3x1 ["" ""]
Field 3x2 9x1 ["" ""]
Field 3x3 9x1 ["" ""]
Field 3x4 3x1 ["" ""]
Field 9x4 3x1 ["" ""]
Field 3x6 9x1 ["" ""]
Field 3x7 3x1 ["VIC" "states.txt"]
Field 9x7 3x1 ["" ""]
Field 3x8 9x1 ["" "pcodes-VIC.txt"]
Field 3x10 9x1 ["" ""]
Field 3x11 9x1 ["" ""]
Field 3x12 9x1 ["" ""]
Text 0x0 12x1 ["Particulars" 1.25 bold left]
Text 0x1 3x1 ["Title" 1 none left]
Text 6x1 3x1 ["File#" 1 none left]
Text 0x2 3x1 ["Firstname" 1 none left]
Text 0x3 3x1 ["Surname" 1 none left]
Text 0x4 3x1 ["Medicare#" 1 none left]
Text 6x4 3x1 ["DOB" 1 none left]
Text 0x5 12x1 ["Address" 1.25 bold left]
Text 0x6 3x1 ["Street" 1 none left]
Text 0x7 3x1 ["State" 1 none left]
Text 6x7 3x1 ["City / PO" 1 none left]
Text 0x8 3x1 ["Suburb" 1 none left]
Text 0x9 12x1 ["Contact" 1.25 bold left]
Text 0x10 3x1 ["Home" 1 none left]
Text 0x11 3x1 ["Work" 1 none left]
Text 0x12 3x1 ["Email" 1 none left]

Each line denotes a separate form element, with the first being a hidden (it does not appear on the form) “control” element that describes the form itself. Following this are all the data elements and then all the text elements.

1.1.4 Element properties

Each element has three properties, or attributes, that are common to all elements (Type, Offset and Size), followed by a group of zero or more properties specific to that type of element.

1.2 Does the sequence of elements matter?

This question is so fundamental to the design of RecordMan that it deserves a detailed explanation. But before we can answer the question we need to understand where and how RecordMan stores your data.

Important!

You must read and understand this section in its entirety to guarantee the integrity of your data.

1.2.1 Form data table

Your data is stored in a table named after the form (with spaces replaced with underscores). This table has four columns, only the last two of which concern us at the moment. A small slice of this table might look like:

ID Date       Seq Value
-- ---------- --- -----
 1 1-Jan-2007   1 Mr
 1 1-Jan-2007   2 John
 1 1-Jan-2007   3 Smith

This shows us that each value you enter and save on a form is stored as a separate row in the database, with the sequence determining “where” the value is located on the form. This sequence is the order in which data elements are located in the form file (in our Patient Details form the field adjacent to "Title" is first, with the field adjacent to "Firstname" second and so on).

1.2.2 How is this sequence managed?

If maintaining this sequence is so critical, what does Form*Designer do to prevent you from inadvertently mucking it (and your data integrity) up? Luckily, the answer to this question is quite simple, as Form*Designer ensures that:

1. Each new data element is inserted on a new line after the last data element, thus preserving the original sequence.
2. A data element can only be deleted if its sequence number is greater than the highest sequence number currently stored for the form in the database.

This means that you can freely modify your forms, even those that have already been used to store data, so long as as you realize that existing data is tied to specific data elements.

Example

If you swapped the fields adjacent to “Firtsname” and “Surname” around, any existing data “tied” to those fields would also be swapped as well; so John would appear next to the “Surname” text the next time you ran the form!

We started off by asking whether the sequence of data elements mattered, to which the categorical answer is YES! RecordMan is very flexible in that it allows you to design and modify forms almost without restriction, but you must consider how any changes you make will effect your existing data. If the change is too dramatic, it may be better to create a brand new form.

2. Using the Form*Designer

The built-in Form*Designer allows you to create, modify and run forms in an environment totally separate from your actual data (it can only change your form definition files, NOT the data entered via those definitions). Starting the Form*Designer displays an empty grid as follows:

2.1 Form actions

Each of the icons at the top of the window (they each have a tool-tip that appears when the mouse passes over them) triggers a form operation of the like name.

2.1.1 Open

Clicking Open will prompt for a form name to open. Choosing an existing form, such as our Patient Details example, will load and display the form in design mode.

The form will be rendered in a font 75% the size of what it will appear like at run-time and text lists will be displayed like a web link for easy design-time reference. If you want to create a new form, either copy and rename an existing one you wish to base it on, or enter a new name.

2.1.2 Save

Each form that you design and Save will have a .frm source file as previously discussed.

2.1.3 Run

Clicking Run will save the current form and then run it in a preview window.

Clicking the Print button will create a B&W PNG image of the form as it currently appears on the screen (less its window title-bar and print button) and open it with the default OS image viewer.

2.1.4 Delete

Clicking Delete only works when one or more element(s) have been highlighted. Form*Designer will not delete a data element with a sequence number less than or equal to the maximum sequence number currently stored in the form's table (i.e. it will prevent you from “breaking” current bindings).

2.1.5 Properties

The Properties button displays the current form dimensions and number of elements.

2.2 Element actions & properties

Each of these buttons places the like-named element on the form, and displays its modifiable properties beneath the action icons (additional informational properties are displayed in the status bar at the bottom of the window). A brief explanation of each element follows.

2.2.1 Text

Clicking a text element allows the following properties to be modified:

• A text edit-list where you enter your desired boilerplate text (terminated with a carriage return), including substitution variables (refer User Guide).
• A scale that scales text relative to the current font-size in use (specified under Settings).
• A style (Normal, Bold, Italic, Underline) which details the boilerplate text style.
• An Alignment (Left, Center, Right) which determines the text alignment.

2.2.2 Field

Clicking a field element allows the following properties to be modified:

• A button that prompts for a List text file. This lets you assign a text list of values to the field which appears as a pick-list at run-time.
• A text edit-list where you enter your desired default text (terminated with a carriage return), including substitution variables (refer User Guide), that appears when the form is run and the field would otherwise be empty.

The field's height and the presence or absence of a text-list determine how it is rendered at runtime:

• Field: cell height is one and no text list is specified.
• Drop-List (read only): cell height is one and an UPPERCASE text list name is provided.
• Edit-List (editable): cell height is one and a text list is specified.
• Scrollable Area: cell height is greater than one and no text list is specified.
• Scrollable Text-List: cell height is greater than one and a text list is specified.

The example below shows each of these:

Note

If a text list is specified at design time but is not located at runtime then it will be dynamically created as a new empty file with a .txt file extension.

2.2.3 Check

The check element has no design-time properties that may be modified. At runtime, check boxes have three states:

1. Empty ("Unknown")
2. Green tick ("Yes")
3. Red cross ("No")

Left-clicking alternates between "Unknown" and "Yes", while right-clicking alternates between "Unknown" and "No".

2.2.4 Diagram

Clicking a diagram element allows the following property to be modified:

• A button that prompts for a Background Image. This lets you assign an image over which you can make graphical annotations at run-time.

2.2.5 Mark

Clicking a mark element allows the following property to be modified:

• A text edit-list where you enter your desired boilerplate text (terminated with a carriage return), including substitution variables (refer User Guide).

At runtime, clicking a mark button will copy its substituted text into a buffer for later use in the Consultation Summary.

2.3 Moving & resizing elements

Moving an element is as simple as left-click dragging it, while a resize is done with a right-click drag. In both cases the red “rubber band” does not “lock” to the grid until after the move / resize has been completed. This makes for a much smoother move/resize experience.

Group selection has been drastically simplified – left-click drag an area, starting at a point not occupied by an element, until all desired elements are highlighted. Then left click drag a second time to move them or click the delete icon to delete them all in one go.

Note that the highlight area is inverted such that underlying elements can be seen, and the highlighted area can be created in any direction.

Warning!

The software allows you to move and size elements such that they overlap each other ... DON'T.

3. Designing good forms

The key to getting the most value out of RecordMan is putting the most value in, and the way to ensure this is to design and use good forms from the start.

While the technical procedure is quite simple, it is both an art and science to create good usable forms that stand the test of time. It is often easier to first review your existing forms before trying to create new digital ones.

3.1 Review your existing forms

Look at your existing forms. What data do you currently capture? How well do your current forms work? Are there lots of blank areas? Do you have to scribble on the back because of a lack of room?

Your current forms have evolved over time. Is the structure and work-flow optimal? Are you capturing all the information you need to? Are you capturing information you do not need or use?

Think about how your forms currently work, and then think about how you would like them to work.

3.2 Design your new digital forms

Don't fall into the trap of just converting your existing paper-based forms into digital equivalents. Here are some simple guidelines to help you get the most out of your new forms:

1. Structure. Make use of headings and boilerplate text to clearly and logically structure and organize your data.
2. Consistency. Some people like labels above their fields, some to the side, some want boilerplate text left-justified, some right-justified, others with a trailing colon; use what suits but be consistent with the style you adopt.
3. Symmetry and Balance. If your form has two columns, make each the same size.
4. Less is more. Single word labels and short, concise phrases make the form easier to work with.
5. White space. Don't try and cram too much information into a single form, leave plenty of white space to break the content up into manageable chunks.