Creating Character-Based Layouts

This section describes designing character-based data entry layouts used for data entry in Oracle Clinical. If you are using RDC Onsite, see Creating Graphic Layouts

Two tools help you create data entry form layouts:

• Default DCM Layout Generator Creates an initial layout of data entry fields on a DCM by reading its DCM Question, DCM Question Group, and DCM definition information. This tool takes as input the preferences specified in the DCM definitions—including prompt position, prompt text, and Question sequencing—which makes it capable of generating several different styles of DCM layouts.

  Note:

  The Default Layout Generator assigns a display order to each field from left to right and top to bottom according to the DCM Question's Disp Seq# (Display Sequence Number) value. If the Disp Seq# values are changed for the DCM Questions, the existing layout is not affected and the 'Regen Reqd?' flag for the DCM is not checked. The display order of the fields in the character layout is changed only when the layout is defaulted again.
• DCM Layout Editor. Use the DCM Layout Editor to customize the appearance of default layouts, refining the DCM's interface to be more intuitive for data entry.

The basic steps to create data entry screens are:

1. Generate a default layout for the specified DCM.
2. View the default layout with the DCM Layout Editor.

   Optionally, return to the DCM and change default settings and regenerate the default layout.

3. Modify the default layout with the DCM Layout Editor.
4. Test the layout by using it in the test environment.
5. Move the layout from the test environment into production.

For more information, see:

• Creating Default DCM Layouts
  
• Creating Additional Layouts
  
• Editing DCM Layouts with the DCM Layout Editor
  
• Sequencing Data Entry
  
• Using Data Entry Forms in Test and Production Modes
  

Creating Default DCM Layouts

To create a new DCM character-based layout:

1. Put your cursor on an existing DCM that you want to create a layout for. If the DCM has more than one subset, select the one for which you want the new layout.
2. In the Special menu, choose Default Character Layout. A message appears in the status bar stating that a layout has been successfully created, and the system sets the Data Entry Generation Time value. You can see the timestamp in the Character Layout tab.

Creating Additional Layouts

You can create multiple layouts for the same DCM; for example, layouts in German and French. If a DCM has multiple subsets, you can create multiple layouts for each subset.

To create an additional layout for a DCM, from the Data Collection Modules window, do the following:

1. Put your cursor on an existing DCM that you want to create a layout for. If the DCM has more than one subset, select the one for which you want the new layout.
2. In the Special menu, choose Create DCM Layout. The system creates a new layout with the Layout number incremented by one.
3. In the Description field, explain the purpose of the new layout.
4. If you want to prevent a Question from being displayed in the new layout, click the Questions Group button, select the Question's Question Group, click the Questions button, and deselect Displayed? for the Question.
5. Edit the new layout (see Editing DCM Layouts with the DCM Layout Editor).

Editing DCM Layouts with the DCM Layout Editor

The DCM Layout Editor allows you to modify data entry forms to more closely resemble CRFs, to improve the efficiency of data entry, or to add on-screen information. The DCM Layout Editor can display all the Questions in a particular Question Group, including all repeating instances of fields. The ability to create more than one layout for a single DCM, combined with the ability to tailor each one, means that you can create different layouts for different uses.

An example of this flexibility is a case where two laboratories collect data in different Question sequences and with different labels. You need create only one DCM in Oracle Clinical, with two layouts tailored to each laboratory's usage. The use of different DCM layouts does not affect the underlying structure of the DCM, nor the organization of the resulting data in the database.

To open the DCM Layout Editor:

1. From the Definition menu, select DCMs, then choose DCMs.
2. Select the DCM to edit
3. From the Special menu, select Edit Layout.

   The DCM window opens the DCM Layout editor in a new window. All windows in your session remain open. If you return to your session, you see a message stating that a Layout Editing session is in progress. (Check that you have saved your work in the DCM Layout Editor, if necessary, before closing this message box.)

For more information, see:

• Parts of the DCM Layout Editor
  
• Positioning Objects
  
• Selecting Objects
  
• Editing or Adding Text
  
• Adding Boxes
  
• Moving Objects
  
• Arranging Objects
  
• Deleting Objects
  
• Resizing Objects
  
• Controlling Spacing and Sizing of Objects
  
• Changing Page Numbers of Objects
  

Parts of the DCM Layout Editor

The DCM Layout Editor window has a menu, a toolbar, a work area, and—at the bottom of the window—a task bar. A sample detail of the DCM Layout Editor's window follows:

