Working with Forms

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

This topic discusses some overall considerations when contructing form templates.

A form template is an XML file. Elements in such XML files are called form template items. Template items may be nested inside other template items - according to some rules.

The form template XML files may be edited by the tools described in editing tools.

This topic only gives an overview of som of the possiblities. For details, go to the forms reference.

Form template items may be divided into several logical groups:

Form element
Layout
Data fields
Array tables
Embedded views/reports
Include elements

Form element

The "root" of the template item hierarchy must always be a Form element.

Layout

It is possible to place data fields directly in the Form element. But normally, this will not look very good (poor aligment).

Decide on some overall layout - depending on the number of fields in the form. For example, if the form will contain more fields that are easily visible in a browser window without scrolling, consider organizing the fields using TabSet elements.

Form template items used for layout include:

Type	Description
TabSet	Must contain TabSet elements - nothing else.
Table	Placing fields in a table ensures aligning of the input fields, even if captions have different lengths. Fields may be displayed vertically in 1 column (default), vertically in multiple columns, or horizontally.
Group	No alignment of fields.
TemplatePanel	No alignment of fields. Option to show/hide contents.
Grid	Alignment of fields in a grid / matrix organization Must contain GridRecord elements - nothing else. Each GridRecord should contain similar fields.

These element types may be nested. Some common scenarios include:

Tables

Copy

Form
    Table
        field1
        field2
        field3

Tab set with tables

Copy

Form
    TabSet
        Tab1
            Table
                field1
                field2
                field3
        Tab2
            Table
                field4
                field5

Some fields always visible, others in Tab set

Copy

Form
    Table
        field1
        field2
        field3
    TabSet
        Tab1
            Table
                field4
                field5
                field6
        Tab2
            Table
                field7
                field8

Data fields

All template item types, that have the DataName property (except the Form element type) are considered "data fields". Each "data field" occurring in a form will generate one (or more) column(s) in the generated database table.

Important
See field names for rules regarding how to use DataName!

Type	Description
TextLine	Single-line text field.
TextArea	Multi-line text field - plain text (no formatting).
RichTextArea	Multi-line text field - with formatting.
TextInteger	Integer field.
TextFloat	Floating point number field.
TextDate	Date field.
TextDateTime	Date/time field.
Checkbox	Values: true / false Any number of template items may be placed below a Checkbox. Thise items will be visble when then Checkbox is checked, hidden otherwise.
DropDown	Must contain Option elements. Any number of template items may be placed below each Option. Thise items will be visible when the Option is selected, hidden otherwise.
DropDownSQL	May NOT contain Option elements! The configurator defines the contets of the dropdown using an SQL query. The SQL Query may contain "embedded" TOPICA Basic, which makes is possible to build the SQL query according to the context.
List	Must contain Option elements. Any number of template items may be placed below each Option. Thise items will be visible when the Option is selected, hidden otherwise.
RadioButtonGroup	Must contain RadioButton elements. Any number of template items may be placed below each RadioButton. Thise items will be visible when the RadioButton is selected, hidden otherwise.
RadioButtonTable	Must contain RadioButton elements. Radio buttons and captions are aligned in separate table columns. Any number of template items may be placed below each RadioButton. Thise items will be visble when the RadioButton is selected, hidden otherwise.
OrgUnitPicker	Specialized to select OrgUnits. This is an exception from the general rule that one field in the form generates one column in the database. This is because the key of an OrgUnit is a combination of 2 fields: (Type, Code). To make it easer to join etc. when extracting values from the database, each OrgUnitPicker field generates 2 database columns. Example: An OrgUnitPicker having DataName = "SelectOrgUnit" will generate 2 columns in the database: SelectOrgUnit_TYPE and SelectOrgUnit_CODE.
EmployeePicker	Specialized to select employees (users).

Array tables

1:N-relations - also known as "master/detail" relationships - may be handled in different ways:

1:N-relations may be implemented in the structure file, but this results in that each "detail" row must be entered in a separate form and submitted one at a time.
If it is a requirement, that ALL "detail" rows should created/entered as part of the "master" form (and submitted automatcally when the the "master" form is submitted) use the ArrayTable element.
The DataName value of the ArrayTable element is used to generate a table for the fields defiend in the ArrayTable.

