Letter Wizard

OpenOffice.org 2.0 / Q

Task ID(s)

<Required - Tasklist comma separated.>

Category	Specification Affects

Extras

Abstract

This is the specification for the re-implementation of the letter wizard for OpenOffice.org 2.0 / StarOffice 'Q'. It describes the reasons for a new implementation as well as all the features of the letter wizard.

i-Team

Specification Owner	Tom Verbeek	tom.verbeek@sun.com
Marketing (MA)		
User Experience (UX)	Christian Jansen Matthias Müller-Prove	christian.jansen@sun.com mprove@sun.com
Development(DEV)	Tom Verbeek	tom.verbeek@sun.com
Quality Assurance (QA)	Stefan Baltzer	stefan.baltzer@sun.com
Documentation (DOC)	Uwe Fischer	uwe.fischer@sun.com

Specification Reviews

Version	Reviewer	Comment
Reviewed by UX 10.09.03	Matthias Müller-Prove	review ok, if you address my issues MMP-20 to MMP-26
<Date>	Christian Jansen	
UI String Review 15.03.04	Elizabeth Matthis	Strg review and changes/comments
Reviewed by QA <Date>		
Reviewed by DOC <Date>		

Document History

Version	Author	Comment
	Tom Verbeek	initial draft
15.07.03	Matthias Müller-Prove	some comments and notes.
07/20/03	Tom Verbeek	Clearing of the issues by MMP
11.08.03	Matthias Müller-Prove	comments based on version 25-Jul-03; inline and in 7Notes
18.08.03	Tom Verbeek	Clearing of the issues by MMP
10.09.03	Matthias Müller-Prove	just MMP-20 to MMP-26 and sime minor comments inline.
Final 10/20/03	Tom Verbeek	Incl. Strings
Update 3/10/2004	Tom Verbeek	additional strings
Update 3/10/2004	Elizabeth Matthis	added competitive analysis (text with screen shots) and some strgs and comments

Contents

Glossary	1

References	1

1	Motivation	1

2	Goals	1

2.1	How does this feature meet the requirements	1

2.2	How does this feature improve the program architecture	2

3	Dependencies	2

3.1	Technical Dependencies / Requirements	2

4	Detailed Specification	3

4.1	Solution in OpenOffice.org 1.1, StarOffice 6 and former versions	3

4.2	New Design for OpenOffice.org 2 / Q	8

4.2.1	Technical Details	8

4.2.2	User Interface and Strings	8

4.2.3	Application Flow	16

4.3	Error Conditions	17

5	Future Tasks	18

6	Legal Issues	18

7	Notes	18

Glossary

Term	Description
<Term 1>	

References

Concept for Wizards: Wizards_NewConcept.sxw

Motivation

StarOffice's 6.0 Letter Wizard is basically unchanged since StarOffice 3.0. The old implementation has been created in C++.

A number of reasons make it obvious to re-implement this wizard:

Look & Feel outdated. The wizard looks pretty old-fashioned and does not fit to the rest of the GUI design.

Localization impossible. The old implementation was done in a time when only the European and North American Market was served. Since StarOffice now supports basically all scripts and languages it is necessary the Letter Wizard can cope with certain cultural specialties.

Letter output unsatisfactory. Although the old implementation was based on the use of Writer templates (which could be customized), many features of a modern business letter could not be achieved with the old model. This lead to less and less satisfactory results as the rest of the DTP world increased the quality of their products. Also the current norms are not honored.

Usability unsatisfactory. Some areas of the old implementation are hard to understand/hard to use because the GUI design is somewhat exotic.

Goals

All flaws of the previous version (listed above) need to be improved.

The new implementation should have less steps than the old one. It is desired to implement it with 6-8 steps.

A very small preview of the generated letter is not useful, therefore the new implementation needs to display the generated letter in its real size on the underlying Writer document.

The generated letter must conform to current standards and norms.

The wizard needs to be able to complete the letter on every step (when the user clicks on the Finish-button) using default values for the unedited steps.

It should be possible to create a letter in a locale that is different from the StarOffice language. For instance a German user should be able to create a standards-conform British business letter with his German StarOffice.

The letter wizard will generate templates for the use of subsequentially creating letter documents out of this. The difference between templates and documents holding the data needs to be communicated by the new implementation.

