Documentation XML Form Generator forms

The XML file

The first thing consultants and customers will encounter will be the form XML file. The
XML file provides a structured overview of your forms. All the info your forms should have
is gathered in one forms object: the <forms> element. This root element has the
mandatory attribute initialform, the form which will be shown when the XML Form
Generator is opened. The forms element also allows several optional attributes:
logWarnings(false), showValidationMessages(false), showValidationIcon(true),
enableValidationCss(true), columns(2) and span(1). The root element also holds the
attributes for the schema definitions. The following example would be perfect (and can be
copied as the base for any new xmlform):
<?xml version="1.0" encoding="UTF-8"?>
<forms initialform="menu" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="xmlform.xsd" showValidationMessages="true">
<form name="menu" defaultnextform="submit" >...</form>
</forms>
The form element encompasses a complete page shown in the browser and consists of
one or more rows, with one or more groups, with one or more fields. In this the fields
represent the actual fields on your form. As such, a request could consist of several
forms.
A form element has mandatory name and defaultnextform attributes: the name is a
unique indicator for that form (cannot be 'submit', 'overview' or 'submitoroverview', these
are default names for specific operations), the defaultnextform gives the default form to
be displayed after submitting this form. If the current form is the final form,
defaultnextform=submit will process the entire request, while value overview will
provide an overview of the request with a submit button and value submitoroverview
shows both an overview and a submit button, letting the user chose whether to view the
overview or just process the request right away. Optional attributes are the rows,
columns, preloadlogic and formlogic. The preloadlogic attribute can be used to have
specific information from for instance the database loaded in the form when shown, for
instance filling a callerblock section in the form using:
<form name="caller" defaultnextform="hardware" preloadlogic="callerblock.jsp">
will use a bespoke jsp-file callerblock.jsp to fill (a) certain field(s) in the form, provided
they are declared in accordance with this jsp. The formlogic attribute finally can be used
to add specific javascript files to the current form, for instance a page of javascript to
complete a callerblock after selecting the name of a caller:
<form name="caller" defaultnextform="hardware" formlogic="employeedetails.js">

will have form caller use the employeedetails.js javascript file.

Directly underneath the form element it is possible to add go elements. These elements
can be used to restrict the access to the form, mostly based on one or more attributes of
the current user, but it is also possible to restrict access based on prior information
recorded through forms. The go element has two attributes: toForm and toUrl of which
one is mandatory. It is also mandatory to include at least one when-like child element,
these will be explained after the following example.
<form >
<go toForm=noaccess>
<whenUser matches=achternaam = Ginneken>
</go>
The previous example will redirect any user with a last name of Ginneken to the form
noaccess instead of showing them the form they are attempting to access. In this
example any database field from the persoon or actiedoor' table could have been used
as well as any form field, FOX-PRO expression or resource. Several other when-like fields
can be used:
- when, required attribute: expression. Only form fields and resources can be used.
- whenBranch, required attribute: matches, database fields from the vestiging table
can be used.
- whenDepartment, required attribute: matches, database fields from the afdeling table
can be used.
- whenForm, required attributes: isFilled (true/false) and form.
- whenGroup, required attribute: matches, database fields from the actiedoor (when
used in the operator section) or persoongroep (when used in the ssd) table can be
used.
- whenGroupNot, required attribute: matches, database fields from the 'actiedoor' (when
used in the operator section) or 'persoongroep' (when used in the ssd) table can be
used.
- whenRole, required attribute: matches, database fields from the gebruiker table can
be used. This condition can only be used in the operator section.
- whenRoleNot, required attribute: matches, database fields from the 'gebruiker' table
can be used. This condition can only be used in the operator section.
A row element has the mandatory, unique name attribute and the optional
drawheader(true), columns(2), span(1) and dependencies attributes. The drawheader
attribute has the default value of true, setting it to false will cause the page to not
display the row title and other css items related to the row specifically. With the columns
and span attributes the layout of the groups in this row can be manipulated. By default (in
accordance with TOPdesk Look&Feel) a row has 2 columns and each column has a span of
1. For instance, setting either the columns of a row to 1 or setting the span of a row to
2 will result in a row where every group is the entire width of the browser window. Each
row can contain any number of groups, but grouping is for layout purposes only, no other
information (like headers) will be shown.
A group element has the mandatory name attribute and an optional dependencies,
drawheader(false) and span attribute. It is nothing more then a layout/grouping tag, but
fields must be in groups.

