Difference between revisions of "Macros in Database Documents"
(→Semi-automatic Migration) |
(→Definition and Timeline) |
||
Line 80: | Line 80: | ||
| colspan="2" | '''Milestone''' || '''Due''' | | colspan="2" | '''Milestone''' || '''Due''' | ||
|- | |- | ||
− | | style="background-color:#c0c0ff" | M1 || embedding/organizing/running macros/scripts works || t.b.d. | + | | style="background-color:#c0c0ff" | M1 || |
+ | * embedding/organizing/running macros/scripts works | ||
+ | || t.b.d. | ||
|- | |- | ||
− | | style="background-color:#ffc0c0" | M2 || sub documents cannot contain macros/scripts anymore | + | | style="background-color:#ffc0c0" | M2 || |
+ | * sub documents cannot contain macros/scripts anymore | ||
+ | * old documents which still do offer the migration menu entry, but work as before until migration is done | ||
+ | * semi-automatic migration works as described in the specification | ||
+ | || t.b.d. | ||
|- | |- | ||
− | | style="background-color:#ffe0ff" | M3 || Assigning macros to database document events ({{menuitem|Tools / Customize / Events}}) works. For instance, it is possible to assign a macro to the <code>OnLoad</code> event of an DB document itself. || t.b.d. | + | | style="background-color:#ffe0ff" | M3 || |
+ | * Assigning macros to database document events ({{menuitem|Tools / Customize / Events}}) works. For instance, it is possible to assign a macro to the <code>OnLoad</code> event of an DB document itself. | ||
+ | || t.b.d. | ||
|- | |- | ||
| style="background-color:#c0ffc0" | M4 || TODO || t.b.d. | | style="background-color:#c0ffc0" | M4 || TODO || t.b.d. |
Revision as of 14:32, 28 November 2007
Specification Status | |
Author | Frank Schönheit |
Last Change | 2007-11-28 |
Status (Help) | Preliminary |
Contents
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
Help | User Interface Element Templates
Accessing Macros and Scripts
- Macro and Script Organizers (Template:Menuitem) 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 (Template:Menuitem) will show opened database documents, and allow to run them.
- The UI customization dialog (Template:Menuitem) will allow access to the current database document's macros and scripts, when invoked for this document.
Basic Macros
- In a running Basic macro embedded in a database document, the globally available context variable
ThisComponent
will contain 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:
Template:SpecUIElement/Label Template:SpecUIElement/Label
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 |
TODO
Implementation Milestones
Definition and Timeline
The development of this feature will produce the following milestones:
Milestone | Due | |
M1 |
|
t.b.d. |
M2 |
|
t.b.d. |
M3 |
|
t.b.d. |
M4 | TODO | t.b.d. |
M5 | TODO | t.b.d. |
Tasks
Task | Status | M |
<area> | ||
<lengthy task description> | planned | M1 |
<lengthy task description> | planned | M1 |
<area> | ||
<lengthy task description> | planned | M1 |
<lengthy task description> | planned | M2 |
Open Issues
- When assigning a macro, located in the database document, to, say, the "When initiated" event of a button in an embedded form document: should the called Basic code have some easy access to the form which the button lives in? It might become necessary to refer to this form document, similar to how
ThisComponent
will refer to the database document as a whole. On the other hand, the macros get ancss.lang.EventObject
, which in all cases is sufficient to obtain the form document (which is an ancestor in the parent-child-hierarchy of the control model).
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
Acronyms and Abbreviations
Acronym / Abbreviation | Definition |
Customization dialog | is the dialog which allows to customize menus, toolbars, keyboard and event bindings. Reached via Template:Menuitem 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. |
Macro Organizer | is the dialog which you open via Template:Menuitem in all applications. |
Macro Selector | is the dialog 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 Template:Menuitem), and cases where it contains only macros/scripts from the active document (e.g. when invoked from the customization dialog of an active document). |
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 |
Test case specification | not available |
Contacts
Role | Name |
Developer | Frank Schönheit |
Quality Assurance | Marc Neumann |
Documentation | Uwe Fischer |
User Experience | Bettina Haberer |