Difference between revisions of "Macros in Database Documents"

From Apache OpenOffice Wiki
Jump to: navigation, search
(Tasks)
(Tasks)
Line 190: Line 190:
 
|-
 
|-
 
| style="background-color:#c0c0ff; text-align:center" | M1 || let the Basic script provider implementation accept an XScriptInvocationContext as creation context || style="background-color:#00FF00" | done
 
| style="background-color:#c0c0ff; text-align:center" | M1 || let the Basic script provider implementation accept an XScriptInvocationContext as creation context || style="background-color:#00FF00" | done
 +
|-
 +
| style="background-color:#c0c0ff; text-align:center" | M1 || let the Basic script provider translate its invocation context into a global variable || open
 
|-
 
|-
 
| style="background-color:#c0c0ff; text-align:center" | M1 || let the BeanShell/JavaScript script provider implementations accept an XScriptInvocationContext as creation context || open
 
| style="background-color:#c0c0ff; text-align:center" | M1 || let the BeanShell/JavaScript script provider implementations accept an XScriptInvocationContext as creation context || open

Revision as of 13:51, 17 December 2007

Specification Status
Author Frank Schönheit
Last Change 2007-11-28
Status (Help) Preliminary

Abstract

OpenOffice.org Base, unlike the other OpenOffice.org applications, is currently not able to embed macros and scripts into its documents. We will empower Base users to use macros and scripts (StarBasic, JavaScript, BeanShell, Python) in their database documents the very same way they can use them in all other application's documents.

Detailed Specification

Accessing Macros and Scripts

  • Macro and Script Organizers (Tools / Macros / Organize / *) will show opened database documents, and allow editing/creating macros/scripts therein.
  • The Basic IDE will treat macros in database documents the very same way as macros in other application's documents.
  • The Macro Selector (Tools / Macros / Run...) will show the current database documents, and allow to run them, when invoked for this document, or any of its descendant documents.
  • The UI customization dialog (Tools / Customize ...) will allow access to the current database document's macros and scripts, when invoked for this document, or any of its descendant documents.

Global Variables in Basic Macros

Current Situation

  • Macros located in documents can only be called from within the very same document. This might happen through document items bound to macros (command buttons, fields in Writer, shapes in Impress, and the like), or through macros customized to appear in the the document's, or the document classes, UI.
  • The only exception is the Basic IDE, which allows to run macros from arbitrary documents.
  • When running a macro located in a document, there is a global variable called ThisComponent, which refers to the document.
  • When running a macro located in the application's or user's basic libraries, then there's also a variable called ThisComponent, which refers to the active document.
  • Database documents do not participate in the "global" ThisComponent: When you, from within a database document, run a Basic macro located in the application's or user's Basic libraries, then ThisComponent will refer to the single document that was last active before the database document became active.

Changes with Macros in Database Documents

  • Database documents will participate in the ThisComponent game. That is, when you activate a database document, and execute a macro located in the application's or user's Basic libraries, ThisComponent will refer to the database document.

In general, the change described herein for the first time allows to, from within a document, execute macros which are not located in this very document, but in another one. Specifically, from within a form or report (which technically, and probably perceived by many users, are separate documents, though semantically only "sub documents" of the database document), you can execute macros located in the database document.

This implies we need to separate the two aspects of ThisComponent which so far are used equivalently: By now, ThisComponent refers to the document from which the macro was invoked, and to the document in which the macro was located.

We will do this separation by introducing another global variable, called TODO

TODO: We need to decide whether ThisComponent should be the "invoking document", or the "document where the script is located". Pro and con:


If ThisComponent is the "invoking document", then macros will differ in behavior, depending from where they're invoked: If called from within a form or report, ThisComponent will point to the form or report, if called from within the Basic IDE, ThisComponent will be empty (or point to the database document).

On the other hand, it will keep ThisComponent's semantic of "the document which currently, directly or indirectly, has the focus".


If ThisComponent always is the "embodying document", then it will be stable no matter where you call the script from. However, it will contradict the semantics which some users might associate with ThisComponent: Remember that when calling an application- or user-macro from within a document, then ThisComponent points to this very document, i.e. the "active document", not the "document which contains this macro" (as there is no such macro).

Of course the newly-introduced variable TODO will suffer from the above problem of being undefined in the Basic IDE, but this might be less of a problem, since nobody is yet used to, and thus has expectations for, TODO's behavior, simply since TODO does not exist in today's OOo versions.


Yet more, we could say ThisComponent is always the "active document or sub document", or, to avoid the term "sub document", the "document in the top-level frame which is currently active". If your database document has the focus while the macro is executed, ThisComponent points to the database document. If a form is active (or was last active before you switched to the Basic IDE), then ThisComponent points to the form.

