Form Wizard

OpenOffice.org 2.0 Database Access

Document - ID	Specification Owner	Last Change	Status
	Berend Cornelius	04/03/06	Approved
Conforms to	
Applies to	OpenOffice.org Base
Task ID(s)	20424
Category	Feature

Abstract

The Form Wizard conforms to the new wizard design that is introduced for OOo 2. Two new wizard panels extended the functionality to subforms. Above that the user interface of the current Form Wizard will be worked over.

i-Team Members

	Name	E-mail Address
User Experience	Matthias Müller Prove /MMP	Mprove@sun.com
Development	Berend Cornelius /BC	Berend.Cornelius@sun.com
Quality Assurance	Marc Neumann	Marc.Neumann@sun.com
Documentation	Uwe Fischer /UFI	Uwe.Fischer@sun.com

Approved for Implementation

	Approved by	Date
User Experience	Matthias Müller Prove /MMP	19.04.04
Development	Berend Cornelius /BC	19.04.04
Quality Assurance	Marc Neumann	19.04.04
Documentation	Uwe Fischer	19.04.04
String Review		

Document Change History

Rev. Level	Change	Initials	Date
1.0	initial draft	BC	26.08.03
1,1		BC	10.12.03
	review	MMP	12/18/03
	Changes according to recommendations of MMP worked in	BC	19.12.03
	review: changed title, new abstract, several comments inline (marked with ##MMP)	MMP	2/5/04
	UFI added some comments	UFI	2004-02-05
	Recommendations of MSC, UFI and MMP worked in	BC	2/11/04
	4th review, approval pending. Please resolve my issues MMP-1 to MMP-12	MMP	3/31/04
	Issues of MMP worked in	BC	4/1/04
	Default settings for the dialog pages added	BC	4/5/04
	Issue #i44812# worked in	BC	
	review of new error string	MMP	Apr 3, 2006

Contents

Glossary	1

1	Motivation	1

2	User Scenarios	1

3	Goals	2

4	Requirements and Dependencies	2

4.1	Requirements	2

4.2	Technical Dependencies	2

5	Competitive Analysis	2

5.1	MS Access 2002	2

6	Detailed Specification	4

6.1	Common Roadmap handling	5

6.2	Document as a Preview	5

6.3	Startup	5

6.4	Step 1: Field Selection	5

6.5	Step 3:Set up subform	7

6.6	Step 3: Select subform fields	8

6.7	Step 4: Adding Subform fields	9

6.8	Getting joined fields	10

6.9	Step 5:Arrange Controls	10

6.10	Step 6: Data handling	11

6.11	Step 7: Styles	12

6.12	Step 8: Finish	13

6.13	Error Conditions	14

7	Future Tasks	15

8	Notes	16

9	References	16

Glossary

Form	Forms allow access to the data of a table through a graphical user interface within a document. They can be used to enter or to edit existing data easily.
Subform	A subform is a form that is inserted in another form
Main form (master form, parent form)	If a subform is inserted in another form the primary form is called the main form or parent form or master form.
Related forms	Related forms offer the possibility to view related records on two forms at the same time.
Master field	data field of the main form responsible for the synchronization between parent and subform
Slave field	data field of the subform responsible for the synchronization between parent and subform
Style Template	A style template is a document that contains specific formatting styles. Such a template is used as the basis for creating other documents
Interaction Handler	If the execution of a command cannot proceed because of an error condition, an OpenOffice.org API InteractionHandler is used to resolve the problem in a consistent way.

Motivation

Users often want to create forms with a subform that is joined to the master form. The creation of subforms and their linkage to a master form is not very intuitive in OOo 1.1. Here the form wizard assists the user to create forms in documents, but it is not able to create subforms and it also does not allow the modification of existing forms. A new set of modules should give the user additional help to ease the daily work related with the creation of forms.

User Scenarios

A typical user scenario of a form is the need of the user for a user friendly frontend to enter or to view the data of his database. The creation of appealing user interfaces is very well possible yet a task that would overstrain the novice abilities and cause time tool. The solution is the wizard that keeps the user free from all this time consuming trouble.

Goals

This wizard should cover all major aspects to consider when creating related forms. It should be modernized by applying new style templates.

Requirements and Dependencies

Requirements

The wizard will ease the use of a program feature that's not easy to deal with right now. Adding subforms and linking them to a master form is still a thing that requires advanced skills and more.

Technical Dependencies

There are no specific requirements that can't be met by the OpenOffice.org API.

Competitive Analysis

MS Access 2002

MS Acceess 2002 does not offer the option to immediately review committed layout changes in the document. The form is created after finishing the wizard and the user is assisted by some bitmaps that convey a vague idea of how the final document will look like. The delivered styles haven't changed in the recent years, and according to our ideas in Step 7: Styles appear old fashioned.

One advantage of MS Access 2002 is the option to create pivot charts and pivot tables.

Creation of subforms is also possible.

The major competitor does not provide any navigation tool like the roadmap.

The following screenshots provide an overview of the Form Wizard of MS Access 2002:

Detailed Specification

The new form wizard will contain an extension that allows the user to create a subform and to add this to the main form. To do so the implementation for the subform has to be embedded in the existing form wizard. The following issues have to be dealt with: (i) The selection of fields for the main form must be duplicated for the subform. (ii) Before selecting the subform fields the relation to the parent has to be determined. The selection of the relation can either be based on a list of all available existing relations to the table of the main form or it can be selected manually be determining master and slave links of a chosen database table.

For the form wizard of OO.org 2.0 wizard there will be a way to choose between two modes for all forms to enter the data: One mode where all data is displayed and one mode to add data only without displaying existing data. In the “Display mode” the user will get the possibility to set allowance for modification, deletion and addition of data.

Basically the functionality of arranging the controls inside the form document is duplicated for the subform. Only the areas for the two forms in the document body have to be redefined in dependence of how many forms are to be integrated.

Last but not least the form wizard will be equipped with a page to set the title, save path and determine whether the user wants to further modify the form document manually or work with it straight away.

Common Roadmap handling

The interactive mode of the roadmap is set to “true”, meaning that the user is free to navigate over all available steps of the wizard. When skipping steps in this way their default settings are taken over (if not previously modified by the user. Conflicts may occur when the user steps back to the first step and removes a field that is already represented by a control in the underlying form document or that has even been selected as the primary key beforehand. Possible conflicts are resolved in the following way:

Removed field is already represented by a control in the underlying document: As soon as the index of the current page becomes greater than the index of the “Control Arrangement page” (which is '5') the controls in the form document will be rearranged.

Removed field have priority been chosen as a joined field between main form and subform: the joined field is “silently removed. If it was the only joined field the steps behind “Getting joined fields” will be disabled because a new joined field has to be determined beforehand. If it was the only subform field all steps behind step 2 “Setup subform will be disabled.

The adjustment of the navigation inside the dialog and the underlying document is described in Arrange Controls

Document as a Preview

As the creation of a user friendly form is especially a matter of layout which again is a matter of the personal preferences of the user , the Form Wizard immediately displays all committed layout relevant settings to the underlying form document. The assignment of these layout settings is described in the chapters. The advantage of this behavior is that the user can check out several settings without having to end the wizard and see if the result suits his needs. The assignment of the layout specific settings is described in the chapters Arrange Controls and Step 7: Styles.

Startup

The wizard always starts with the creation of a new writer document, that is going to be the container for the form before the respective wizard dialog appears.

Step 1: Field Selection

Field Selection

Item	English	German	Comments
Right Pane Header	Select the fields of your form	Wählen Sie die Felder Ihres Formulars	BC: Form or MainForm?
Label	~Tables or queries	~Tabellen oder Abfragen	
Label	~Available fields	~Vorhandene Felder	
Label	Fields in ~my form	Felder in meinem Fo~rmular	
	Binary fields are always listed and selectable from the left list.<BR> If possible, they are interpreted as images.	Binärfelder werden mit aufgeführt und können aus der linken Liste selektiert werden.<BR> Wenn möglich, werden Sie als Bilder interpretiert.	
Roadmap Item Label Field selection Feldauswahl Roadmap Item Label Set up a subform Subformular Roadmap Item Label Add subform fields Subformularfelder Roadmap Item Label Get joined fields Verknüpfte Felder Roadmap Item Label Arrange controls Anordnung der Kontrollfelder Roadmap Item Label Set data entry Dateneingabe Roadmap Item Label Apply styles Stile Roadmap Item Label Set name Formularname	

In the first dialog page (see illustration “FieldSelection”) the respective fields for the form document are selected by the user. The operating mode of the “Existing fields” and “Fields in my form” listboxes are described in the FieldSelection Specification. As soon as a table is selected the “Existing Fields” listbox is populated, and the fields can be added to the “Fields in my form” listbox.
The field listboxes on the right hand side will only be allowed to contain fields of a single table or query Therefore both fields listboxes will be emptied as soon as another table or query has been selected.
The roadmap is initially filled with all description of steps. As soon as the “Fields in my form listbox has been populated the roadmap's Interactive mode is switched on. When the “Fields in my form listbox is emptied the interactive mode is switched off.

On the Startup the dialog page is initialized with the first table being selected and the “Available Fields” listbox being populated accordingly – unless specific selection has been passed over on the start up of the wizard.

Step 3:Set up subform

Set up subform

The white square is a placeholder for the info image noted in the common wizards spec and will be inserted after the approval of the strings

Item	English	German	Comments
Right Pane Header	Decide if you want to set up a subform	Entscheiden Sie, ob Sie ein Subformular hinzufügen möchten	
Label	A subform is a form that is inserted in another form. <BR>Use subforms to show data from tables or queries with a one-to-many relationship.	Ein Subformular ist ein Formular, das in ein anderes Formular eingefügt wird. <BR> Subformulare sind besonders geeignet, um Daten von Tabellen oder Abfragen in eine one-to-many Beziehung zu setzen.	Please do not translate “<BR>” It indicates a new line.
Check Box Label	~Add Subform	Subformular ~hinzufügen	
Radio Button Label	~Subform based on existing relation	Sub~formular basiert auf bestehenden Beziehung	
Radio Button Label	Subform based on ~manual selection of fields	~Beziehungen werden manuell ausgewählt	
Label	~Which relation do you want to add?	~Welche Beziehung möchten Sie hinzufügen?	

The second page (Illustration “Set up subform”) will query whether the user wants to add a subform to his form. The default will be “Do not add a subform”. If yes he has the possibility to create the subform based on an existing relation offered in the listbox or on a new relation that's going to be determined two steps further. The listbox with its label is subsidiary to the radio button “Subform on relation” and toggle with its selection or deselection. On its selection the next RoadmapItem “Adding subform fields” gets enabled as soon as a relation has been added. Before this the roadmap's steps behind the current one are disabled and the Finish and Next button are disabled. When no relations exist in the database this option together with its subsidiary listbox is disabled.

When selecting/deselecting the option “Select relations manually” the roadmap items “Adding subform fields” and “Getting joined fields” are toggled immediately. Otherwise when the user choses to include a subformular the steps after the following step “Adding subform fields” will be disabled, because it is not possible to determine the arrangement of the formcontrols before the assignment which controls belong to which form has been made.

Step 3: Select subform fields

Select subform fields

Item	English	German	Comments
Right Pane Header	Select the fields of your subform	Wählen Sie die Felder Ihres Subformulars	
Label	~Tables or queries	~Tabellen oder Abfragen	
Label	~Available fields	~Verfügbare Felder	
Label	Fields in my ~subform	Felder ~meines Subformulars	

The selection of the subform fields (see Illustration “Select subform fields”) works in analogy to the selection of the parent's form fields. If the relation has been determined in the page beforehand prior to the page displayed in the “Tables or queries” listbox is readonly and the table associated with the chosen relation is selected. As soon as at least one subform field has been selected the following page “Getting joined fields“ will be enabled. The listboxes work in the same way as the listboxes in Step 1.

As it does not make sense. To take the same table as for the main form non table or query is taken as default unless the user has select an existing relation on the previous page. In this case the table of the first selected relation is the default.

Getting joined fields

Item	English	German	Comments
Right Pane Header	Select the joins between your forms	Wählen Sie die Verknüpfungen Ihrer Formulare	
Label	~First joined subform field	Erstes untergeordnetes Feld	
Label	~Second joined subform field	Zweites untergeordnetes Feld	
Label	~Third joined subform field	Drittes untergeordnetes Feld	
Label	~Fourth joined subform field	Viertes untergeordnetes Feld	
Label	F~irst joined main form field	Erstes übergeordnetes Feld	
Label	S~econd joined main form field	Zweites übergeordnetes Feld	
Label	T~hird joined main form field	Drittes übergeordnetes Feld	
Label	F~ourth joined main form field	Viertes übergeordnetes Feld	

Getting joined fields

When having choosing a relation manually two pages beforehand the user now has to determine the joined fields.

As it is possible to determine several links the masks functions in the same way the as the sorting criteria component in the query wizard's specification.

As long as no joined fields have been chosen the following steps remain disabled and the finish button and Nextbutton too.

Step 5:Arrange Controls

Control Arrangement

Item	English	German	Comments
Right Pane Header	Arrange the controls on your form	Ordnen Sie die Kontrollfelder auf dem Fomular an	
Label Header	Ali~gnment of the labels	Ausrich~tung der Beschriftungsfelder	
Radio Button Label	Align ~left	Ausrichtung ~links	
Radio Button Label	Align ~right	Ausrichtung ~rechts	
Label Header	Arrangement of the main form	Anordnung der Datenbankfelder des übergeordneten Formulars	
Label Header	Arrangement of the subform	Anordnung der Datenbankfelder des Subformulars	

The setting of the control arrangement (see Illustration “Control Arrangement”) is applied in analogy to the existing wizard

The arrangement scenarios are visualized as images in an imagelist.

When the user clicks on an image, a verbal description of the layout appears underneath the graphics gives additional information about the selected arrangement

However compared to the current version OOo1.1 one arrangement scenario is left out: “in blocks; labels left”, because it seems very rare that it will be made use of in daily practice. The “Label placement” radio buttons are only enabled if in the selected scenario the labels are placed next to the data control.

When clicking on a scenario button the form controls are rearranged after a determined algorithm “on the fly” on the underlying document.

If a subform does not exist the appropriate controls on this page are disabled.

Just like in the current Form Wizard the default setting will be the display “As Data Sheet”. The reason is that this arrangement builds up the fastest because only one grid control has to be configured. In this case the “Alignment control group at the top of the page is disabled.

As soon as the current step number becomes equal or greater than this step (which is step no 5) all selected database fields will be rearranged in the the default arrangement.

Step 6: Data handling

On the following page (Illustration Data handling) the user can choose the explicit edit mode. As said above there is a mode where data can be added only and existing data is not displayed and one mode where existing data is displayed. In this mode the user can set the exact purpose of his form: modification, deletion and addition of data. All functionality will be applied to both forms. When the forms are not to display all existing data the indented checkboxes are disabled.

Data Handling

Item	English	German	Comments
Right Pane Header	Select the data entry mode	Wählen sie die Art der Dateneingabe	
Radio Button Label	The form is to be ~used for entering new data only, existing data will not be displayed	Das Formular wird nur zur Eingaben neuer Daten verwendet, existierende Daten werden nicht dargestellt.	
Radio Button Label	T~he form is to display all data	Das Formular zeigt existierende Daten an.	
Check Box Label	Do not allow ~modification of existing data	Existierende Daten dürfen nicht verändert werden.	
Check Box Label	Do not allow ~deletion of existing data	Existierende Daten dürfen nicht gelöscht werden.	
Check Box Label	Do not allow ~addition of new data	Neue Daten dürfen nicht hinzugefügt werden.	

Step 7: Styles

In the current version (OO.org 1.1) of the form wizard the style page is included within the “arrange” page. But we will separate both topics and provide an extra “Styles” page to define backgrounds and font issues.

We will redesign the templates for the form wizard in the style of the Calc themes. But the basic concept of importing the styles from another template remains. The current controls to scale the background images will thus be removed as the background images are outdated from a designer's point of view. Above that the legibility of the text decreases with the use of background images.

Applied styles are immediately taken over in the underlying document. As soon as the templates are implemented it remains to be seen which will be the default.

Styles

Item	English	German	Comments
Right Pane Header	Apply the style of your form	Wählen Sie den Stil Ihres Formulars	
Listbox Header	~Page styles	Seitenvorlagen	
Header Label	Field bo~rder	Feldumrandung	
Radio Button Label	N~o border	Ohne Umrandung	
Radio Button Label	3~D look	3-D Look	
Radio Button Label	F~lat	Flach	

Step 8: Finish

In opposition to OOo1.1 the Form Wizard provides a “Final” page to assign last settlements such as a form title, store path, and what the user intends to do with the form next. The title of the form is preselected with a default name derived from the prefix “Form_” and the the selected table or query name If the composed name of the form already exists in the database it is made unique by applying an self incrementing autonumbering suffix.

Set title

Item	English	German	Comments
Right Pane Header	Set the name of the form	Setzen Sie den Namen des Formulars	
Label	Name of ~the form	Formularname	
Label	How do you want to proceed after creating the form?	Wie möchten Sie fortfahren?	
Radio Button Label	~Work with the form	Mit dem Formular arbeiten	
Radio Button Label	~Modify the form	Das Formular weiter verändern	

This is also used as the title. When the user modifies the form title for the first time it is made a replication to the pathname when this has not yet been modified by the user. The default name of the form is combined following the pattern: <FirstTableName of MainForm> + “_Form” + suffix. The suffix is a number that makes sure the name is unique inside the database. By default it remains “”.

For the control group “How do you want to go on” the default is set to “Work with the form”.

Finish the wizard

When clicking the finish button the current step will change to the last step and the according actions like the insertion of the formcontrols in the formdocument will take place accordingly. After that a form is added to the datasource. From then on the form will be available in the future base component. Forms are part of the new database file format.

Error Conditions

Style templates are not existing, Path is invalid: Stop messagebox: "The files required could not be found.<BR>Please start the %PRODUCTNAME Setup and choose 'Repair'."; wizard is terminated.

Style template's cannot be imported: Warning messagebox appears: “Styles cannot be imported from '%templatepath'

Database form cannot be created: an Error Message with Stop icon appears:"The form could not be created." Detailed exceptions are passed over to an interaction handler.

Unexpected error occurs: Error message with Stop icon: "An error occurred while running the wizard. The wizard will be terminated." wizard is terminated. These kind of errors should not occur but they can never be completely excluded. Therefor you have to be prepared for them.

The most probable errors will turn up when the design mode of the form is switched off which happens when the wizard has already been terminated and is therefor no longer involved.

Item	English	German	Comments
Error Message	An error occurred.<BR> The fom could not be executed	Es ist ein Fehler aufgetreten.<BR> Das Formular konnte nicht erstellt werden.	
Error Message	An error occurred while running the Wizard. The Wizard will be terminated.	Während der Ausführung des AutoPiloten ist ein Fehler aufgetreten. Der AutoPilot wird beendet.	
Error Message	"The files required could not be found.<BR>Please start the %PRODUCTNAME Setup and choose 'Repair'."	Die benötigten Dateien konnten nicht gefunden werden.<BR>Bitte starten Sie das %PRODUCTNAME Setup and wählen Sie “Reparieren”.	
Error Message	A form with the name '%FORMNAME' already exists.\nChoose another name.	Ein Formular mit dem Namen '%FORMNAME' existiert bereits.\nBitte wählen Sie einen neuen Namen.	This message is raised after the “finish” click if necessary. Afterwards the text control 'Name of the form' on the last dialog page becomes the active control.

Future Tasks

It should be discussed if we want to provide functionality to edit an existing form.

This could work as follows:

A form is opened and a toolbar icon is attached to the function bar. The code is attached at the document event “OpenDocument”. It has to be considered that the user than cannot attach no other functions at this event except he removes this code. Behind this icon lies the functionality to analyze the form and retrieve the relevant data such as the datasource name, the connection, the affected command and selected fields, the relationship between main form and subform. After all this information is retrieved the form wizard can be started by skipping the first pages and the arrangement page as the initial one. The user then has the possibility to rearrange the form and change the style afterwards.

Yet this handling can be problematic because the user could have modified the structure in such a way that it's no longer to compatible with the wizard e.g. By grouping controls. It has to be discussed how such scenarios should be dealt with like with an untimely termination of the wizard. When closing the document the toolbar icon must be removed too.

I suggest to have this feature conceptionally in mind but deal with it with a low priority.

Notes

References

JLF(Advanced Topics) Chapter 7 Wizards

New Wizard's Concept Specification

Query Wizard Specification.sxw

FieldSelection Component

User Interface Text Style Guides

Required - Give references to related documentation, such as engineering designs, technical specs, and other sources for related units. Also include links to documents that other sections in this spec need to refer to, such as user opinions usability test reports.

Extension of the Form Wizard

Page 5

http://dba.openoffice.org/specifications/Wizard_Form.sxw

Christian Jansen

2003-11-04T09:09:03

Berend Cornelius