Concept for Wizards

OpenOffice.org 2.0 / Q

Task ID(s)

110234, 110235, 110234

Category	Specification Affects

All wizards used in OpenOffice.org

Abstract

This document gives precise guidelines to be followed for the creation of StarOffice/OpenOffice.org's wizards. The more wizards are to be developed the more important becomes the recognition and consistency of certain repeating elements throughout the wizards. Basically this specification brings together the Sun specification in JLF(Advanced Topics) Chapter 7 Wizards and the different way of Microsoft's wizards.

i-Team Members

	Name	E-mail Address
Specification Owner	Berend Cornelius	Berend.Cornelius@sun.com
User Experience	Matthias Müller-Prove	mprove@Sun.COM,
Development	Berend Cornelius	Berend.Cornelius@sun.com,
Quality Assurance	Marc Schwanz	Marc.schwanz@sun.com,
Documentation	Uwe Fischer	Uwe.Fischer@Sun.COM

Approved for Implementation

	Approved by	Date
User Experience	<Name>	<Date>
Development		
Quality Assurance		
Documentation		
String Review	Elizabeth Matthis	19.03.04 Approved the 6 strings in the string list.

Document Change History

Rev. Level	Change	Initials	Date
1.0 draft	Initial draft	BC	25.06.03
	first round of comments	MMP	06/30/03
	Changes due to today's meeting added.	BC	02.07.03
	Changes due to today's meeting added	BC	02.07.03
	2nd round of comments on version 14-Jul-2003	MMP	07/14/03
	Comments worked in; Reference to Sun directions formulated	BC	23.07.03
	3rd round of comments on version 7/23/03 - rename wizards to wizards - new notes MMP-6 to MMP-10	MMP	07/23/03
	Prior Comments of MMP worked in	BC	24.07.03
	4th round of comments. Find them at ##MMP inline. Please also work on the open issues. I also added priorities to MMP-2, 3, 6, 10. My other issues have been addressed.	MMP	09/09/03
	Comments for Roadmap lables and Right pane headings added	EM	02/11/04
	Added some Comments and deleted some redlinings	BC	02/13/04
	Added User Interface description for the saving settings feature	IH	02/16/04
	review, Assuming you will address MMP-10 and MMP-11 this spec is approved by User Experience.	MMP	03/16/04
	Final changes	BC	03/17/04
	Added reasons for writing style to sections 4.3 and 4.5.2	EM	03/19/04
	Exchanged screenshots	BC	03/19/04
	add spaces to Next/Back buttons (see string list, page 13)	MMP	01/10/05

Contents

Glossary	1

References	1

1	Motivation	2

2	Goals	2

2.1	How does this feature meet the requirements	2

2.2	How does this feature improve the program architecture	2

3	Dependencies	2

4	Detailed Specification	2

4.1	Changes compared to the existing AutoPilots in OpenOffice.org 1.1 (Geordi)	2

4.2	Measurements	3

4.3	Left Pane: Roadmap	3

4.3.1	Active Navigation	3

4.3.2	Alternative Paths	4

4.3.3	Image	4

4.4	Bottom Pane	4

4.5	Right Pane	5

4.5.1	Additional Instructions	5

4.5.2	User Input Headline	5

4.5.3	Design Allegations of the User Input Area	5

4.6	Title Bar	5

4.7	Overview Page	5

4.8	Confirmation Page	6

4.9	Requirements Page	6

4.10	Summary Page	6

4.11	Number of used Steps	6

4.12	Default Values	6

4.13	Fixed Starting Parameters	7

4.14	Previews	7

4.15	Emphasized Labels	7

4.16	Messageboxes	7

4.17	Saving Session Settings	7

4.18	Example	8

4.19	Error Conditions	12

5	Future Tasks	13

6	Notes	13

6.1	Addressed Issues	13

Glossary

See also: Glossary of Sun

Term	Description
AutoPilot	same as Wizard; used by versions prior to OpenOffice.org 2
Wizard	A window that leads a user through a task one step at a time--requesting a series of responses from the user and then performing the task based on those responses
Subtopic, Subtask	A task that a wizard leads through is divided in several subtasks. Each subtask is dealt with in one or more steps of a wizard
Branch	A branch in the application flow of a wizard allows two or more different ways of perpetuation in dependence of the user input
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.
OpenOffice.org API	TheOpenOffice.org API is the comprehensive specification that describes the programmable features of OpenOffice.org.
MA (MAP)	The units which are used in this specification are Map AppFont (ma). It is the preferred unit when designing dialogs with the OpenOffice.org API. Map AppFont units are device and resolution independent. One Map AppFont unit is equal to one-eighth of the average character (Systemfont) height and a quart in width.
Title bar	The strip at the top of a window that contains its title and window controls
Registry Database	Registry Database Backend repository that contains information about UNO components registered with the service manager.
UNO	Universal Network Objects. Platform-independent component technology used as a basis for OpenOffice.org.

