XForms Graphical User Interface (GUI) Specification - Part 2

OpenOffice.org 2.0 and StarOffice 8

Document - ID	Specification Owner	Last Change	Status
	Frank Schönheit	2005-06-08	draft
Conforms to	
Applies to	XForms module, Writer
Task ID(s)	
Category	Feature

Abstract

XForms is an international standard for web forms. OO.org is able to create and edit XForms compatible forms. Part 2 of the specification describes the graphical user interface for designing form controls which live in XForms compatible form documents.

i-Team Members (The specification owner is part of the i-Team)

	Name	E-mail Address
User Experience	Frank Loehmann	Frank.loehmann@sun.com
Development	Daniel Vogelheim	Daniel.vogelheim@sun.com
Quality Assurance	Marc Neumann	Marc.neumann@sun.com
Documentation	Uwe Fischer	Uwe.fischer@sun.com

Approved for Implementation

	Approved by	Date
User Experience		
Development		
Quality Assurance		
Documentation		
String Review	Elizabeth Matthis	20.08.04

Document Change History

Rev. Level	Change	Initials	Date
0.1	initial public revision	FS	2004-07-22
0.2	check boxes can also be bound to "string" any "anyURI" suggested by FL bindings expressions not validated anymore (chapter "The 'Bind expression' property") spelling/grammatical errors corrected proper references to the "Add Condition" dialog in part 1 of this spec new chapter "Providing list entries for list and combo boxes" list and combo boxes now can be bound, too – to exactly the same data types as text fields	FS	2004-08-04
0.3	data type names adjusted to what is defined in part 1 of the spec	FS	2004-08-09
0.3.1	linguistic review, finalization of strings	LIZ/FS	2004-08-24
0.3.2	adjust two termini to part 1 of the spec, according to Issue 34461	FS	2004-09-24
0.3.3	adjusted to the current implementation state. In particular, the Pattern facet will not be supported in the first version	FS	2004-11-01
0.3.4	Pattern is back alive	FS	2004-11-02
0.3.5	no "Form properties" in XML form documents (36484)	FS	2004-11-12
1.0.1	introducing a Binding property, which explicitly specifies the name of an existing binding to use for a control. (49019)	FS	2005-06-08

Contents

Glossary	1

Legend	1

1	Motivation	1

2	User Scenarios	2

3	Goals	2

4	Requirements and Dependencies	2

4.1	Requirements	2

4.2	Technical Dependencies	2

5	Competitive Analyses	2

6	Detailed Specification	2

6.1	Binding a form control	2

6.1.1	Defining the data binding	2

Choosing the bound node	2

The "XML data model" property	2

The "Bind expression" property	3

6.1.2	Binding properties	3

6.1.3	Validation settings	4

The Data type property	4

Administrating data types	5

Restricting available data types	6

Data type facets	7

Common facets	7

String facets	8

Boolean facets	8

Decimal facets	8

Common facets	9

6.1.4	Providing list Entries for list and combo boxes	9

6.1.5	Hiding Properties	10

Validation-related Properties	10

Database-binding related properties	10

6.1.6	New properties	10

Reference value (unchecked)	10

6.2	Submission	11

6.2.1	Using buttons for data submission	11

6.3	Miscellaneous	12

7	Future Tasks	12

8	References	12

Glossary

Term	Description
XForms	The XForms markup language describes the behavior of electronic forms. XForms markup must be embedded into a host language, which describes the form except for the actual form controls. In our parlance, XForms describes the form layer. Typical host languages for XForms are W3C's XHTML and SVG.
data model	A data model stores the data a user enters into a form. One could say a data model constitutes the entirety of all data items. There can be different data models, such as an XML data model, or an SQL data model.
binding	StarOffice Enhanced Forms distinguish between a form user interface element (a control) and the data store (a data item). A control must be bound to a data item, to make the control store its data in said data item. The programmatic representation of this connection between a control and a data item is called a binding.
property browser	A component for inspecting and modifying (form related) objects such as → form controls.
property	the smallest possible aspect of a → form control which can be modified in the → property browser
form control	Form controls are document elements which behave like well-known user interface elements in usual applications, such as option buttons, check boxes, input fields, and the like. Controls can appear in any of OpenOffice.org's document types.
logical form	Technically, → form controls are organized in a hierarchy. A document can contain one or more logical forms, and every logical form can contain one or more other logical forms, and one or more → form controls. For SQL → data models, logical forms have a high relevance, as they specifiy the data to display in a database form document. For XForm documents, logical forms don't have any importance, since all relevant settings are available at → form controls or the XML → data model.
inspection	the process of displaying and changing the properties of a form control in the → property browser