Important
Several features, that work perfectly on "normal" fields (that are NOT placed inside an ArrayTable) will NOT work on fields INSIDE an ArrayTable. Examples: In an ArrayTable it is only possible to place "simple" data fields - it is impossible to add "layout" elements (that may contain many data fields). The validation rules (that may be used to validate fields againts each other before form is submitted) does not work. Checking / manipulating fields in an ArrayTable using JavaScript is doable - but very difficult! Do not place many fields inside an ArrayTable - otherwise the generated form will be very wide (making horizontal scrollbars appear). If these limitations cause to much problems, consider using the structure file (optionally combined with th the SubForm element) to implement 1:N relations.

Important

Several features, that work perfectly on "normal" fields (that are NOT placed inside an ArrayTable) will NOT work on fields INSIDE an ArrayTable. Examples:

In an ArrayTable it is only possible to place "simple" data fields - it is impossible to add "layout" elements (that may contain many data fields).
The validation rules (that may be used to validate fields againts each other before form is submitted) does not work.
Checking / manipulating fields in an ArrayTable using JavaScript is doable - but very difficult!
Do not place many fields inside an ArrayTable - otherwise the generated form will be very wide (making horizontal scrollbars appear).

If these limitations cause to much problems, consider using the structure file (optionally combined with th the SubForm element) to implement 1:N relations.

Embedded views/reports

Per default, an input form does not display any data, that is not directly entered in this form. In som cases it is helpful for the end user to be able to see some addiltional data.

In order to implement this, the configurator may use the following template item types to display such additional data.

Type

Description

View

The configurator may write a computation in TOPICA Basic. The result of this compuation is displayed in the form.

Used to display a single (or a few) values.

TableView

The configurator may write any SQL query against the database (or even against some other database). The resulting "result set" is display in a table. The column names in the reulst set will be used as column headers.

The SQL Query may contain "embedded" TOPICA Basic, which makes is possible to build the SQL query according to the context.

Caution
There is no "paging" mechanism - i.e. all rows returned by the query are displayed in the table.

IFrame

Used to display any page (specifed by an URL) "inline" in the generatd form (inside an iframe tag). This URL might for example refer to a custom webform.

The URL may contain "embedded" TOPICA Basic, which makes is possible to build the URL according to the context.

Include elements

The Include element is used to include the contexts of some other file in the generation of fields in the database AND generate the input form.

This is a feature that is very usable for organizing the form template files. This may be used for the following types of files:

Filename extension

Usage

Description

.xml

"Include" forms.

This is particularly useful, when a field or a group of fields should be used in more than one form.

Using this feature ensures, that changes to fields in this of fields may be done in one place, and changeds will automatically affect all the forms, that includes this "include file".

Such include files may be nested - e.g. a form A may include file B that includes file C, etc.

Note

As stated earlier, all form template files have a Form element at the top. This also goes for "include files". The include mechanism strips the top Form element in each included file, so the resulting form template will still only contain 1 Form element at the top.

Also, layout elements like Table are automatically merged.

FormMain.xml

Copy

Form
    Table
        field1
        field2
        Include "IncludeA.xml"

IncludeA.xml

Copy

Form
    Table
        field3
        field4

Result after include

Copy

Form
    Table
        field1
        field2
        field3
        field4

.inc

JavaScript

Obsolete - use the .js extension in stead.

.js

JavaScript

It is cumbersome to write JavaScript in the editor. It is way easier to write JavaScript in external files, and the in include these files using the Include element.

The reason for using .js extension in stead of the now obsolete .inc is, that tools like Visual Studio makes in much easier to write JavaScript ("intellisense"), when the file extension is .js.

Note that the contents of the referenced file is included in the form template after the include operation. Theroetically it might be sufficient to a a reference to the eternal JavaScript file - but this is NOT have it is implemented. As the entire text is included, there will be no issues with caching the JavaScript files,

.htm

Include any HTML

Include any HTML file.

Note
The text in the included file is inserted directly in the generated HTML page (form). The HTML page being generated will already contain standard tags like <html> and <body>. So the "HTML" file being included should NOT contain such tags (in other words - it should contain an HTML fragment - it should NOT be a full HTML file)!