Motivation

The motivation is to improve the usability of the existing wizards and create guidelines when designing wizards in order to maintain consistency between them.

Goals

The use cases of wizards are described in JLF(Advanced Topics) Chapter 7 Wizards

Above to that specification we design wizards not only as a mean to perform a task step by step but also to create a professional result that meets commonly accepted standards. Some examples: A business letter designed by a letter wizard should meet the standards of a business letter also if the user himself does not know about the details of this standard. A web page designed by Web wizard should meet the demands of a professional web designer. Such wizards should work with conforming to standards or aesthetic templates as much as possible.

How does this feature meet the requirements

This specification describes the framework for all future wizards in OpenOffice.org.

How does this feature improve the program architecture

The program architecture will be improved by enhanced usability and consistency.

Dependencies

Technical Dependencies / Requirements

This concept can be realized with the OpenOffice.org API. There are no further requirements. Due to the various language bridges of the API it can be implemented in several languages.

Detailed Specification

Changes compared to the existing AutoPilots in OpenOffice.org 1.1

Compared to the existing wizards in OpenOffice.org 1.1 the following major items in the dialog have changed:

A roadmap to ease the navigation in the wizard has been added.

The button panel at the bottom of the dialog has been modified. A “Finish” button has been added. The order of the buttons have changed. The “Next” button and the “Back” button will be attached to one another.

Additionally to the “Next” button a “Finish” button is provided that is only enabled when it makes sense.

The title image of the AutoPilots of OOo1.x will be replaced by a regular window title .

The size of the dialog has changed. Due to the additional roadmap and the missing title image the dialog is wider and less high than before.

Measurements

The measurements for the dialog can be retrieved from Illustration 1. These allegations should be followed when possible but they are not compulsory.

Illustration 1Illustration 1 Measurements

The size of a wizard is fixed for all panels.

Left Pane: Roadmap

(see also: JLF(Advanced Topics) Chapter 7 Wizards)

The left pane is supposed to give the user an overview about what the wizard is supposed to fulfill. It consists of a roadmap and an image in the down right corner of the roadmap. The left pane as to be seen in Illustration 1 contains the roadmap that gives feedback about the navigation in the wizard and also supports active navigation. The roadmap on the left hand side displays all the steps to follow when navigating through the wizard.

The roadmap is initialized by passing over the text which constitutes the steps, which are vertically arranged in the roadmap. The vertical distance in Illustration 1 may be made smaller in case all the steps do not fit into the pane. The roadmap steps may be expanded over two lines, but they should be kept as short and precise as possible. Verb phrases are preferred, but noun phrases can be used instead. You should use the same grammatical type consistently for the whole roadmap.

Each roadmap step must correspond to the heading of the page it calls in the right pane. That means that the words of the roadmap step are used in the heading, if at all possible. Use sentence capitalization but do not put a period or other punctionation at the end even if it is sentence. The sentence capitalization makes it possible to have shorter as well as longer text for the roadmap, depending on the purpose of the wizard. If title capitalization were prescribed, then longer text, for example a sentence, would look ridiculous and not be as legible. For the same reason, we leave the period out: Only full sentences should end with sentence punctuation, but most of the time the roadmap will not contain sentences. Therefore by never using the period, we avoid inconsistency in the overall look for all wizards.

Active Navigation

The Roadmap supports active navigation between the subtasks of an wizard as long as it makes sense to do so. This means that a roadmap item can only directly navigated to if all prerequisites for this step are fulfilled. In this case the item is getting underlined following the behavior of a hyperlink when the mouse moves over the roadmap item. The mouse pointer is also changed to a hand as long as it resides over the roadmap item. Yet opposed to the “visited hyperlink behavior” the color of the roadmap item is not changed when the user has already gone through this step. If a step has become unnecessary because of the user input the respective roadmap item is disabled. The depiction of the current step is emphasized by setting the background of the respective control to the currently set selection color of the operating system. The fontcolor of the roadmap items is Sun Blue (RGB:89 79 191).

Each specification of wizards has to clearly state if the roadmap is passive or active in the sense described above.

Alternative Paths

It might occur that the exact roadmap of the wizard is not clear from the beginning because it contains one or several branches where the input of the user impacts the roadmap. If it is unclear how the roadmap is moving on after a branch because the respective controls do not contain values the following step after the branch is visualized with “...”. The steps afterwards are skipped as long as the state of this branch is uncertain. In this respect the rules in Default Values have direct influence on the roadmap. Basically there are several ways to handle these branches.

