Script Organizer Specification
OpenOffice.org 2.0

Document - ID	Specification Owner	Last Change	Status
	Duncan Foster	31. Mrz. 2005	Draft
Conforms to	
Applies to	Every Module of OpenOffice.org
Task ID(s)	i21148
Category	Feature

Abstract

The development of the Scripting Framework allows the user to develop macros in languages other than OpenOffice.org Basic. This document describes the changes to the Tools->Macros submenus and the dialogs it launches to allow the user manage their macros.

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

	Name	E-mail Address
User Experience	Bettina Haberer	Bettina.Haberer@Sun.COM,
Development	Duncan Foster	Duncan.Foster@Sun.COM,
Quality Assurance	Joerg Skottke	Joerg.Skottke@Sun.COM,
Documentation	Uwe Fischer	Uwe.Fischer@Sun.COM

Approved for Implementation

	Approved by	Date
User Experience	Bettina Haberer	16th April 2004
Development	Duncan Foster	16th April 2004
Quality Assurance	Joerg Skottke	16th April 2004
Documentation	Uwe Fischer	16th April 2004
String Review	Elizabeth Matthis	27 April 2004

Document Change History

Rev. Level	Change	Initials	Date
0,1	Initial draft for discussion	DF	26th January 2004
0,2	Revision post meeting of 2nd Feb.	DF	3rd February 2004
0,3	Revision post meeting of 19th Feb. Updated with input from Kay Ramme. Separate organizer dialogs for each language.	DF	24th February 2004
0,4	Revision post meeting of 26th Feb. Dialog Provider specification, error messages.	DF	27th February 2004
0,5	Updated after comments from James Cleere. Fixed consistency of terminology (Container/Library). Rewording. Reorganise the String Lists. Fixed position of dialog mockup.	DF	3rd March 2004
0,6	Updated post meeting of 5th & 11th Mar. Splitting of Macro Organizer tabpage into two (modules, dialogs). Removal of Properties button.	DF	12th March 2004
0,7	Added some UI changes and descriptions / remarks, reworked existing mockups	BH/DF	31th March 2004
0,8	Reworked some dialogs.	DF	15th April 2004
0,9	Clarification of BeanShell, move Dialogs Organizer into Organize submenu.	DF/BH/UF	16th April 2004
0.10	Updates from BH. Splitting of Basic merged view into %PRODUCTNAME Macros & My Macros.	DF/BH	10th June 2004
0,11	Updated Basic IDE related screenshots	TBE	20th July 2004
0,12	Two button label need change (New Module..., New Dialog...), because they got too long in brazilian-portuguese version. They got shortened to New... (as on the Library-tabpage too).	BH	28th January 2005
0,13	String review for changed button label done	EM	28th January 2005
0,14	3 german strings needed a change (Exchange 'c' in Macro with 'k')	BH	31st March 2005

Contents

1	Motivation	4

2	User Scenarios	4

3	Goals	4

4	Requirements and Dependencies	4

4.1	Requirements	4

4.2	Technical Dependencies	4

5	Competitive Analyses	5

6	Detailed Specification	6

6.1	Basic	6

6.2	Dialogs	9

6.3	Libraries	10

6.4	Other Languages - Common Organizer	11

6.5	Error Conditions	16

7	Future Tasks	18

8	Notes	18

9	References	18

Glossary

Term	Description
Scripting Framework	An extensible framework provided by OpenOffice.org for the execution of code written in different languages such as Basic, JavaScript, BeanShell and Python.
Basic module	An object which contains OpenOffice Basic macros.
Basic library	An object which contains OpenOffice Basic modules or dialogs.
Script Library	An object that directly or indirectly contains macros (examples include OpenOffice Basic libraries and modules, or the equivalent for other Scripting Framework languages).
Organizer	A dialog for the management of macros & dialogs. This allows the creation, deletion, and editing of such objects.
BeanShell	BeanShell is a small, open source, embeddable, Java source interpreter with object scripting language features, written in Java. It is used in the scripting framework to allow macros to be written in Java without having to precomile them. More details on the interpreter can be found at http://www.beanshell.org/