How does this feature meet the requirements

The new Letter Wizard will be implemented in Java. This makes it possible to use synergies from other Java wizard projects such as the database wizards. The concept of showing the document which is being created in the background has proven to be much more effective than a small preview.

The experience and the available data of the Extras team will back the development process, ensuring that the implementation will actually meet the requirements.

How does this feature improve the program architecture

Since a wizard is a high-level feature not supporting other features there it really does not affect the program architecture.

Dependencies

Technical Dependencies / Requirements

The Java/UNO bridge must provide sufficient effectivity and speed to allow the programming of the API with a non-native programming language such as Java.

Since the developer will only be able to communicate with the StarOffice functionality via the API, the API needs to be complete for all areas affected by the letter creation process.

The implementation of the new Letter Wizard creates dependencies to the Extras team, which will be providing the templates being used as a base for a Letter generated by the wizard.

Competitive Analysis

Although the StarOffice Letter Wizard is based on the concept of templates and the Microsoft Word Letter Wizard is not, the MS Word Letter Wirzard is a similar tool. The following screen shots show how the MS Letter Wizard looks.

Figure 1 Microsoft Word 2003 Letter Wizard

Figure 2

Figure 3

Detailed Specification

Solution in OpenOffice.org 1.1, StarOffice 6 and former versions

In order to understand the problems of the Letter Wizard the 9 steps are shown below:

Illustration 1Selection of the general type and design of the letter. This triggers the load of a certain template

Illustration 2Selection of Logo/Header properties

Illustration 3Sender address properties

Illustration 4Addressee properties and database management (mail merge)

Illustration 5Selection of letter elements

Illustration 6Footer properties

Illustration 7Properties of the following pages of the letter

Illustration 8Document properties and save options

Illustration 9Printing options

New Design for OpenOffice.org 2 / Q

Technical Details

The new Wizard will be implemented in Java, using the StarOffice API and UNO dialogs. This way it will look like the C++ Core dialogs.

The implementation will make heavy use of reusable code. For instance the roadmap control will be implemented within a class in a helper library so it can be used by all wizards.

The roadmap is active. [c.f. Wizards_NewConcept.sxw]

User Interface and Strings

Illustration 10 Step Type/Style

Item	English	German	Comments
	Letter Wizard	Brief-Assistent	Step 1
Radio	~Business letter	Geschäftsbrief	Step 1
Radio	~Formal personal letter	Förmlicher Privatbrief	Step 1
Radio	~Personal letter	Privater Brief	Step 1
Checkbox	~Use letterhead paper with pre-printed elements	Geschäftliches Briefpapier verwenden	Step 1
Label	Page design	Seitendesign	Step 1
Info	This wizard helps you to create a letter template. You can then use the template as the basis for writing letters as often as desired.	Dieser Assistent hilft Ihnen, eine Dokumentvorlage für Briefe zu erstellen. Sie können die Dokumentvorlage als Basis verwenden, um dann so häufig wie erwünscht, Briefe zu erstellen.	Step 1
Header	Please choose the type of letter and page design	Bitte wählen Sie den Typ und das Seitendesign des Briefs	Step 1
Roadmap item	Page design	Seitendesign	Step 1
Roadmap item	Letterhead layout	Briefpapier-Layout	Step 2
Roadmap item	Printed items	Gedruckte Elemente	Step 3
Roadmap item	Recipient and sender	Empfänger und Absender	Step 4
Roadmap item	Footer	Fußzeile	Step 5
Roadmap item	Name and Location	Name und Speicherort	Step 6
new menu item under Tools	Letters and Mailings	Briefe und Sendungen	

Please note that the list box titled with 'Style' contains names of Styles of templates. The names of these styles are being drawn out of the titles of installed templates and are not being translated via the resources.

Illustration 11 Step: Business paper

