DataNameBase Reference

[This is preliminary documentation and is subject to change.]

The DataNameBase class is the base class for ALL elements used in forms that generate data fields (input fields in forms, and fields in the generated database table).

Class hierarchy

The class DataNameBase is a subclass of the root class TmplItem. That is, all propeties on TmplItem are also on DataNameBase.

See TmplItem Reference.

DataNameBase is an abstract class (it cannot be instantiated). A configurator cannot use this class directly in neither form templates nor the structure file.

DataNameBase properties

Property

Type

Description

DataName

String

Field name in generated database table. See rules for field names.

Most element types generate one field in the database table. A few element types (e.g. OrgUnitPicker) generate 2 fields in the database.

DataName also controls the HTML id(s) in the generated HTML input form (unless the HTMLName property is specified).

ViewName

String

Specifies the "root" name (suffix) of auto-generated database views. When ViewName is not specifed, the "root" name for views is the value of DataName.

ReadOnly

String

When this property is NOT set, input fields are editable (= not read-only) - if security permits, of course.

When this property IS set, it is interpreted as a TOPICA Basic expression, and this expression is evaluated. If the evaluated value is a Boolean value, this value specifies whether this field is read-only or not. If the evaluated value is NOT a Boolean value, an exception occurs.

Examples:

true	The current field is read only (unconditionally).
Not DebugMode	The current field is read-only for normal users, but editable in debug mode.

MapToExternalField

String

Used to map data to some external field, e.g. during import or export.

SetValueOnCopy

String

In copy operations (including patient merge), the default value for each field in the newly created copy record will have same value as in the source record being copied.

There may be situations, where the configurator needs to override this behavior. For example, if some fields must contain values related to the current patient (the patient that the record belongs to). When merging patients, the new records should contain the values from the destination patient (not from the source patient, that would be the default).

Note
Only in TOPICA versions 4.30 and later!

When SetValueOnCopy is blank (the default situation), the field values is copied unchanged.

When SetValueOnCopy is NOT blank, the contents is interpreted as a TOPICA Basic expression. This expression is evaluated, and the evaluated value is set on the newly copied record.

Note

Evaluation of TOPICA Basic expressions take place in some context. Normally, the global variable Patient refers to the patient, that the user has set in context (in case of "patient merege" this i the "source" patient). But in this special case there are 2 patients involved. To implement setting of fields according to "destination" patient, the Patient global variabel IN THIS SCENARIO ONLY refers to the "destination" patient.

Example: On a field holding current patient's first name, set SetValueOnCopy to the value Patient.FirstName.

The global variable Record contains the record begin copied in the "source" patient. So it is possible to access data on the "source" patient using Record. Example: Record.Patient.FirstName will return the first name of the "source" patient.

FillInStatusSelect

Enumeration

XML

Editor

Constant

Description

Optional

FillInStatus_Optional

It is optional to fill in this field.

Even if end user does not fill in this field, no errors or warnings are given.

Required

FillInStatus_Required

This field is "required" (mandatory).

In the input form the field is marked with a single *.

If the user does NOT fill in this field, a warning is generated. The entered data is saved in the database, but the record gets status "incomplete".

NotNull

FillInStatus_NotNull

This field is "required" (mandatory)

In the input form the field is marked with 2 asterisks (**).

If the user does NOT fill in this field, an ERROR is generated. The entered data is NOT in the database.

Furthermore, the generated database field gets the NOT NULL SQL attribute (unless the field is controlled by som other field).

FillInStatusComputation

String

Per default (when FillInStatusComputation is NOT specified), the "fill in status" of the field is determined by the property FillInStatusSelect.

When FillInStatusComputation IS specified, it is interpreted as a TOPICA Basic expression, and this expression is evaluated. If the evaluated value is an Integer value matching one of the legal values for FillInStatusSelect, this values determines the "fill in satus" fo the field.

Tip
When writing the expression, use the constants in the table above.

DefaultLastPrevious

Boolean

Per default, when a configured input form is opened in "create" mode, fields are either empty, or controlled by a TOPICA Basic expression in the Computation property.

In many situations, however, the configurator may want to make fields per default "inherit" values from from previously entered forms (= saved records).

When DefaultLastPrevious is true, the system automatically (without further configuration) computes the latest value entered in any field with same name as the current DataName, in any form on the patient. This value will then be set as the default value of the field.

Caution
Obviously, for this to work, all fields with a given DataName (across all forms), MUST have the same data type, including field length an enumeration values (see field names)!

PublishChanges

Boolean

Set to true to mark this field as a publisher in the "publish/subscribe" functionality (TODO: link to item describing "publish/subscribe").

Computation

String

When this property is set (e.g. not blank), the value is interpreted as a TOPICA Basic expression, and the evaluated value is set in the field as the default value, when a form is opened in "create mode".

Caution
Obviously the type of the evaluated value must be compatible with the type of the field!

PreProcessInstruction

String

When one or more pre-process routines are executed before the form loads, the data computed by these routines is saved in an XML structure (in RAM).

On fields, whose default values should be set according to the data collected by the pre-process mechanism, specify an XPath-expression to get the data from the XML document.

Refer to the DemoPreProcess application for examples on how to use this feature.

RunPreProcessInstructionOnEdit

Boolean

Per default any pre-process mechanism runs ONLY when a form is opened in "create mode" (because the main purpose of the pre-process mechanism is to make it possible to compute default values for fields).

Howevre, in some cases it might be desirable to pre-process mechanism in "edit mode", too. Set RunPreProcessInstructionOnEdit to true to make this happen.

Link

String

This value is for documentation purposes only.

The value is saved in the Data Dictionary.

Description

String

This value is for documentation purposes only.

The value is saved in the Data Dictionary.

ListColumn

Integer

When displaying a group of records in the user interface, the default behavior is to display ALL fields. This is seldom very useful.

One way to override this behavior is to specify an ordering number in the ListColumn property on some of the fields. The system will then list only those fields having a ListColumn value, and order the columns according to the value.

TODO: check that this functionality (still) works, and construct a working demo application.

Note
Another way to customize which fields should be listed in what order is to use the ListQuery computation specified in the structure file.