The field elements are the main elements in your form. These hold all the inputs and can
direct the data to the card. The attributes of the field elements depend on the type of
field, although all fields have a mandatory name attribute, which must be unique within
the form. All field have the optional dependencies, mandatory(false),
placeLabel(onLeftSide or onTop for memoField), disabled(false), hidden(false),
inoverview(ifFilled, always, never), activeAfterTabOnField, clearValueWhenHidden(false)
and note(false) attributes (default values in parentheses), some have additional
mandatory and/or optional attributes. For information about the possible validations per
field element one can read the specific documentation on validations. All available field
elements and their additional attributes follow below (TD means TOPdesk styling):
-

textField: A normal input box with a {label [text input box]} set up
memoField: A normal text area (TD) input box, optional attribute rows (number,
controls the height)
- checkboxField: A {checkbox[] label} set up, optional attributes: checked(false)
- checkboxGroupField: A group of {checkbox[] label} inputs with optional attributes
orientation(vertical) and checked(false) has an option list with optional attributes:
selected(false) and note(false)
- radioField: A {label o radio button} set up with optional attributes:
orientation(vertical), has an option list with optional attributes: selected(false),
nextform (a form name) and note(false)
- selectField: A select input box with a {label [dropdown select box]} set up, has
optional attributes: emptyoption(false) and an optionlist with optional attributes:
selected(false)
- suggestField: A autocompleter input box (TD) with a {label [autocompleter box]}
set up, has mandatory attributes: table, optional attributes:
column(naam/ref_dynanaam), displayexpression, parent, parentcolumn, filter,
filterexpression, openLinksInCurrentWindow(false) and disableFilters.
- gridField: A grid of database entries. Mandatory options are: table and columns.
Optional attributes are: filter, filterexpression, columnWidths, searchColumns,
linkColumns, parent, parentcolumn, checked(false),
openLinksInCurrentWindow(false) and disableFilters.
- dateField: A date input box (TD) with a {label [date input box]} set up
- timeField: A time input box (TD) with a {label [time input box]} set up
- datetimeField: A date & time input box (TD) with a {label [date input box][time
input box]} set up
- infoField: A pure text label with a {label note} set up. Optional attributes are:
labelExpression and noteExpression.
- emptyField: A bit of vertical whitespace, purely a layout tool.
- uploadField: An upload box with a {label [file browser]} set up; using these
without validations is not recommended.
The note attributes can have values false(default), text and html. A note will show an info
icon with a mouse-over tooltip which displays a text or html text as defined in the
properties. The selectField emptyoption will show an empty 'null' option which 'doesn't
count as a valid selection' and can therefore be validated where needed. The label for this
text entry can be set in the properties.
The radioField, checkboxgroupField and selectField must have a <data> child group with
all options in the group as <option> children, the option list. The data tag has no
attributes, the option element has the mandatory unique name attribute and an optional
selected(false) attribute. An option may also have the nextform attribute, which
determines the form that is shown if that option has been selected.

<radioField name="gender" note="text" mandatory="true" orientation="horizontal">

<data>
<option name="male" selected="true"/>
<option name="female"/>
</data>
</radioField>
will result in a radio group (horizontal) with 2 radio buttons, the first, Male, is selected, the
second is Female, with an info button. Since this is a radio group, the mandatory attribute
of the field is not needed as soon as one of the options has selected=true.

A suggestField has the most extra attributes: it has a mandatory table attribute, which
should have the value of a TD database table (exact name). It has an optional column
attribute, which can have the value of any of the columns in the aforementioned table. If
no column is entered, it will automatically display the naam column for most tables,
ref_dynanaam for person, etc. If you need to display a combined name you can utilize
the displayexpression attribute which takes a foxpro expression to combine one or more
values of a card.
To mimic the standard TD functionality of category/subcategory or branch/location links,
there are also the optional attributes parent and parentcolumn. The parent attribute
should get the value of the higher level suggest field, the parentcolumn the value of the
column in the source table of the child element that links the two tables.
<suggestField name="branch" table="vestiging"/>
<suggestField name="location" table="locatie" parent="branch" parentcolumn="vestigingid"/>
will provide two autocompleters with the lower one linked to the value selected of the
upper one, both displaying the names of the cards. Additionally, to implement a set of
category/subcategory fields, one needs to add a so-called filterexpression to each of the
suggestFields:
<suggestField name="category" table="classificatie" filterexpression="ISNULL(parentid) AND
incidentbeheer"/>
<suggestField name="subcategory" table="classificatie" parent="category" parentcolumn="parentid"
filterexpression="NOT(ISNULL(parentid)) AND incidentbeheer"/>
where the incidentbeheer condition depends on the module these fields values will be
used in. This filterexpression attribute also allows you to create suggestFields containing
optional search list values:
<suggestField name="optionallist" table="vrijeopzoekvelden" filterexpression="code = 'INCIDENT_1'"/>
As shown,filterexpression causes the fields data source to be filtered on an additional
FoxPro expression, which may also be used to filter on a certain prefix or suffix:
<suggestField name="topdeskbranch" table="vestiging" filterexpression="LOWER(LEFT(naam, 7)) =
'topdesk'"/>
This field will only show branches with a name starting with topdesk (case-insensitive).
If these filtering options do not suffice for your purposes, you can contact the bespoke
work team to develop a custom filter which may then be used by specifying the filter
attribute.
<suggestField name="operator" table="actiedoor" filter="onlyoperatorsinthesamegroupascurrentuser"/>
Here, the filter value is the name tag that can be used for a certain filter on the query on
the TOPdesk database that fills the autocompleter. The bespoke work team will build the
filter as required and give it the name the customer-consultant team thought up for that
specific filter. Once made, the filter can be (re-)used on any suggestField by providing the
filter attribute that name.