Item	English	German	Comments
Checkbox	~Logo	Logo	Step 2
Checkbox	Return ~address	Absenderadresse	Step 2
Checkbox	~Include footer	Fußzeile einfügen	Step 2
Checkbox	~Return address in envelope window	Absenderadresse im Kuvertfenster	Step 2
Label	~Height:	Höhe:	Step 2
Label	~Width:	Breite:	Step 2
Label	S~pacing to left margin:	Abstand zum linken Rand:	Step 2
Label	Spacing ~to top margin:	Abstand zum oberen Rand:	Step 2
Label	H~eight:	Höhe:	Step 2
Label	Wi~dth:	Breite:	Step 2
Label	Spacing t~o left margin:	Abstand zum linken Rand:	Step 2
Label	Spacing to right ~margin:	Abstand zum rechten Rand:	Step 2
Label	Hei~ght:	Höhe:	Step 2
Header	Specify items already on your letterhead paper	Bitte legen Sie fest, welche Elemente bereits auf Ihrem Briefpapier sind	Step 2

Illustration 12 Step: Elements

Item	English	German	Comments
	~Logo	Logo	Step 3
Checkbox	~Return address in envelope window	Absenderadresse im Kuvertfenster	Step 3
Checkbox			EM->TV: this is not a common thing in English letters so it should not be in this main selection, but rather only in the country template.
Checkbox	S~ubject line	Betreffzeile	Step 3
Checkbox	Salu~tation	Briefanrede	Step 3
	Dear Ladies and Gentlemen	Sehr geehrte Damen und Herren	
	Dear Sir or Madam	Meine lieben Damen und Herren	
	Hello	Hallo	
Checkbox	Fold ~marks	Falzmarken	Step 3
Checkbox	~Complimentary close	Grußformel	Step 3
	Sincerely	Gruß	
	Best Regards	Mit freundlichen Grüßen	
	Cheers	Tschüß	
Checkbox	~Footer	Fußzeile	Step 3
Label	Use a typical letter format for this country:	Typisches Briefformat für dieses Land verwenden:	Step 3
Header	Select the items to be printed	Wählen Sie die Elemente, die gedruckt werden sollen	Step 3

The norm listbox contains entries like 'American' 'German' or 'French'. This defines that the letter will be formatted in accordance to the country specific values.

The salutation listbox contains a list of salutations. This list can be edited later.

The greeting listbox contains a list of greetings. This list can be edited later.

Illustration 13 Step: Sender/Receiver

Item	English	German	Comments
Radio	~Use user data for return address	Für Versendeadresse Benutzerdaten verwenden	Step 4
Radio	~New sender address:	Neue Absenderadresse	Step 4
Radio	Use placeholders for ~recipient's address	Für Empfängeradresse Platzhalter verwenden	Step 4
Radio	Use address database for ~mail merge	Die Adressdatenbank für Serienbrief verwenden	Step 4
Label	Sender's address	Absenderadresse	Step 4
Label	Name:	Name:	Step 4
Label	Street:	Straße:	Step 4
Label	Postcode/State/City:	PLZ/Stadt	Step 4
Label	Recipient's address	Empfängeradresse:	Step 4
Header	Specify the sender and recipient information	Legen Sie Absender- und Empfängerdaten fest	Step 4

Illustration 14 Step: Footer

Item	English	German	Comments
Checkbox	Include ~only on second and following pages	Nur auf der zweiten und folgenden Seiten einfügen	Step 5
Checkbox	~Include page number	Seitenzahl einfügen	Step 5
Label	Footer	Fußzeile	Step 5
Header	Fill in the information you would like in the footer	Füllen Sie die Infos ein, die in der Fußzeile zu sehen sein sollen	Step 5

Illustration 15 Step: Final Settings

Item	English	German	Comments
Label	Business Letter Template	Geschäftsbrief-Dokumentvorlage	Step 6
Radio	Create a ~letter from this template	Einen Brief aus dieser Dokumentvorlage erstellen	Step 6
Radio	Make ~manual changes to this letter template	Manuell Veränderungen an der Dokumentvorlage vornehmen	Step 6
Info	This wizard creates a letter template which enables you to create multiple letters with the same layout and settings.	Dieser Assistent erstellt eine Dokumentvorlage, die Sie vielfach verwenden können, um Briefe mit demselben Aussehen zu erstellen.	Step 6
Info	To create another new letter out of the template just navigate to the template location and double-click it.	Um einen weiteren Brief mit dieser Dokumentvorlage zu erstellen, gehen Sie zur Dokumentvorlage und doppelklicken darauf.	Step 6
Label	Template name:	Name der Dokumentvorlage:	Step 6
Label	Location and file name:	Speicherort und Dateiname:	Step 6
Label	How do you want to proceed?	Wie möchten Sie fortfahren?	Step 6
Header	Please specify last settings	Bitte legen Sie letzte Einstellungen fest	Step 6
Label	Formal Letter Template	Förmlicher Brief-Dokumentvorlage	Step 6
Label	Personal Letter Template	Privater Brief-Dokumentvorlage	Step 6