Motivation

The development of the Scripting Framework provides the user with the option of writing macros in languages other than OpenOffice Basic. The need to organize these macros, start up the appropriate IDE, create new macros, dialogs, or script libraries necessitates an examination of the Tools->Macros->Macros and Macro Organizer dialogs. These will require a redesign or the provision of new dialogs to accommodate the new scripting languages. Due to the limited resource available to the project and priority constraints a low cost/minimal effort solution is required.

User Scenarios

User A wishes to test a macro. He brings up a dialog that lists macros, selects a macro, and executes it. [Run]

User A realizes that the macro contains a minor error, but has the knowledge required to fix it. He brings up a dialog that lists macros, selects a macro, and opens it in the IDE appropriate to the language in which the script is written. [Edit]

User B decides to write a new macro. He has an existing Script library to which he can add his macro. He brings up a dialog which shows his script library, selects the script library. He is prompted for a name for his new macro, and the IDE appropriate to the language for his script library is opened. The IDE contains a template for his new macro. [Create(macro)]

As per scenario 3, however, in this case there is no suitable script library. User B, when presented with the existing script libraries, decides to create a new library. He is prompted for the library's name, and a new library is created, and shown along with the previously existent libraries. [Create(script library)]

User C decides that an existing macro is no longer of use to him. He brings up a dialog that lists macros, selects the macro, and deletes it. [Delete(script)]

User C decides that an existing script library, and all of the scripts it contains are no longer of use. He brings up a dialog that lists script libraries, selects the script library, and deletes it. [Delete(script library)]

Goals

The goals of this work are to

To provide the user with a useable, accessible and consistent UI in which to perform the management tasks associated with macro development.

Assess the options associated with providing new dialogs to support the organization of Scripting Framework macros.

Requirements and Dependencies

Requirements

The functionality in the existing Basic dialogs must be retained for Basic.

Users, at a minimum, must be able to create and delete macros and script libraries, for languages other than Basic.

Technical Dependencies

The testtool requires Help IDs on every control in every dialog.

<Are there any technical dependencies for this feature? Does the implementation of this feature create any technical dependencies to other program parts? Or very important any issues for automatedd GUI Testing?>

Competitive Analyses

MS Office has a dialog named Macro which is similar to the Macro dialog in OpenOffice.org 2.0. The MS dialog is used to enable running and organizing Visual Basic Macros. MS Office also has an Organizer, which is not very intuitive to use. The organization of macros from different scripting languages needs an easier handling. In OpenOffice.org 2.0 this will be done via the the Script Organizer, which is launched via the menu Tools / Macros / Organize / BeanShell or JavaScript and makes available simple IDEs for BeanShell or JavaScript.
MS Office works with docked windows instead of using only dialogs. The MS Office Script Editor shows all the elements on one view (e.g. Code, property browser, form functions) docked, which are also available in OpenOffice.org, but here are to find on different sides and floating windows and dialogs, which have to be opened. In future releases of OpenOffice.org (ie. post 2.0) it would be desirable to have an IDE framework which would keep the relevant content on one view and dockable.

Concerning the term Script in Script Editor: The Script Editor in MS Office does not enable editing scripts of different scripting languages, it supports only the visual Basic scripts.
MS Office Macros do not have the organizational level of libraries that is to be found in OpenOffice.org.

Detailed Specification

The proposed solution is to provide access to the various dialogs for Macro management via Tools submenu. This existing item Macros should be re-used as it is already familiar to OpenOffice.org Basic users & developers.