Your form will be a lot easier to maintain if, within the form element, every
name is kept unique. Fields must be unique per form, groups per row and rows
per form, so overall form uniqueness is not enforced, but it will make your life a
lot easier.
All values in the XML attributes must be pure letters/numbers, no spaces, no
underscores, no dashes or special symbols. All lower caps is preferred.
One reason to keep your forms unique is the use of dependencies. The attribute
dependencies is an optional attribute which can be used in rows, groups and fields. The
value of this attribute represents a field in the form which has to have a certain value for
the element that has the dependencies to display:
<radioField name="folderaccess">
<data>
<option name="yes"/>
<option name="no"/>
</data>
</radioField>
<textField name="foldername" mandatory="true" dependencies="folderaccess:yes"/>
here the field foldername, a textbox, will be shown if the radio button yes of the field
folderaccess is selected. Then it will also be mandatory.
<checkboxField name="orderhardware" note="text"/>
<selectField name="requesttype" note="text">
<data>
<option name="software"/>
<option name="hardware"/>
<option name="both"/>
</data>
</selectField>
<row name="hardware" dependencies="orderhardware:checked; requesttype:hardware,both"/>
will show the row hardware if the checkbox orderhardware is checked and/or the select
requesttype has hardware or both selected.
The dependencies attribute supports two different syntaxes:
1. The simple and short variant 'orderhardware:checked; requesttype:hardware,both' like the
one above.
2. Or it can be written as a FOX-PRO expression like so: 'form_row_group_orderhardware OR
form_row_group_requesttype = 'hardware' OR form_row_group_requesttype = 'both''
Dependencies are a powerful layout tool, but the best way to see how they work is to just
run some tests with them.

A complete form example:

<form name="form1" defaultnextform="overig" preloadlogic="callerblock.jsp">
<row name="information"></row>
<row name="caller">
<group name="caller">
<textField name="callername" disabled="true"/>
<suggestField name="branch" table="vestiging"/>
<textField name="ref_plaats1" disabled="true"/>
<textField name="telefoon"/>
<suggestField name="location" parent="branch" parentcolumn="vestigingid"
table="locatie"/>
<textField name="department" disabled="true"/>
<textField name="budgetholder" disabled="true"/>
</group>
</row>
<row name="description">
<group name="description">
<suggestField name="typeofcall" table="soortmelding"/>
<memoField name="request"/>
</group>
</row>
</form>
will show up as the following form:

(example form has a filled form properties file, so labels are shown correctly)

These forms will display all name attributes as labels, first letter capitalized, rest lower
case, unless these names have been specified in a properties file. These files hold the
resources for the forms.
The keys and values for the above example would be these:
form1 = Incident ICT Department
form1.information = The ICT department manages all IT related items
form1.caller = Caller
form1.caller.caller.callername = Caller
form1.caller.caller.branch = Site
form1.caller.caller.ref_plaats1 = City
form1.caller.caller.telefoon = Telephone number
form1.caller.caller.ref_locatie = Location
form1.description = Description
form1.description.description.typeofcall = Type of call
In general a key is built up in this way:
formname = value (form title)
formname.rowname = value (row title)
formname.rowname.groupname.fieldname = value (field label)
formname.rowname.groupname.fieldname.optionname = value (option label)
formname.rowname.groupname.fieldname.note = value (value of tooltip)
The properties files can be generated by the tool. After loading the form XML file in the
tool by opening the index page (for the SSD this would be /tas/public/xfg on your TAS) in
any browser, redirect to the URL /tas/public/xfg/tools/?language=en (or nl or de for the
dutch/german language file) and the tool will generate the properties file for that
language. It will provide all possible keys and use any existing properties file as to not
overwrite existing key-value pairs. For new keys, the base value is entered as one can see
when using a valid xmlform without properties. Leaving a value empty results in an
empty label as would be expected. If you have modified a properties file you should note
that it should be saved as an UTF-8 encoded textfile (Using wordpad as an Unicode text
document). If you do not save it in that encoding non ASCII characters such as a will
not be rendered correctly.