Legend

Throughout the document, some character styles are used to indicate various things. In particular:

This kind of text denotes a property name, as to be seen in the property browser.

This kind of text denotes a form control type.

This kind of text denotes a property value, as to be seen in the property browser.

This text denotes technical explanations which are not important to readers other than engineers implementing the specification

Motivation

See the first part of this specification for a motivation.

User Scenarios

See the first part of this specification for possible user scenarios.

Goals

See the first part of this specification for goals of the implementation described in both specifications.

Requirements and Dependencies

Requirements

n/a

Technical Dependencies

n/a

Competitive Analyses

n/a

Detailed Specification

Binding a form control

In XML forms, the "Data" tab page of the property browser will be replaced by a version dedicated to binding form controls to nodes of the XML model of the document. This new tab page allows the user to modify two aspects: The binding itself (which is determined by properties such as Required, Constraint, etc.), and the XSD data type which the control should be validated against.

The appearance of this page will follow the usual appearance of the property browser. In particular, every property is represented by one line in the browser, which allows inputting data of various kind (e.g. free text, or a list selection).

Defining the data binding

Choosing the bound node

Binding a form control to a node requires to define an XForms model, and a binding to use for the control. Bindings can either be chosen from a list of bindings which exist in the document (and which are usually defined via the Data Navigator), or newly created. In addition, the properties of the current binding (such as its XPath expression) can be edited within the property browser.

The "XML data model" property

For the XML data model property, a drop down lists presents the names of all XML models present in the document. For newly created controls, the first available model is automatically selected, if there is at least one model.

Note that this list simply allows a selection of a model, not a complete administration of the models (i.e. insertion, removal, renaming, etc.). This is the task of the Data Navigator.

If a model is chosen from this list, any existing binding (see the Binding property) is cleared.

The “Binding” property

Binding specifies the name of an existing binding, which is to be used by the form control. It is represented by a combo box, containing the list of all bindings in the document.

Entering the name of an existent binding associates this binding with the form control. Clearing the property revokes any binding from the control.

Entering a name for which no binding exists in the document automatically creates a new binding, and associates it with the form control. The name of the new binding (which is also visible in the Data Navigator) is be “Binding <number>” for the smallest <number> which yields a non-existent name.

String list

Item	English	German	Comments
Label	XML data model	XML-Datenmodell	
Label	Binding	Bindung	since spec version: 1.0.1

Illustration 1 The properties XML data model and Binding

Binding properties

Besides the DOM node to bind a control model to, which is reflected in the property Binding expression, an XML binding offers the properties Required, Relevant, Read only, Constraint, Calculation. All those properties form XPath expressions, thus the user can enter them in a usual text input field. Additionally, all properties are fit with a browse button: upon pressing it, the "Add Condition" dialog, used to build XPath expressions, and known from part 1 of this specification, is opened to allow the user to easily create a valid expression.

No validity checks will be made on the expressions, since even currently invalid expressions may become valid in the future, if the underlying XML data model is changed.

String list

Item	English	German	Comments
Label	Binding expression	Bindungsausdruck	
Label	Required	Erforderlich	
Label	Relevant	Relevant	
Label	Read-only	Schreibgeschützt	
Label	Constraint	Bedingung	
Label	Calculation	Berechnung	

Illustration 2 Additional binding properties on the Data tab page of the property browser

Validation settings

Additional properties are offered on the "Data" tab page for defining the data type which the control should be validated against. The property browser will not only allow to chose this data type, but also to do a simple type administration, in particular it's possible to create new data types, to delete user-defined ones, and to modify the settings of existing data types.

This approach is chosen to prevent a full-blown data type administration, which would only confuse the user. Instead, with the approach described here, users will recognize data type settings as aspects of the control they are currently inspecting.

The Data type property

For the Data type property, the user can chose, via a drop down box, from a list of all types available for the selected model (see XML data model).

Illustration 3 The Data type property as seen in the property browser

String list

Item	English	German	Comments
Label	Data type	Datentyp	

Every XML model has built-in data types. In the following table, those types are listed together with their corresponding XSD data types.