The roadmap is immediately updated with every user input. Certain controls's values are evaluated and the according roadmap set appropriately. This should be the preferred way to implement OpenOffice.org wizards because it offers the best overview functionality.

The roadmap is updated before switching to another step of the wizard. The implementation of this mode is easier because updates of the roadmap are only assigned in certain points of the application flow. On the other hand the user does not get an overview about other possible options of the branches.

The headline of the roadmap is underlined and emphasized bold.

Image

The roadmap may contain a low contrast image which contains a metaphor that can easily be associated with the task of the wizard or the subtask of the according step. In this respect the image may be exchanged for each subtask of the wizard. The transparency of the image should be set to 30%. The measurements given in Illustration 1 for the image are merely benchmarks because certain images may appear larger or smaller as they actually are.

Bottom Pane

(see also: JLF(Advanced Topics) Chapter 7 Wizards)

The bottom pane is a compromise between the JLF specifications and the layout of the wizards used in other products. In this respect the “Back” and “Next” buttons are closer attached to one another. Navigation instructions will generally not be provided. The “Next” button should only be enabled when all necessary input configurations have been assigned. On the last step, when the “Finish” button is enabled the “Next” button must be disabled. The “Back” button is enabled on the first step.

The same applies for the “Finish” button should be enabled as soon as possible. This can be achieved by useful default values. On the other hand it is also permitted to leave the “Finish” button disabled as long as very indispensable settings have not yet been made. On activation of this button the result is created with all user input values and preset default values. However paths where the wizard's target is going to be stored to should not be defaulted. Instead a Store dialog could pop up prompting the user to specify a target path. In the same way a wizard could provide an input box to demand indispensable data subsequently. For example such an input box could prompt for the name of a datasource before its final creation. The wizard's dialog should not be disposed before not all necessary data have been assigned.

Right Pane

(see also: JLF(Advanced Topics) Chapter 7 Wizards)

The right pane contains a heading, the user input area and, optionally, an area for additional instructions.

Additional Instructions

In opposition to the definition in the JLF specification additional instruction are also used as an additional description to explain the user the whole subtask of a wizard's page. In this case the additional instruction may also appear above the user input area. Additional instructions should be marked with an icon as in Illustration 7.

User Input Heading