This sounds a little bit like magic - hard to explain to users, and hard to maintain. However, it would probably be nearest to what users are used to in today's OOo.

TODO would then be the "embodying" document, i.e. the document where the macro is located, i.e. the database document.

Database Document Macros vs. Macros in Sub Documents

Up to now, macros can be embedded into sub documents of a database document, that is, into forms and reports (which technically are Text documents).

We will not allow this in the future anymore. The reason is that it is hard to find a consistent concept (in particular: create a consistent user experience) which allows both, macros in the embedding database document and macros in the embedded form/report document.

As a consequence, in any place where you can currently access macros in forms (which we'll use as placeholder for forms and reports from now on), you won't be able to do so anymore. Instead, you can access the database documents's macros.

This means:

  • Currently, when you have a form, and open the customization dialog, it will give you access to macros embedded in this form. In the future, you will have access to the database document's macros only.
  • Currently, you see all open form documents in the macro organizer and the macro selector. In the future, you will see open database documents only (and all other application's documents, of course).
  • Assigning macros to elements in a form document (in particular: to events of form controls, from the "Events" tab page of the property browser) will be possible with macros from the database document only, not with macros from the form document.

Migration

Database documents created with version prior to OpenOffice.org 3.0 might contain forms or reports with embedded macros or scripts. Since this constellation is prohibited as soon as macros in database documents are implemented, a migration path is necessary.

The goal is to transform documents so that all the macros and scripts are in the database document, not in its sub documents anymore. Unfortunately, this cannot be done automatically.

For once, it is difficult to (in a generic way) merge all macros from embedded documents into the database document. For instance, if two forms both contain a Basic library named "Standard", with a module named "Module1", with a function named "Foo", then moving both libraries/modules into the database document's Basic libraries will lead to name clashes. Solving those in an automated way is possible, but references to those macros will almost certainly be broken then.

Second, a complete automatic migration requires a syntactical analysis of the macro/script code. For instance, imagine a Basic macro which does a LoadLibrary call with the name of a Basic library in the form document. If this library has been moved to the database document, and perhaps been renamed in this course, the LoadLibrary call would need to be adjusted to refer to the new name. This is effectively impossible without analyzing the Basic code, effectively compiling it. Similar arguments hold for other script types.

As a consequence, we won't migrate macros and scripts in sub documents automatically.

Compatibility Warning

Instead, we will show the following message box when the user opens a database document which contains a form or report with embedded scripts or macros:

Macros in Database Documents: Compatibility warning

Template:SpecUIElement/LabelHeading |- | style="vertical-align:top; background-color:#eeeeee;" | Label | style="vertical-align:top; background-color:#F8F8F8;" | Text | The document contains forms and/or reports with macros and/or scripts embedded. | |- | style="vertical-align:top; background-color:#eeeeee;" | Label | style="vertical-align:top; background-color:#F8F8F8;" | Text | Scripts and macros should nowadays be embedded into the database document itself.

You can continue to use your document as before, however, you are encouraged to migrate your scripts and macros. The menu item "Tools / Migrate Scripts and Macros ..." will assist you with this.

Note that you won't be able to embed macros or scripts into the database document until this migration is done. | |}

So, when the user simply opens an "old" document containing macros and/or scripts in the sub documents, nothing except the above warning will happen in the first instance. Until the user migrated the macros, the database document, and all sub documents, will behave as if the feature which this spec is about were never implemented. In particular, the user is free to create additional or modify existing macros in her forms and reports, to customize macros from sub documents into her toolbar/menu, to bind those macros to events in the sub documents, and so on.

Semi-automatic Migration

We will introduce a new menu item, called "Migrate Scripts and Macros ...", located in the top-level menu "Tools", immediately below the existing "SQL ..." item.

Menu Item(s)

Item Sub Item Sub Item KBD Shortcut Icon Comment
Migrate Scripts and Macros ...

TODO: specify the behavior in detail

Assigning Macros to Events

TODO: specify the Tools/Customize/Events appearance/behavior for database documents. We want, for instance, be able to assign a macro, embedded in the database document, to the document's OnLoad event.

Database Specific Events

TODO: specify events which are specific to database documents, and available in the Tools/Custormize/Events tab page. Not yet sure whether we need this.

Implementation Milestones

Timeline and Tasks

The development of this feature will produce the following milestones:

Milestone Due
M1
  • embedding/organizing/running macros/scripts works
  • the usual suspects (macro selector/organizer, customization dialog) do not display forms/reports anymore, but the database documents instead
  • macros, located in database documents, assigned to form/controls in forms, work as expected
  • you can customize database-document-located macros into toolbars/menus/events of forms/reports
2nd January 2008
M2
  • old documents offer the migration menu entry, but still work as before until migration is done
  • semi-automatic migration works as described in the specification
31st January 2008
M3
  • Assigning macros to database document events (Tools / Customize / Events) works. For instance, it is possible to assign a macro to the OnLoad event of an DB document itself.
20th February 2008
M4
  • loose ends are fixed
t.b.d.
M5

TODO: There's more to come here ...

t.b.d.

Milestone M1 and M2 are considered essential before the feature can be released. Milestone M3 is strongly desired. Milestone M4 is desired to be reached before a release, but not required.

Tasks

Task Status M
Base
M1 implement XStorageBasedDocument for database documents done
M1 implement XEmbeddedScripts for database documents done
M1 implement XScriptProviderSupplier for database documents done
M1 let database documents participate in the global WorkingDocument/ThisComponent game done
M1 switch off XEmbeddedScripts support for forms and reports done
M1 allow assigning macros from the database document to elements inside a form done
M1 implement XScriptInvocationContext for database documents done
M1 implement XScriptInvocationContext for database controllers which do not have an own XModel instance open
Application Framework
M1 customization dialogs should use the associated frame's document, not the WorkingDocument done
M1 executing scripts via Tools/Macros/Execute should also allow execution for non-Sfx-documents done
M1 let TDOC UCP create proper document identifiers for non-SFX documents done
M1 embedded document implementations (SFX) must allow to switch off the support for embedded macros/scripts done
M1 script selectors need to display the database document when invoked in form/report done
M1 let the SfxObjectShell make use of the XScriptInvocationContext when invoking scripts done
Scripting Framework
M1 the Basic script provider must not use the SfxObjectShell done
M1 the Basic/JavaScript/BeanShell script providers should respect the non-availability of the XEmbeddedScripts interface done
M1 design XScriptInvocationContext done
M1 let the ScriptProtocolHandler make use of the XScriptInvocationContext done
M1 let the Basic script provider implementation accept an XScriptInvocationContext as creation context done
M1 let the Basic script provider translate its invocation context into a global variable open
M1 let the BeanShell/JavaScript script provider implementations accept an XScriptInvocationContext as creation context open

Open Issues

Future Tasks

  • For the moment, it will not be possible to sign macros embedded in database documents. This is up to a later step.
  • Macro recording will still not be possible in database documents. This is a separate topic, which requires implementations in a completely different area.

Appendix

Glossary

Acronym / Abbreviation Definition
Customization dialog is the dialog which allows to customize menus, toolbars, keyboard and event bindings. Reached via Tools / Customize ... in all OpenOffice.org applications. For all aforementioned UI types, it allows to add macros or scripts, for instance, you can customize your toolbar or menu to include a reference certain Basic function. This holds for office-wide macros as well as document-local macros, in which case you usually store the customization in the document only, and not application-wide.

Note that the customization dialog is context-sensitive.

Macro Organizer is the dialog which you open via Tools / Macros / Organize Macros / OpenOffice.org Basic ... in all applications.
Macro Selector is the dialog which allows you to select a single macro. It is invoked whenever the user needs to specify a macro or script function or method, for instance when you choose the "Macro" button on the "Events" tab page of the organizer dialog. Note that there are cases where the macro selector allows to select macros or scripts from all currently-open documents (for instance when invoked via Tools / Macros / Run), and cases where it contains only macros/scripts from the active document (e.g. when invoked from the customization dialog of an active document).

Note that the macro selector is context-sensitive.

context-sensitive In the scope of this document, a UI element (usually a dialog) which displays a hierarchical list of macros and scripts, and allows to select macros and scripts to perform actions on them (editing, executing, and the like), is called context-sensitive when it will display the application-wide and the user-level macros and scripts, plus the macros and scripts located in the document from which this UI element was invoked.

In contrast, UI elements which display all macros and scripts in all documents which are currently opened, are not context-sensitive.

active document is the one document within OpenOffice.org which last got the focus (directly or indirectly, i.e. via one of its child windows).

References

Reference Document Check Location (URL)
Specification Process Entry Check [passed/failed] n/a
Product Requirement, RFE, Issue ID available

Possibility to put macros in *.odb files
Impossible to bind a macro to an OpenOffice.org Base document
RFE: add database specific event for macros to the database

Test case specification not available

Contacts

Role Name
Developer Frank Schönheit
Quality Assurance Marc Neumann
Documentation Uwe Fischer
User Experience Bettina Haberer
Personal tools