String	string: http://www.w3.org/TR/xmlschema-2/#string
URL	anyURI: http://www.w3.org/TR/xmlschema-2/#anyURI
Boolean	boolean: http://www.w3.org/TR/xmlschema-2/#boolean
Decimal	decimal: http://www.w3.org/TR/xmlschema-2/#decimal
Float	float: http://www.w3.org/TR/xmlschema-2/#float
Double	double: http://www.w3.org/TR/xmlschema-2/#double
Date	date: http://www.w3.org/TR/xmlschema-2/#date
Time	time: http://www.w3.org/TR/xmlschema-2/#time
Date/time	dateTime: http://www.w3.org/TR/xmlschema-2/#dateTime
Year	gYear: http://www.w3.org/TR/xmlschema-2/#gYear
Year/Month	gYearMonth: http://www.w3.org/TR/xmlschema-2/#gYearMonth
Month	gMonth: http://www.w3.org/TR/xmlschema-2/#gMonth
Month/Day	gMonthDay: http://www.w3.org/TR/xmlschema-2/#gMonthDay
Day	gDay: http://www.w3.org/TR/xmlschema-2/#gDay

String list

Item	English	German	Comments
List box entry	String	Text (String)	
List box entry	Hyperlink	Hyperlink	
List box entry	True/False (Boolean)	Wahr/Falsch (Boolean)	
List box entry	Decimal	Dezimal	
List box entry	Floating point	Fließkomma	
List box entry	Double	Fließkomma (doppelt genau)	
List box entry	Date	Datum	
List box entry	Time	Zeit	
List box entry	Date and time	Datum und Zeit	
List box entry	Year	Jahr	
List box entry	Month and year	Monat und Jahr	
List box entry	Month	Monat	
List box entry	Month and day	Monat und Tag	
List box entry	Day	Tag	

Administrating data types

A push button besides the drop down list (see Illustration 3) allows deleting the currently selected type from the XML data model. This button is disabled if the currently selected type is a built-in type. The deleting of a type must be confirmed by the user, as shown in Illustration 4. In this confirmation, "No" is focused by default.

Illustration 4confirmation dialog when deleting a data type

String list

Item	English	German	Comments
Fixed Text	Do you want to delete the data type '#type#' from the model?\nPlease note that this will affect all controls which are bound to this data type.	Möchtenen Sie den Datentype '#type#' aus dem Modell löschen?\nBeachten Sie, dass alle Kontrollfelder betroffen sein werden, die mit diesem Datentyp verbunden sind.	

When the user confirms the deletion, then the data type is removed from the model, and the built-in datat type of the same class is selected. This means if the user deletes a string type (say "String 8", a string with length 8), then the built-in string type will be selected afterwards.

An additional push button allows creating a new type. It is enabled if an only if an existing type is selected in the Data type list. If it is pressed, the "New type" dialog (see Illustration 5) is opened. It's edit field is filled with the name of the currently selected type, appended by the smallest number (starting with 1) which makes the combined name unique. If the user confirms this dialog with OK (while the OK button is enabled if and only if the entered name is not empty, and there does not already exist a type with this name), then a new type will be created at the XML data model, which initially inherits all facets (see chapter "Data type facets") from the data type which was selected when the "New type" button was pressed. Then, this type is selected in the Data type drop down.

Illustration 5 Dialog for entering the name of a to-be-created data type String list

Item	English	German	Comments
Dialog title	New data type	Neuer Datentyp	
Label	Type a name for the new data type:	Bitte geben Sie einen Namen für den neuen Datentyp an:	

Restricting available data types

Not all data types can be bound to all types of controls. Illustration 6 shows the compatibility matrix for form control types and basic XSD data types:

Illustration 6compatibility matrix: Form control types and XSD data types

In the Data type drop down list box, only those types will be shown, which are derived (directly or indirectly) from a basic type which is supported for the control being currently inspected.

Data type facets

The XSD data type system (see the References section) consists of a set of basic types, and the possibility to derive types from existing types. Every type has a set of so-called constraining facets, which represent certain aspects of it. For instance, types which are derived from the basic String type support a constraining facet Length.

In the property browser, all constraining facets of the currently selected type will be shown below the Data type property, so the use can freely edit them. To indicate that they depend on another property, they're shown with a small indent (see Illustration 7). Upon selecting another Data type, the set of facets is exchanged in the UI, to match the newly selected type.

Illustration 7 Data type facets for a string type

Common facets

The following facet properties are available for all data types:

Whitespaces	Specifies how whitespaces are to be handled when a string of this data type is being processed. Possible values are “Preserve”, “Replace”, and “Collapse”. In their semantics, they exactly follow their XSD pedants at http://www.w3.org/TR/xmlschema-2/#rf-whiteSpace.
Pattern	Specifies a regular expression pattern. Strings validated against the data type must conform to this pattern to be considered valid. The regular expressions for this property do not follow the regular expression syntax as used in OpenOffice.org in other instances (e.g. in the search dialog). Instead, it follows the Regular Expression syntax as defined for XSD data types.