Description of the illustration dcmlay01.gif

Objects are any selectable parts of the layout: response fields, field labels, text, and graphic shapes. In the sample illustration above:

• ddd is the label text

• ALLERGIC_REACTION is a Question name, and the surrounding white box is the representation of the field's shape and position in the corresponding data entry form.

Positioning Objects

The DCM Layout Editor allows positioning objects within a character grid in one-character increments. The administrator of the Web server controls the character grid size by changing registry settings (described in Appendix A of the Oracle Clinical Administrator's Guide).You can display an overlay of the character grid on your workspace by dropping down the View menu and selecting the Show Grid box. Rulers along the top and left sides of the work area display the coordinates of the cursor position. (The numbers on the ruler represent tens of characters; the number 1 represents ten characters.) You can also see the exact position of a selected object, or the mouse pointer, in the left-side corner of the taskbar.

Selecting Objects

Selected objects display pull handles (small black squares at the corners and midpoints).

Selecting Individual Objects

To select one response field, field label, or text object: with the selection tool, click inside the borders of the object. For a box object, either position the point of the selector over the border of the box and left-click, or position the cursor inside the box and click-drag in a diagonal direction.

Selecting Contiguous Objects

To select all the objects in an area of the layout: Click-drag the selector in a diagonal direction across the area.

Selecting Non-contiguous Objects

You can Control-click to select or deselect objects regardless of their geographic location in the layout. If you are Control-clicking a box, note that you must position the pointer of the selector tool directly on its border.

Editing or Adding Text

The DCM Layout Generator creates text objects of the Questions' Default Prompt values, referred to sometimes as boilerplate text. You can change the text in these objects as well as in new text objects you add to the layout. To edit the text in a text object, double-click the object. The system changes to text edit mode. To stop editing a text object, click outside the text object.

You can add extra text objects to the layout. Text objects cannot exceed one character in height. (Stack multiple text objects to create multiple lines.) To create new text objects:

1. Click the Text button in the tool bar.
2. Position the mouse pointer in the layout at the position where the text starts. You can see the character grid location of the pointer on the rulers and in X,Y character coordinates on the taskbar.
3. Click. The system places a text field in the layout, snapped to the coordinates of the closest positions in the character grid, and changes to text editing mode.
4. Enter the text.

Your organization sets the DCM layout text font characteristics with registry entries on the Web server computer. For text objects, the registry entry is OC_DE_TEXTFONT. For field text, the registry entry is OC_DE_FIELDFONT. Note that these registries control layout screens and data entry screens.

Adding Boxes

You can add ruled rectangles, or boxes, to enhance the usability of the data entry form. You can, for instance draw a rectangle around a Question Group to indicate to the data entry operator that the fields are related.

1. Click the Rectangle button in the toolbar.
2. Position the mouse pointer in the layout at the point of a desired corner. You can see the character grid location of the pointer on the rulers and in X,Y character coordinates on the taskbar.
3. Click and drag the pointer diagonally to the desired position of the opposite corner. The system places a text field in the layout, snapped to the coordinates of the closest positions in the character grid.

Moving Objects

You can move objects with either the mouse or with your keyboard's arrow keys. All movements increment to the closest position on the character grid.

Moving an Object with the Mouse

You can move an individual object with the mouse. For a rectangle object, place the tip of the mouse pointer on the perimeter of the rectangle. (Try to avoid the midpoints and corners, which are the locations of the grab handles.) Mouse-click and hold while you drag the rectangle to a new position. For any other type of object, place the tip of the mouse pointer within the object's perimeter, then mouse-click and hold while you drag the object to another position.

Moving Objects with the Keyboard Arrows

You can move one or more selected objects with the keyboard arrows. This approach is effective for maintaining the geographic relationship among a local set of objects (for instance, response fields and their labels), while moving them.

Arranging Objects

The DCM Layout Editor has a set of tools for aligning selected objects, and a tool for controlling the distance between repeating Questions.

Aligning Selected Objects

The DCM Layout Editor has six tools for systematically aligning groups of selected objects by the objects' axes or borders. You invoke the tools either from the Arrange menu or from toolbar buttons. Position the mouse pointer over a symbol to read a description of how it aligns selected objects.

Setting Distance Between Repeating Questions

You can adjust the spacing between repeating Questions. Select a set of repeating Questions, then from the Arrange menu, select Lines Per Repeat. The Lines Per Repeat dialog box opens. The lines per repeat increment corresponds to the character grid. Enter a number and click OK. The system adjusts the distance between repeating Questions a corresponding number of character cell increments.

Note:

The Lines Per Repeat spacing tool only works for Question Groups with a prompt position value of 'L.' Its prompt position must be set to the Left radio button in the DCM Question Groups dialog box. (See Creating and Maintaining Question Groups for more information.)

Deleting Objects

To delete an object, select it and press the Delete keyboard key, or use the keyboard combination Control-X. Alternatively, from the Edit menu, select Delete. If the object is a non-expendable part of the DCM, deleting without pasting generates an error message.

Resizing Objects

You can change the height and width of rectangles and text objects, and the lengths of text fields. You can also systematically resize a group of selected items in one operation.

Resizing Individual Rectangles or Text Objects

Select the object to expose its pull handles (small black boxes at the midpoints and corners of the object). Place the point of the mouse pointer over a pull handle. Click and hold while you drag the pull handle. You must pull the handle at least one character length for a change to take place.

Resizing Individual Response Fields

You can only lengthen the width. Select the field to expose its pull handles. Place the point of the mouse over one of the drag handles at either end of the field. Click and drag the handle at least one character length.

Resizing Widths of Multiple Selections

Use the tools in the Resize menu to change the widths of all selected objects to a uniform size, either:

• the shortest selected width

• the average of all of the selected widths (to the nearest character)

• the longest selected width

Controlling Spacing and Sizing of Objects

Layout controls are independent of the default font setting. These controls enable you to specify the spacing of the objects in your data entry layouts and the length of field. The values are in pixels.

You control the appearance of the data entry panel (the lower panel in the data entry window), with parameters de_gridwidth and de_gridheight. You must set these values.

You adjust the width of list of values columns in the data entry form with the parameter de_lgridwidth. This parameter is optional. If you don't supply a value, the default value is 11 pixels You adjust the size character width of List of Values entries in data entry screens with parameter de_lgridwidth.

To adjust these values, edit file formsweb.cfg, which is located at oracle_home\forms60\server. Follow these instructions:

1. Open formsweb.cfg in a text editor.
2. In the [opa45] section, find the line that begins: form=opamenu.fmx.
3. Add the following text string to the end of this line:

   de_gridwidth=number de_gridheight=number

   Where number is the parameter value (in pixels) you choose.

4. Save and close formsweb.cfg.
5. Test your settings by opening a data entry form.

For default DCM data entry layouts, Oracle recommends you use de_gridheight=18 de_gridwidth=7. If you re-arranged objects in earlier layouts, Oracle recommends you use de_gridheight=27 and de_gridwidth=10. DVG LOVs are objects in the bottom panel of the data entry form. To adjust the width of DVG list of valueslist of values columns, add to the otherparams line: de_lgridwidth=number Where number is the parameter value you choose. If you do not add this line, the system sets the de_lgridwidth default value to 10.

Here is a sample text string for new default layouts:

form=opamenu.fmx term=opahome\opa_fmrpcweb.res de_gridheight=18 de_gridwidth=7

Here is a sample text string for revised default layouts:

form=opamenu.fmx term=opahome\opa_fmrpcweb.res de_gridheight=27 de_gridwidth=10

Changing Page Numbers of Objects

Select the object(s) you want to move to another page. Select Cut to move to the clipboard. Use the Page list to move to the page where you want to place the object(s). Select Paste, then click where you want to place it. The editor pastes objects at the clicked mouse location if they fit there. Otherwise they remain in the clipboard, and an error message appears.

The following are the function of each menu entry:

• File
  • Save - Update the database with the current version of your edits.
  • Validate - Test that the layout conforms to layout rules that prevent, for instance, overlapping fields.
  • Revert - Select Revert to return to the previous saved version without exiting the Layout Editor.
  • Exit - This choice performs a number of tests to ensure that the current layout conforms to DCM and layout rules.
  • Exit without saving - Choose this entry to bypass conformance checks. (The system still prompts you if you have unsaved work.)
• Edit
  • Cut - Copy the selection to the clipboard and remove it from the layout. (Control-X)
  • Copy - Copy the selection to the clipboard. (Control-C)
  • Paste - Place the contents of the clipboard on the current page. (Control-V)
  • Undo - Return the layout to its state prior to the last action. (Control-U)
  • Redo - Return the layout to its state prior to the last Undo.
• Resize
  • Resize to smallest width - Adjust the width of selected objects to the width of the narrowest selected object in one operation.
  • Resize to average width - Adjust the width of selected objects to the average width of the selected objects in one operation.
  • Resize to largest width - Adjust the width of selected objects to the width of the longest selected object in one operation.
• Order
  • Order by clicking
  • Order by entering Sequence Number
  • Display
  • Order Current Page by Row/Column
• View
  • Show Grid box
  • Zoom (radio buttons for various magnifications)
  • Center on selection box
• Arrange
  • Lines Per Repeat
  • Align Left
  • Align Middle Horizontally
  • Align Right
  • Align Top
  • Align Middle Vertically
  • Align Bottom
• Page
  • Next
  • Previous
  • Insert
  • Delete - You must first delete or move elsewhere all objects on the page; otherwise the editor displays an error message and prevents you from continuing.
• Help
  • Help - Opens context-sensitive HTML-based extended online help.

Sequencing Data Entry

A data entry form has a cursor visitation order: the order in which the response fields become active as a data entry operator completes them. The default Layout Generator assigns visitation order values to each field from left to right, top to bottom according to the Questions' Disp Seq# values in the DCM Questions form. Until you use the DCM Layout Editor's Order utility, fields retain their default visitation order values, even if you move them in the Layout Editor. If a default or modified layout does not have the most efficient or intuitive visitation order, you can resequence the values.

To display a layout's cursor visitation order, from the Order menu, select Display. The DCM Layout Editor replaces each response field's Question name with its cursor visitation order value. To simplify reordering, the values are multiples of 10. For instance, the DCM's first active field has a value of 10, and the next field in the visitation order has a value of 20. (You cannot adjust the visitation order from this menu path. See the following sections for changing the visitation order.) The system replaces the layout toolbar with the ordering mode toolbar.

There are three visitation ordering tools, each described in the following sections.

Note:

You cannot insert the visitation order value of a Question into the visitation order sequence of a repeating Question Group unless it is a member of the repeating Question Group.

For more information, see:

• Ordering by Row and Column
  
• Ordering by Clicking
  
• Ordering by Entering Sequence Numbers
  
• Validating a Layout
  
• Saving a Layout
  
• Closing the Editor
  
• Laid Out Versus Not Laid Out Objects
  
• Using Undo or Revert
  

Ordering by Row and Column

When the system generates the default layout it assigns a visitation order to the fields from left to right, from top to bottom. You can assign this same visitation order scheme to a rearranged layout. The row/column visitation order might suffice for data entry, or you can use it as a starting point for further manipulation with one of the other ordering tools. Navigate to Order, then Order Current Page by Row/Column. With this tool you remain in layout mode. (To view the results, from the Order menu, select Display. To return to the layout after viewing the visitation order, click the Exit button in the toolbar, which appears in the editor's toolbar as a doorway.)

Ordering by Clicking

Use the Order by Clicking tool to set the visitation order by clicking each successive field in the layout: click once in the field you want to be first, then click once in each successive field in the new order. As you click each field, the system automatically adjusts the order values of the remaining fields. Note that once you have clicked as many times as there are fields, continued clicking assigns the last sequence number with each click.

When you finish ordering, click the Door-close button in the toolbar to return to layout mode. Or, if you are unsatisfied with the results of your pass through the fields, click the Door-close button. You can then reopen the Order by Clicking tool (or Order by Entering Sequence Numbers, described next), and start again.

Ordering by Entering Sequence Numbers

You can select a field and change its visitation order by entering a value. From the Order menu, select Order by Entering Sequence Number. You select a field and enter a number, and the system adjusts the values of all other fields accordingly. You can either enter the values manually or with the plus and minus incrementing buttons, described in the next sections.

Reordering Manually

To insert a field's visitation between two consecutively ordered fields, assign the inserted field the greater value. (You can also assign a value between the two values.) The system renumbers the fields to the new sequence. As an example, a rearranged layout might have a visitation order like:

Field	Visitation Order Number
WEIGHT	10
HEIGHT	40
BIRTHDATE	20

To sequence the visitation order of these fields top to bottom, change the value of HEIGHT from 40 to 20 (or, for instance, to 15), and select another field. The system reorders the fields to:

Field	Visitation Order Number
WEIGHT	10
HEIGHT	20
BIRTHDATE	30

Reordering with the Plus and Minus Buttons

The Order by Entering Sequence Numbers tool also includes Plus and Minus buttons in the toolbar that you can use to change individual sequence values. You select a field, then click either button to change its value by one value. In the example in the previous section, to change HEIGHT from 40 to 20, you would select 40, then click the Minus button twice. The results are the same as manually entering 20.

Validating a Layout

The DCM Layout Editor includes several constraints to prevent lost objects or other layout errors. When you save a layout the system tests if it is valid. You can invoke these tests on a layout before you save it. From the File menu, select Validate. You can check that your layout meets the following constraints:

• There must be at least one Question requiring data on each page.

• At least one Question must follow an indicator Question in the cursor visitation order.

• Objects cannot overlap.

• For Question Groups:

  • An indicator response field must be the first response field visited by a cursor in a Question Group.

  • A response field cannot be physically on the same row as a response field in a repeating Question Group, unless the two response fields belong to the same Question Group.

  • The cursor visitation order of a Question cannot place a response field between two response fields of a repeating Question Group unless all three response fields are part of the same Question Group.

  • All of the response fields of a repeating Question Group must be located on the same page.

  • If the Prompt Position Type field is "L" (left), the distance between response fields must be less than the number of lines specified by the lines per repeat for that repeating Question Group. For instance, if lines per repeat is 3, response fields cannot be more than 2 rows apart. If lines per repeat is 1, response fields must be on the same row. Note that the lines per repeat is one less than the LINES_PER_ROW specified in the database.

  • For repeating Question Groups where Prompt Position Type field is "A" (Above), lines per repeat must be one in number.

When you test validation or save, the system displays a log of any errors.

Saving a Layout

You can save your work even if a layout does not pass validation. In that case you receive a message that the layout is invalid. You can save your work, but you cannot move the DCM to production until you reopen the DCM and fix the errors.

Closing the Editor

You can exit by menu path or the Door-close button in the toolbar.

The system prevents you from modifying a DCM while the Layout Editor is open, and displays a warning if you attempt to access the Maintain DCMs form.

Laid Out Versus Not Laid Out Objects

If you make changes to a DCM after you have generated a default layout, the system automatically collects any new objects into a Not Laid Out area and activates the Not Laid Out button in the toolbar. In fact if you have not generated a default layout and you open the DCM Layout Editor, all the DCM's objects are in the Not Laid Out area. In order for a layout to pass validation, you must move all of these objects from the Not Laid Out area to the Laid Out area:

1. Click the Not Laid Out button to open the Not Laid Out area.
2. Select one or more objects. (See Selecting Objects.)
3. Cut (Ctrl+X) the objects. This action removes the selected objects from the current area and makes a copy of them in the Windows clipboard.
4. Click the Laid Out button in the toolbar to return to the layout area.
5. Paste (Ctrl+V) the objects.

Using Undo or Revert

To undo the last action, from the Edit menu, select Undo last action (where the system determines the type of action).

To return the state of your layout to the previous saved version without exiting the Layout Editor, select Revert.

Using Data Entry Forms in Test and Production Modes

You can test DCMs and layouts by doing data entry in test mode; see Test Mode for more information.

In this section:

• Character-Based Layouts in Test and Production Modes
  
• Graphic Layouts in Test and Production Modes
  

Character-Based Layouts in Test and Production Modes

If you are working with character layouts, you explicitly move the layout to production upon finalizing your DCM layout. The requirements for test and production data entry are:

• Test mode requires that DCMs have a valid layout. The status of the DCM can be either provisional or active. It does not matter if the DCM layout has been moved to production or not.

• Production mode also requires a valid layout. It is possible to move the layout for a provisional DCM to Production, but Oracle recommends moving layouts to production for active DCMs only.

To move a character-based DCM layout to Production:

1. From the Definition menu, select DCMs, then choose DCMs.
2. Select the Character Layout tab, then the DCM layout you want to move to Production.
3. From the Special menu, select Move to Prod. The system updates the Production Generation Time field. The DCM is then ready for data entry.

Graphic Layouts in Test and Production Modes

If you are using graphic layouts in RDC, you must embed your DCM layouts into a DCI Form; see Creating Graphic Layouts The requirements for test and production data entry are:

• Test mode requires a valid DCI Form. The status of the DCI can be either provisional or active. If both are available, the system uses the provisional version and its provisional, valid DCI Form version. If the DCI is active and both provisional and active DCI Form versions are available, the system uses the provisional version.

• Production mode requires an active DCI and an active DCI Form version.