Application Flow

The letter wizard will generate templates for the use of subsequentially creating letter documents out of this. The difference between templates and documents holding the data will be communicated by the new implementation.

The user will start the letter wizard via an entry in the wizards menu. ##c.f. MMP-21# Then the wizard dialog will appear. Its a modal dialog which means that the current StarOffice/OpenOffice.org window cannot be accessed before closing or finishing the wizard. It will be possible though to switch to other StarOffice/OpenOffice.org.

Right at the start of the wizard a new document window opens underneath the wizard, and a complete letter template will be loaded. ##c.f. MMP-26# This letter document will correspond to the current (default) settings of the wizard and will allow for instant previewing of the result. It is not a preview in the common sense but rather the actual document which the user is about to create. The document is scaled to fit the application window to make it possible to see it completely. It will not be possible to scroll, zoom into, or edit the letter document, because the wizard dialogue is modal. The title of the letter document will correspond to the template name that can be specified on the last dialog page.

The user can immediately jump to the Step Final Settings to create a letter template because all the relevant options are defaulted. It will even be possible to press Finish at every time. The wizard will then check if the save path has already be specified. If this is not the case, a save dialog will appear the let the user define where to save the template.

Everything will be “live”, meaning that a click on a control in the dialogue will have an instant effect on the underlying document, which will show the resulting letter template.

It will be possible to create a letter in a locale that is different from the StarOffice/OpenOffice.org language. For instance a German user should be able to create a standards-conform British business letter with his German StarOffice/OpenOffice.org. The setting for this can be made on the Elements step (Illustration 12).

On the first step the user has to decide whether he wants to create a business letter, a private official letter, or a private letter. This choice changes the course of the following steps. The roadmap is immediately updated when the user changes the letter type. Here you see the three branches that are available:

step \ letter type	business letter	private official letter	private letter
Type/Style	x	x	x
Business paper	optional	-	-
Elements	x	x	x
Sender/Receiver	x	x	-
Footer	optional	optional	-
Final Settings	x	x	x

Some steps are optional . This means they depend on settings made in prior steps Furthermore will the substeps Elements and Sender/Receiver differ from another - dependent on the chosen letter type. These are the differences compared to the business letter:

step	private official letter	private letter
Elements	Remove Company Logo Change Company Address into Own Address	Remove Company Logo, Company Address in Receiver Field, Letter Signs, Subject Line and Footer.
Sender/Receiver	Change Company Name to Your Name	This step does not exist for the private letter.

On the Step Elements the user can choose to add or remove certain parts of the letter template. When a norm is relevant only choices honoring this norm will be available. Elements that have been chosen as pre-printed on the Business Paper Stepp (Ill. 11) are not available on this step. The removing of elements have the consequence that the underlying document will be immediately changed. Also, for every removed element the upcoming references to it will be grayed out (possible for the elments Address repetition in receiver field and Footer).

It is always possible to step back and forth or to switch to a different letter type – always with the live preview on the underlying document. If the user cancels the wizard, the dialog and the underlying document is being closed.

On the last dialog page the user can decide whether to immediately use the template to create a letter or to edit the template. In every case the template will be saved.

The template will receive the document title that has been edited in the last step plus a short default description: “template created via Letter Wizard on June 12th 2005”.

<String Lists>

<Required - Dialogs providing strings which have to be translated, have to be accompanied by a table containing the strings used in the image (English or German or both) Strings have to include mnemonics and the item for which the string is used. Mnemonics have to be visualized by a ~ - symbol in front of the letter which has to be displayed mnemonic.>

String list

see User interface.

Tab Order

<Required. It makes sense to describe or visualize the tabbing order. The description of the tab order has to contain which control has the initial focus.>

Key Board Shortcuts