String list

Item	English	German	Comments
Fixed Text	Whitespaces	Leerzeichen	note: "Leerzeichen" does probably not really match what is meant here
List Box Entry	Preserve	Erhalten	
List Box Entry	Replace	Ersetzen	
List Box Entry	Collapse	Zusammenfassen	
Fixed Text	Pattern	Muster	If possible, this should remind the reader to the term "regular pattern" (where this originates from)

String facets

For all string data types, the following facets are available:

Length	Specifies the number of characters for a string.
Length (at least)	Specifies the minimum number of characters for a string.
Length (at most)	Specifies the maximum number of characters for a string.

String list

Item	English	German	Comments
Fixed Text	Length	Länge	
List Box Entry	Length (at least)	Länge (mindestens)	
List Box Entry	Length (at most)	Länge (höchstens)	

note for linguistic review: See Illustration 7 for an illustration where these strings appear.

Boolean facets

Boolean data types do not have any facets except the common facets.

Decimal facets

For all decimal data types, the following facets are available:

Digits (total)	specifies the total number of digits, which values conforming to this data type can have at most. See http://www.w3.org/TR/xmlschema-2/#rf-totalDigits for details.
Digits (fraction)	specifies the total number of fractional digits, which values conforming to this data type can have at most. See http://www.w3.org/TR/xmlschema-2/#rf-fractionDigits for details.

String list

Item	English	German	Comments
Fixed Text	Digits (total)	Ziffern (gesamt)	total number of digits
Fixed Text	Digits (fraction)	Nachkommastellen	“Decimal accuracy” i.e. number of digits after the decimal point

Common facets

Some facets are available for more than one data type:

Maximum (incl.)	Specifies an inclusive upper bound for values.
Maximum (excl.)	Specifies an exclusive upper bound for values.
Minimum (incl.)	Specifies an inclusive lower bound for values.
Minimum (excl.)	Specifies an exclusive lower bound for values.

String list

Item	English	German	Comments
Fixed Text	Max. (inclusive)	Maximum (einschl.)	Maximum
Fixed Text	Max. (exclusive)	Maximum (ausschl.)	Maximum
Fixed Text	Min. (inclusive)	Minimum (einschl.)	Minimum
Fixed Text	Min. (exclusive)	Minimum (ausschl.)	Minimum

Those facets are available for the types Decimal, Float, Double, Date, Date/Time, Year, Month, Day. Depending on the concrete type, different types of values can be entered in the property browser. In addition, for some types, value limits are enforced by the property browser.

Types	value type to enter	minimum value	maximum value.
Decimal, Float, Double	numeric values	n/a	n/a
Date	date	n/a	n/a
Time	time	n/a	n/a
Date Time	date time	n/a	n/a
Year	integer values	0	32767
Month	integer values	1	12
Day	integer values	1	31

Providing list Entries for list and combo boxes

OpenOffice.org knows two form control types which display a list of strings: list boxes and combo boxes. For both, a new property List source is introduced. This property, placed immediately above the Model property, allows the user to select one binding in the document (out of all bindings of all models), which is responsible for supplying the list entries for the control.