The first entry in the submenu is for recording Macros (in OpenOffice.org Basic only). The second entry in the submenu should bring up the Script Selector in a mode that allows the user to select and run a macro. The third menu entry, “Organize...” should bring up a submenu containing one entry for each language. As BeanShell and JavaScript will be part of OpenOffice.org, at least the three languages are listed default. The fourth entry is “Organize Dialogs...”, and brings up the Macro Organizer with the Dialog tabpage selected. Except for OpenOffice.org Basic the entries in the second submenu should bring up the appropriate organizer dialog (the Scripting Organizer for other languages. These are described further below). In case of OpenOffice.org Basic the Macro-dialog comes up with the full functionality for Basic Macros, including opening the Macro Organizer. The submenus are is shown in Figure 1.

OpenOffice.org Basic... Figure 1The new Tools->Macros submenus

String List

Item	English	German	Comments
Menu Entry	R~un macro...	Makro ausführen...	A dialog (named Macro Selector) comes up to run a selected macro / script
Menu Entry	~Organize Macros	Makros verwalten	
Menu Entry	~Organize Dialogs...	Dialoge verwalten...	
Menu Entry	%PRODUCTNAME ~Basic...	%PRODUCTNAME Basic...	Product name –DO NOT TRANSLATE! (http://docs.sun.com/db/doc/817-1826-10)
Menu Entry	Bean~Shell...	BeanShell...	Product name –DO NOT TRANSLATE!
Menu Entry	~JavaScript...	JavaScript...	Product name –DO NOT TRANSLATE!

Basic

For Basic, the existing Tools->Macros->Macros dialog will be retained in its current form, however the menu item will be renamed "OpenOffice.org Basic Macro". A mockup of this dialog is shown in Figure 2. this mocukup does not contain the new icons nor the splitting of the soffice node both described below.

Figure 2The renamed Macro dialog

String List

Item	English	German	Comments
Dialog Title	%PRODUCTNAME Basic Macros	%PRODUCTNAME Basic Makros	
List Entry Label	My Macros	Meine Makros	First toplevel node
List Entry Label	%PRODUCTNAME Macros	%PRODUCTNAME Makros	Second toplevel node

The Basic Macro Organizer, which will be renamed to OpenOffice.org Basic Macro Organizer, should be split into three tabpages from the existing two. The “Libraries” tabpage should remain unchanged. Creation of a Library should create both a Basic Library and a Dialog Library. The “Modules” tabpage should only display Basic Libraries and Modules. The “New Dialog...” button on the Modules tabpage will move to the Dialogs tabpage. A mockup of the tabpage is shown in Figure 3. The new tabpage should be labelled “Dialogs”. This tabpage should look & behave similarly to the “Modules” tabpage, but display Basic Libraries and Dialogs. A mockup of this tabpage is shown in Figure 4. When launched by the Tools->Macros->Organize->OpenOffice.org Basic entry, the “Modules” tabpage should be active.

String List

Item	English	German	Comments
Dialog Label	%PRODUCTNAME Basic Macro Organizer	%PRODUCTNAME Basic Makros verwalten	Do not translate “%PRODUCTNAME Basic” because it is a product name (for our dialect of the BASIC language); the German text was approved by UFI, so it is okay that it is a verb phrase as compared to a noun phrase in English.
Button Label	~New...	Neu...	was 'New Module...'

Organizer OpenOffice.org Basic Figure 3The modified Macro Organizer showing the Modules tabpage.

The OpenOffice.org Basic Macro and Macro organizer dialogs currently present a merged view of the macros found in user and share. For consistency with the dialogs for other macro languages it would be desirable to split this into separate views.

The new view will show the two toplevel nodes “My Macros” (containing the macros of the user) and “%productname Macros” (containing the macros, which belong to the OpenOffice.org installation).

This new treelist view is visible as an example in Figure 6 and 7 showing the two toplevel nodes, the hierarchie and the used icons. There is no longer an soffice-node and also no blue star as icon for a node in use. The nodes can be expanded and collapsed by plus and minus boxes.

Icons
The following icons are used within the OpenOffice.org Basic Macro and Macro organizer dialogs:

Harddisk for My Macros and %productname Macros instead of a blue star icon	
Modulfolder / basic script library (these icons are an optimized version of the older one)	
Modulfolder / basic script library (these icons are an optimized version of the older one. These white icons are only used in the OpenOffice.org Basic Macro-dialog and in the Basic Macro Organizer for showing the unloaded mode)	
Document icons instead of	
Renewed icons for dialogs	
Dialog Libraries	
Dialog Libraries (unloaded status)	

Dialog libraries contain only dialogs; but script libraries can contain both dialogs and macros.

Figure 4The modified Macro Organizer showing the new Dialogs tabpage. Organizer OpenOffice.org Basic Dialogs

The “Organize Dialogs...” entry should launch the Organizer OpenOffice.org Basic described in the previous section. However, when launched from Tools->Scripts/Macros->Organize Dialogs..., the Macro Organizer should be launched with the “Dialogs” tabpage active. The treelist toplevel node soffice will be split into “My Dialogs” and “%PRODUCTNAME Dialogs”.

String List

Item	English	German	Comments
Tabpage Label	Dialogs	Dialoge	
Button Label	~Edit	Bearbeiten	
Button Label	Close	Schließen	
Button Label	~New...	Neu...	was 'New Dialog...'
Button Label	~Delete	Löschen	
Text Label	D~ialog	Dialog	
List Entry Label	My Dialogs	Meine Dialoge	First toplevel node
List Entry Label	%PRODUCTNAME Dialogs	% PRODUCTNAME Dialoge	Second toplevel node

Libraries

Also for Libraries the toplevel node soffice needs to be adjusted. The two toplevel nodes are named with My Macros & Dialogs and %Productname Macros & Dialogs. As it is possible to locate user macros and installed macros in their places, “Location” is more clear then Application/Documents, which is difficult to associate (Figure 5).

Figure 5

Item	English	German	Comments
Text Label	~Location	Ort	Was Application/Document. As it is possible to locate user macros and installed macros in their places, “Location” is more clear then Application/Documents, which is difficult to associate.
Combobox and Listbox Entry Label	My Macros & Dialogs	Meine Makros & Dialoge	First toplevel node
Combobox and Listbox Entry Label	% PRODUCTNAME Macros & Dialogs	% PRODUCTNAME Makros & Dialoge	Second toplevel node

The Object Catalog dialog in the OpenOffice.org Basic IDE shows the same two toplevel nodes My Macros & Dialogs and % PRODUCTNAME Macros & Dialogs as shown in the following figure.

Item	English	German	Comments
Listbox Entry Label	My Macros & Dialogs	Meine Makros & Dialoge	
Listbox Entry Label	%PRODUCTNAME Macros & Dialogs	%PRODUCTNAME Makros & Dialoge	

Other Languages - Common Organizer

To simplify the task for developers wishing to add new languages to the Scripting Framework, a common dialog for script management is provided. There should be hooks in the Scripting Providers to allow the use of a language specific dialog if one is provided. This should be a modal dialog to prevent any concurrency issues which may arise as the Scripting Framework does not have a notification mechanism. The installation and removal of Scripting Framework languages is handled via the Package Manager and is beyond the scope of this document.

Rename... Delete + OpenOffice.org Macros My Macros BeanShell Samples HelloWorld.bsh Highlighter.bsh Macros BeanShell Macros Figure 6A mockup of the new BeanShell Macros dialog, showing the available BeanShell macros.

OpenOffice.org Macros My Macros JavaScript Samples HelloWorld.js Highlighter.js MyDoc.sxw Macros JavaScript Macros Figure 7A mockup of the new JavaScript Macros dialog showing the JavaScript macros.

String List

Item	English	German	Comments
Dialog Title	%MACROLANG Macros	%MACROLANG Makros	%MACROLANG will be replaced at runtime by Java Script or BeanShell or other macro language automatically
Fixed Text	Macros	Makros	
Button Label	~Run	Ausführen	
Button Label	Close	Schließen	
Button Label	~Create...	Erstellen...	
Button Label	~Edit	Bearbeiten	
Button label	R~ename...	Umbenennen...	
Button Label	~Delete	Löschen	
Button Label	~Help	Hilfe	

A mockup of the dialog is shown in Figure6 A treelistbox shows the scripts available in OpenOffice.org 2.0, each document and each registered UNO package. At the top level, the nodes correspond to the OpenOffice.org 2.0 Macros, the user's macros, macros stored in open documents and macros present in registered UNO packages. Under each of these nodes is a hierarchy of nodes in the idiom associated with the scripting language, ie. In general, Library->Script. Each node is available for selection. Only one node may be selected at any time. On opening the Script Organizer dialog, the focus is on the top level node, My Macros. The last made selection in the listbox will be remembered at the following opening of the dialog.

Run

This button is only active when a script is selected in the treelistbox. Clicking it will execute the script and close the ScriptOrganizer-dialog.

Close

This button closes the Script Organizer dialog.

Create...

The behavior of this button is very dependent on the selection made in the treelistbox. Table 1 describes the behaviour. The dialogs prompting for a new object name should be pre-filled with "Library#" and "Macro#" where # is replaced with the next available number. While the reuse of this button might be confusing for the user, the dialogs that are launched clearly explain what will happen, and no better solution has been proposed. Where the user tries to create a Library or Macro with the same name as an existing object, the user should be notified as is the case in the Macro Organizer. The enabling and behaviour of this button is dependent on the selection made in the treelistbox and is described below.

Help Figure 8The New Script dialog. Create Macro Macro Macro # String List

Dialog Label	Create Macro	Makro erstellen	
Text	Enter the name for the new macro.	Geben Sie den Namen für das neue Makro ein.	
Button Label	OK	OK	
Button Label	Cancel	Abbrechen	
Button Label	Help	Hilfe	

Help Figure 6The New Library dialog.

Library #

String List

Dialog title	Create Library	Bibliothek erstellen	
Text	Enter the name for the new library.	Geben Sie den Namen für die neue Bibliothek ein.	
Button Label	OK	OK	
Button Label	Cancel	Abbrechen	
Button Label	Help	Hilfe	

If the attempt to create a new Library or Macro fails, the user should be notified, see Figure 10.

Edit

If a script is selected in the TreeListBox, clicking the Edit button will open it in the appropriate IDE, and close the Script Organizer. Otherwise this button is disabled.

Rename

Clicking the Rename button opens a dialog which prompts for a new name for the selected library or script. In other cases the Rename...-button is disabled. The dialog will be prefilled with the current name. The cursor stays in front of the name. Rename via UI is easier than using the current slow click,which is not commonly known by users.

Rename Enter new name for selection Help Rename

Current name

String List

Dialog label	Rename	Umbenennen	
Text	Enter the new name for the selected object.	Geben Sie den neuen Namen für das ausgewählte Objekt ein.	
Button label	OK	OK	
Button label	Cancel	Abbrechen	
Button label	~Help	Hilfe	

Delete

The node (and any children) selected in the TreeListBox are deleted. This button should launch an ok/cancel dialog listing what will be deleted (Figure 9).

Confirm Delete Figure 9The Confirm Delete dialog.

String list

Dialog Label	Confirm Deletion	Löschen bestätigen	
Text	Do you want to delete the following object?	Möchten Sie das folgende Objekt löschen?	
Button label	OK	OK	
Button label	Cancel	Abbrechen	

Help

This button brings up the help content related to the Script Organizer dialog.

Behaviour of the Create Button

Node Selected in TreeListBox	Action
Top level node	The user is prompted for the name of a new script library, and on pressing OK, a new script library is created and highlighted. A mockup of the dialog prompting for the library name is shown in Figure .
Scripting Framework scripting library	The user is prompted for the name of a new script, and on pressing OK the appropriate IDE is opened displaying a template for the new script. A mockup of the dialog prompting for the script name is shown in Figure 8. BH: Is the name of the script immediately adopted into the listbox or first only adopted as name to the template in the IDE and after saving of the template then adopted to the listbobx?
Scripting Framework script	The button is disabled.

Table 1The behaviour of the Create button.

Tab Order

The TreeListBox should have initial focus with top level node My Macros highlighted. Tabbing should then work through the buttons from top to bottom before returning to the TreeListBox.

Error Conditions

The Basic Macro Organizer & Dialog Organizer (now renamed) should retain their existing behaviour and use the existing error dialogs. For this reason they will not be documented here.

The Close & Edit buttons should not fail.

Run

The user should be notified of any errors via the same mechanism as for any Scripting Framework runtime error.

Delete

This could fail due to a permissions or filesystem problem.The user should be notified via the dialog shown in Figure 10.

Figure 10The Delete Error dialog. Delete Error

String List

Dialog Label	Error Deleting Object	Fehler beim Löschen	
Text	The selected object could not be deleted. You do not have permission to delete this object.	Das ausgewälte Objekt konnte nicht gelöscht werden. Sie haben keine Berechtigung zum Löschen dieses Objektes.	NOTE: these sentences are two separate resource strings.
Button label	OK	OK	

Create

This could fail due to a permissions or filesystem problem or if there already exists an object of the same name as that being created. The user should be notified via the dialog similar to that shown in Figure 11 Other error messages are included in the strings list.

Figure 11The Create Error dialog. Create Error

String List

Dialog Label	Error Creating Object	Fehler beim Erstellen	
Text	The object could not be created.	Das Objekt konnte nicht erstellt werden.	
Text	An object with the same name already exists.	Ein Objekt mit dem selben Namen existiert bereits.	
Text	You do not have permission to create this object.	Sie haben keine Berechtigung zum Erstellen dieses Objektes.	
Button label	OK	OK	

Dialog Label	Error Renaming Object	Fehler beim Umbennen	
Text	The object could not be renamed.	Das Objekt konnte nicht umbenannt werden.	
Text	You do not have permission to rename this object.	Sie haben keine Berechtigung zum Umbenennen dieses Objektes.	
Button label	OK	OK	

Future Tasks

OpenOffice.org Basic currently presents a merged view of the macros, dialogs and libraries found in the nodes My Macros and %PRODUCTNAME Macros, My Dialogs and %PRODUCTNAME Dialogs, and My Macros & Dialogs and %PRODUCTNAME Macros & Dialogs. For consistency this should be split into separate lists as is the case with the other macro languages.

Notes

There is significant confusion between the terms “Macro” and “Script”. Are “Macros” only written in OpenOffice.org Basic? Or does the term include other languages? Similarly for “Scripts”?

Is the name BeanShell appropriate? Will users/developers know what this is? Would it be better to replace this with “Interpreted Java”? Or does this imply more compatibility with Java than may be the case with BeanShell? Would there be licensing issues with renaming it?

BH: The behaviour at using create... dependend on the selected knode needs to be pointed out extra in the help. I suggest to implement two buttons instead of the one create... button: one for creating libraries and one for scripts to enable easier creating (program toggles automatically enabling/disabling of buttons) from each knode. If there is reason against those two buttons within a dynamically actualizing command menu, please write down, thank you.
DF: Agreed that this should be well documented, even though the behaviour is relatively intuitive to me. The problem with, for example a “Create Script” button is that technically it is not always possible to determine where the script should be created. For example if the top node User was selected, the script could possibly create in any one of a number of libraries.

BH: Will it be possible to start the JavaScript and BeanShell IDE stand alone? And if so, is then the Script Organizer open?
DF: No, the IDEs can only be opened from the Organizer. Launching the IDE via the Edit button will close the Organizer.

References

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

Script Organizer Specification

Page

http://specs.openoffice.org/scripting_framework/ScriptOrganizerSpecification.sxw

Christian Jansen

2003-11-04T09:09:03

Bettina Haberer