<Required - Key Board shortcuts used in dialogs have to be listed in a table with a small description.>

Error Conditions

<Required - List all error conditions, and the action the system takes about them. If an alert box comes up, which kind is it? Include exact text of messages, or say what points need to be covered. Error Messages need a string list>

Future Tasks

This wizard will depend heavily on templates. StarOffice Q will include a number of templates but it will be possible to increase the number later on. There will be no need to change the code for additional templates. Templates can be created by slighty higher skilled users, too.

Legal Issues

<Recommended - If there are any legal issues to deal with the should be described here. Legal issues could be for example we have to redistribute third party technology. This section can also contain links the Legal Review Tool.If the Specification will be published on OpenOffice.org this section has to be removed.>

Notes

MMP-18 Issue: please contract Young for CJK business letter guidelines. TV: Will do when the templates for CJK languages will be created

MMP-20 Issue/medium: Please consult Stella for a roadmap background image. TV: I requested this. She will draw the image in a timely manner.

EM->TV: The wizard should be accessed via Tools – Letters and Mailings – Letter Wizard, to meet our marketing requirement.

MMP-23 Issue/major: please specify all default values for the wizard. In my understanding a bunch of settings is taken from the samples (business/elegant, etc.) while some others are generic to the wizard. Please make clear which settings are fed from which source, and at least specify the defaults values for the generic settings.

MMP-24 Issue/medium: I like to see some of the types&styles that are planned. Either as an appendix to this spec or by reference.

MMP-26 Question/major: What are the default positions of document window and wizard? Is it possible to move and resize the document window? (It should be.) Is the wizard always on top of the document window? (It should be but this might be a technical problem on Gnome) What if the user closes the document window? (Treat it as [Cancel Wizard])

<Required – This paragraphs gives the audience idea of what to aspect from this document. It should be described shortly what problem will be solved.>

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...

Recommended - Please list of technical terms or specialized field of knowledge here.

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.

<Required - What is the reason for pursuing this project?>

<Required - The goals section must be short but also provide a clear statement of the goals, to achieve with this feature, project or task. A clear statement in this section gives the Development, Quality Assurance and Documentation guidance.>

<Recommended - Describe how this feature will meet expected requirements>

<Recommended - Descripe how this feature will improve the program architecture.>

<Recommended - Are there any requirements or dependencies for this feature? Does the implementation of this feature create any requirements/dependencies to other program parts?>

<Required - First of all the concept section should give the audience an overview of how the new feature will work. When this is done this section has to cover the necessary things to finish this feature. This is the crucial part of the specification. If images are used in the concept, it is very important that these images provide a caption. The caption should be short and has to describe shortly the image. UI Mockups has to provide a caption too, if possible the mockups shouldn't be scaled and our standard user interface font, Andale Sans UI has to be used for strings on dialogs.>

<Required - Dialogs providing strings which have to be translated, have to be accompanied by a table containing the strings used in the image (English or German or both) Strings have to include mnemonics and the item for which the string is used. Mnemonics have to be visualized by a ~ - symbol in front of the letter which has to be displayed mnemonic.>

<Required. It makes sense to describe or visualize the tabbing order. The description of the tab order has to contain which control has the initial focus.>

<Required - Key Board shortcuts used in dialogs have to be listed in a table with a small description.>

<Required - List all error conditions, and the action the system takes about them. If an alert box comes up, which kind is it? Include exact text of messages, or say what points need to be covered. Error Messages need a string list>

<Recommended - If there are features which couldn't be implemented but have to be implemented in the future. State these in here with a description why the feature couldn't be implemented right now.>

<Recommended - If there are any legal issues to deal with the should be described here. Legal issues could be for example we have to redistribute third party technology. This section can also contain links the Legal Review Tool.If the Specification will be published on OpenOffice.org this section has to be removed.>

<Recommended - Questions will arise during the writing of the specification. State these in here.>

Specification Letter Wizard StarOffice 'Q'

Page 2

<file://///Staroffice-doc/Projects/Projects/StarOffice/SO_Q/Marketing/FSD/Extras/LetterWizardSpec.sxw>

Specification Letter Wizard

Tom Verbeek

2003-06-12T15:57:08

Elizabeth Matthis