This does make sense for bindings which refer to more than one node in the XML DOM tree, for instance a binding for /employees/*/name.

List source will be presented to the user as list box, containing the names of all bindings of all models in the document. For every binding, the name to be displayed is comprised as "[model-name] binding-name" . The name of the binding is composed in the very same way as it is on the Bindings Tab of the Data Navigator (see part 1 of this specification).

Chosing one binding will immediately update the list entries in the control with the entries supplied by the binding.

The connection between the chosen binding and the form control is dynamic in the sense that if the nodes referred by the binding change in any way, this is immediately reflected in the entry list of the form control.

String list

Item	English	German	Comments
Fixed Text	List entry source	Listeneinträge aus	

Hiding Properties

Validation-related Properties

There is a certain overlapping between properties which have always been available for form controls, and newly introduced properties, which in real represent an aspect of a binding, or a facet of a data type.

For instance, text fields always supported a Max. Text Length property. Now, when you bind a text field to a node in the XML tree, and validate it against a string type, then there is a new property Length (at most) which has a similar semantics. The difference between those two properties is that Max. Text Length is a constraint which is enforced at the time the user enters text into the control: She cannot enter more characters than are specified in this property. For Length (at most), the constraint is not enforced at input time, but only when the form is validated. Nevertheless, both properties have a similar semantics.

To not confuse the user, in XForm documents, properties which should enforce validity at input time (such as Max. Text Length for text fields, or Value min. for numerical fields) will be removed from the property browser, if there is an equivalent property available as a result of the XML binding.

The following table lists all those properties which will not be available to the user, when she is inspecting a form control in an XForm document:

Property being removed	Superseding property resulting from an XSD data type validation
Decimal Accuracy	Digits (fraction)
Value min. / Value max. / Time min. / Time max. / Date min. / Date max.	Maximum (inclusive) / Maximum (exclusive) / Minimum (inclusive) / Maximum (exclusive)
Max. Text Length	Length (at most)

Database-binding related properties

For XForm documents, it's not possible to bind controls to database content. Thus, any properties which are related to such bindings (such as the Data Field property of a single control) will not be available to the user in XForm documents.

In particular, these are (for controls): Data Field, Empty string is NULL, Filter proposal, Bound field, Type of list content, List content.

For logical forms, the complete Data tab page of the property browser will be hidden.

New properties

Reference value (unchecked)

Check box controls already support a property called Reference value, which allows the user to specify a string which is used for data exchange when the control is checked. That is, if a check box is bound to, say, a spreadsheet cell or, in our case, a DOM node, then the control will propagate its reference value to the cell respectively the DOM node when it is checked by the user. If it is unchecked, it usually propagates an empty string.

This behavior is now extended, so that a check box control has a second property, which specifies the string to exchange when the box is not checked. This new property is called Reference value (unchecked), and in the property browser, it's placed immediately below the Reference value property.

String list

Item	English	German	Comments
Fixed Text	Reference value (off)	Referenzwert (aus)	
	Reference value (on)	Referenzwert (ein)	was “Reference value”

Submission

Using buttons for data submission

For XML form documents, one document can contain multiple models, and one model can contain multiple submissions.

To support creating and operating such forms, command buttons in OpenOffice.org will be extended with a possibility to execute, when pressed, a certain submission. A new property is introduced, called Submission, which allows the user to chose one submission out of all submissions present in the document.

In the property browser, this property is presented with a listbox. Since programmatic submission names must not be unique across models, the display name of a submission will be assembled following the scheme "[model-name] submission-name". That is, for a submission named "foo", which belongs to a model "bar", the display name, as shown for the Submission property, will be [bar] foo.

Submission will be placed immediately below Button type, and be enabled if and only if Button Type is set to Submit form.

String list

Item	English	German	Comments
Fixed Text	Submission	Submission	FS: this should be consistent with the naming in the Data Navigator

An additional particularity of XForm documents is that here, push buttons can only be used to submit the form, but not to reset it, or to open other documents (still, the user can of course bind scripts to such buttons, which are executed when the button is pressed).

To support this in the property browser, the properties URL and Target frame will be hidden for push buttons. Additionally, the choices Reset form and Open document/web page will be removed from the list of allowed Button types.

Illustration 8 Submission property with exemplary submission names

Illustration 8 shows the Submission property as it appears in the property browser, together with some exemplary submissions.

Miscellaneous

In the course of the XForms implementation, the following changes are made to the overall form design functionality:

for XML form documents, it's not possible to display properties of logical forms in the property browser. That is, the “Form...” entry will be removed from the context menu of form controls, the “Form Properties” icon will be removed from the “Form Design” Toolbar, and when a form is selected in the Form Navigator, the “Properties” entry in its context menu will not be available.
The reason is that logical forms only bear properties which are completely irrelevant for XML form documents, but would have the potential to confuse the user in this context (such as the submission target, which is a HTML submission target, and not related to XForms submissions at all).

Future Tasks

n/a

References

Part one of this specification
XForms Graphical User Interface (GUI) Specification - Part 1

XSD data types
http://www.w3.org/TR/xmlschema-2/

XSD data types, regular expression syntax
http://www.w3.org/TR/xmlschema-2/#regexs

The Data Navigator
http://specs.openoffice.org/appwide/xforms/GUI_spec_part1.sxw#6.3.Data Navigator|outline

Each XForms model has an own set of data types

Note that this is consistent with the naming of submissions, see chapter "Submission"

Note that in technically, it's not a property of the control, but a facet of the XSD data type which the control is validated against

<Required - Specification Title>

Page 5

http://specs.openoffice.org/appwide/xforms/GUI_spec_part2.sxw

XForms Graphical User Interface (GUI) Specification - Part 2

Frank Schönheit

2004-07-22T12:31:01