The heading of the page in the right pane must correspond to the roadmap entry that calls that page. The heading should be in the imperative (not a question; cf pg 87 of Joanna Slawik's thesis). The imperative form introduces the information dealt with on the active dialog page by directing the user to do what is to be done on that page. For example “Enter name, address and telephone number” or “Select asset types”.

Use sentence capitalization but do not put a period or other punctuation at the end of the sentence, since this is a heading. The sentence capitalization makes it possible to have shorter as well as longer text at the top of a dialog or wizard page. If title capitalization were prescribed, then longer text, for example a sentence, would look ridiculous and not be as legible. For the same reason, we leave the period out: Only full sentences should end with sentence punctuation, but sometime headings are not full sentences. Therefore by never using the period, we avoid inconsistency in the overall look.

A subtitle with main instruction as described in JLF Specification is not normally used, but is not forbidden. The header has to be vertically aligned to the header of the roadmap and is emphasized according to Emphasized Labels.

Design Allegations of the User Input Area

The positions and sizes of the used controls in the user input area is to be found in the

Dialog Style Guide

The following allegations should be considered when creating the User interface. Some of them are contradictionary to each other and the “prioritiy order” depends on the very specific usecase.

Wizards do not always have to deliver an absolutely perfect result that suits the very own needs of really all users. Sometimes compromises have to be made between the usability and the ability of a wizard. Wizards generally address the advanced users as well as the novices. Therefor the User interface should always be kept simple.

Consistency to other elements in the Office application. As said before this is only an allegation but consistency is naturally always an aspect to observe.

Microsoft interoperability. Microsoft users should immediately feel “at home” when they use the office application. This idea is also valid for the wizards in OpenOffice.org.

As a wizard always performs a task in a sequential way the use of elements like tabpages should not be used in a wizard.

Design the user input area as simple and as convenient as possible. Avoid “teasing” the user with queries about detail information of things he will not be able to answer immediately like details about commonly used standards. A better way is to provide these information directly through the wizard by offering standardized and “well designed” templates. The user should enjoy using wizards!

Title Bar

(see also: http://java.sun.com/products/jlf/at/book/Wizards7.html)

The title of the title bar represents the name of the wizard. Use title capitalization style. It remains the same over all pages of the wizard.

Overview Page

(see also: http://java.sun.com/products/jlf/at/book/Wizards5.html)

An Overview page can be useful in complex wizards but it has to be considered that it adds a dialog page to an wizard which makes the task even longer as it already is. It should preferrably be used when the novice user might not immediately understand

what the wizard is about and

what the result of the wizard will be or

which side effects the wizard may have

The allegations in Number of used Steps must also be considered.

Confirmation Page

(see also: http://java.sun.com/products/jlf/at/book/Wizards5.html)

The use of confirmation pages is optional. Basically they should be used after a large amount of user input. On one hand the user may benefit from a summary of the information they have provided by examining these information before completing the task (finishing the wizard). Conversely, the steps may be simple and a summary page will only add an unnecessary step. Also in wizards that work on underlying documents where input information of the user is immediately assigned to a summary page might not be useful because the input information has already been applied to the document. Product teams should use their own discretion as to whether a summary step is appropriate. A general obliging rule when to make use of overview pages is considered as not useful.

Requirements Page

(see also:JLF(Advanced Topics) Chapter 7 Wizards)

Requirement pages are generally not provided. If a wizard cannot be started because some prerequisites are missing the respective menu item should be disabled if possible. If this is not possible it is sufficient to have a messagebox pop up on start up pointing to the missing prerequisite of the wizard. An alert messagebox in combination with an enabled menu item should also be preferred if the missing prerequisite can be precisely targeted and the user be given a useful hint on how to solve the occurred problem. For example a prerequisite for a database wizard is the registration of at least one datasource in the Office application . As it is hardly feasible to link this logic to the menu item of the wizard a “Stop” messagebox on the start up should additionally be provided (Illustration 8). The message ought to give a helping hint about how to solve the problem.

Summary Page

(see also: JLF(Advanced Topics) Chapter 7 Wizards)

The rules when to make use of confirmation pages may also be applied for the use of summmary pages (see Confirmation Page).

Number of used Steps

Basically the number of used steps should not be limited because there are always use cases where the number of applied steps naturally exceeds this limit. Various use cases simply demand very specific subdivisions in subtasks. Nevertheless the critical number is 8 pages. Nevertheless a wizard designer should consider merging different steps and skipping probable overview, confirmation or summary pages if the total number of pages exceeds 10.

Default Values

Default Values for controls should be set under the following circumstances:

There is a good reason for the suggestion that a certain value is the preferred value of the user.

A default value makes the use of a control clearer to the user.

Textboxes containing names may be defaulted when the default name points to the designed content of the wizard. If such a name already exists a suffix containing a number may be appended following the pattern “DefaultName_2”. In a loop it must be checked if a name with this number – suffix exists already and if yes the suffix number must be appended.

Radio controls should always have a default value set. In this case the control defining the option that is most probably selected by the user should be defaulted.

Otherwise the control should remain empty. A consequence might be that the “Next” button should remain disabled.

Fixed Starting Parameters

Sometimes wizard are started with certain parameters like a datasource name and a datasource command. In these cases the wizard works on a given object and it has to be made sure that the user does not change the parameters of the passed over object. Therefor the controls that are defaulted to this object are to be set to readonly.

Previews

Generally previews should be realized on living objects ->mostly underlying documents where user input is immediately assigned, so that the user gets immediate feedback. Previews in dialogs similar to the MS Access wizards have the disadvantage that they only give the user a very rough idea about how the result will look like. Therefor we should not necessarily stick to the general demanded MS interoperability in this special topic.

Emphasized Labels

Labels that shall be distinguished shall be bold. However bold labels like the headline in the right pane cause problems in Asian languages and under Solaris. Because of the extreme detailed character shapes of the Asian fonts the artificial bold is not applicable. Under Solaris there is also a problem because we do not support bold characters in the system font. For these use cases the emphasis of such labels have to be realized by making the label two points bigger.

Message Boxes

Messageboxes have as a Title the name of the Office application and the respective version (“%PRODUCTNAME %PRODUCTVERSION”, cf. Illustration 7).

“Stop” or “Error” messageboxes should provide a hint how to solve an occurred malfunction (if necessary and possible). The messages must be consistent to other similar messageboxes that pop up in other situations in the office application.

Saving Session Settings

Saving session settings is an optional wizard feature of OpenOffice.org and means that a wizard may be started with certain default states assigned to in a prior session. For example the assigned path for a template created by a wizard could be set as the default path in a later session. Or an assigned style could be reused as the default style in a later session.

Basically there are two different ways to deal with a prior session settings:

The latest sesstion settings are loaded automatically. This means that certain settings (e.g. Targetpaths, Styles...) from the last wizard session are set as default in the current session. These settings only make sense when there is certain evidence that the user will apply these settings again. There is no fix rule on how “certain evidence” is measured”. This must be estimated in the particular specification of each wizard.

The user chooses at the start up of a wizard which saved session he wants to load by choosing from various settings offered in a listbox. Before completing the wizard he is asked if he wants to add a saved session (= the assigned settings of the current session) to the existing saved sessions.

The Session settings must be embedded into the following scheme:

/org.openoffice.Office.<Application>

+-- Wizard

+-- <WizardName_n>

| +-- <SavedSessions> = set of <SavedSessions_Settings>

| +-- <SavedSession 1>

| | ....

| +-- <SavedSession 2>

| ....

| | ....

+-- <WizardName_n+1>

+...

with “/org.openoffice.Office.<Application>” representing one of the following paths in the registry:

"org.openoffice.Office.Writer/Wizard/"

"org.openoffice.Office.WriterWeb/Wizard"

"org.openoffice.Office.Calc/Wizard"

"org.openoffice.Office.Impress/Wizard"

"org.openoffice.Office.DataAccess/Wizard"

"org.openoffice.Office.Common/Wizard"

“WizardName_n” is the english resource for the specific wizard.

Some other aspects may also be put into consideration:

To prevent an unlimited accumulation of saved sessions it might be advisable to limit the list of sessions. If the limit is exceeded the oldest Session settings are dropped and replaced by the current ones. The “limit number” should become the standard once applied for the first time.

The general handling of prior wizard sessions may be specified in each particular wizard.

The user interface should generally be adapted to all existing solutions if applicable. In the following screenshots there is an UI example of the loading page of the wizard settings. This example is taken from the planned WebWizard. The load option should appear on the first page of the wizard. This gives the user the possibility to use a saved setting right when he starts the wizard.

The save option of the wizard setting should be on the last step of the wizard. On the last page of the wizard the user has done all his selections and he can decide if he wants to save his settings for further use. The following screenshot contains the last page of the planned WebWizard.

As the case arises it should also be decided whether all settings should be saved or only some of them. Which setting need to be saved depends on the wizard itself and should be described in the specification of each wizard.

Example

The following mockups describe an exemplary wizard that follows this specification.

Illustration 2 Example wizard Step 1

Illustration 3 Example wizard - Step 2

Illustration 4 Example wizard Step 3

Illustration 5 Example wizard Step 4

Illustration 6 Example wizard Step 5

Illustration 7Stop Messagebox

String list

Item	English	German	Comments
Button	~Help	~Hilfe	
Button	< ~Back	< ~Zurück	
Button	~Next >	~Weiter >	
Button	~Finish	~Fertig stellen	
Button	Cancel	Abbrechen	
Label	Steps	Schritte	

Tab Order

The Tabindices of the bottom pane controls should always be the last ones on the dialog page because they are arranged at the bottom of the dialog. As the default tab order always incremennts from left to right and then from top to bottom the tab order will increment with an initial tab index as follows:

Control	Tabindex
Help Button	Tabindex
Back Button	Tabindex + 1
Next Button	Tabindex + 2
Finish Button	Tabindex + 3
Cancel Button	Tabindex + 4

The labels in the roadmap aren't assigned a tabindex.

Key Board Shortcuts

No Key Board Short cuts are to be assigned.

Error Conditions

Basically all possible error Conditions should be defined in the specifications of respective wizards. Preferrably errors should be caught by means of API interaction handlers because they provide a consistent handling of error conditions.

Future Tasks

It should be discussed for a future version if it is useful to apply some kind of folding capabilities to the dialog to give the user a better view on the underlying document. Along with the thesis of Joanna Slawik mentioned above a concept could be worked out that allows the contemporary modification of an underlying object (like a document) along with the modification of the wizard.

Notes

References

JLF(Advanced Topics) Chapter 7 Wizards
User Interface Design Guidelines for Browser-Based Sun System Management Applications - Version 2.0, Chapter 13

Joanna Slawik's thesis

Dialog Style Guide

The source of software product implementation and change is the I-Team (Implementation Team). I-Teams are typically comprised of people who have skills in the areas of Product Marketing, Development Engineering, Technical Publications, and Test Engineering. I-Teams define the features or set of changes (based on input from SCs, customers, Engineering, or Marketing), plan the implementation project, perform the implementation and testing...

Concept for Wizards

9

http://specs.openoffice.org/installation/wizards/wizards_NewConcept.sxw

Berend Cornelius

2003-06-24T10:55:58

Matthias Müller-Prove

Matthias Müller-Prove