Difference between revisions of "Macros in Database Documents"
(→Future Tasks) |
(→Future Tasks) |
||
Line 330: | Line 330: | ||
* For the moment, it will not be possible to sign macros embedded in database documents. This is up to a later step. | * 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. | * Macro recording will still not be possible in database documents. This is a separate topic, which requires implementations in a completely different area. | ||
− | * In the course of the implementation, we fixed the [http://www.openoffice.org/issues/show_bug.cgi?id=68333 issue] which | + | * In the course of the implementation, we fixed the [http://www.openoffice.org/issues/show_bug.cgi?id=68333 issue] which requested to be able to store menu/toolbar/keyboard customizations in form/report documents. That is, you can explicitly tell a certain toolbar/item to appear in one concrete document only. It would be desirable to allow the same for tables and queries, and perhaps even the relation designer: For all of those, you might wish to do a customization for one concrete object (table/query) only, not for all objects of this type. |
Going further, you might even want to have a database-document-wide configuration for all objects of a certain type. That is, you might want to have a certain toolbar appearing in all tables of the database document, but *not* in the tables of other database documents. | Going further, you might even want to have a database-document-wide configuration for all objects of a certain type. That is, you might want to have a certain toolbar appearing in all tables of the database document, but *not* in the tables of other database documents. | ||
Revision as of 13:35, 23 January 2008
Specification Status | |
Author | Frank Schönheit |
Last Change | 2008-01-23 |
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
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.
Consequences:
- You will be able to run any macro/script which is embedded in a database document from either the document itself, or any of its sub components: forms, reports, table design, query design, relation design, table data view.
- You will be able to customize any such macro/script into a toolbar, or a menu, of any sub component.
Changes to Script Languages
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, thenThisComponent
will refer to the single document that was last active before the database document became active.
Changes with Macros in Database Documents
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 components" 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 at the very same time to the document in which the macro was located. Both are actually the same.
With macros in database documents, that becomes different: Users shall be able to execute, in a form document, macros which are located in the database document. Even more, users shall be able to execute such macros in other sub components of a database document, such as the query designer. Those sub components usually don't even have a XModel
associated with them.
We will do this separation by introducing another global variable, called ThisDatabaseDocument
. This variable will be available in Basic macros which are embedded into a database document, and always refer to this very document.
|
See the discussion page of this article for a discussion on this new variable |
ThisComponent
, in turn, will always be the component which was active when the macro was invoked. This holds no matter whether the macro is located in the database document's or in the application's Basic library. Also, it holds no matter whether the active component is a database document or any of its sub components. In particular, the various designers are also available as ThisComponent
.
Script Contexts in other Script Languages
In other script languages, there is no strict equivalent of Basic's ThisComponent
. Instead, scripts in other languages get an instance of XScriptContext
passed, which has an method getDocument, to "obtain the document reference on which the script can operate".
Such scripts also need to distinguish between the component for which they were invoked, and the document in which they're actually embedded (if any).
This is done by introducing a member XScriptContext::getInvocationContext
. It will refer to the component from which the script was invoked, being either a document (i.e. supporting XModel
) or a controller (i.e. supported XController
).
XScriptContext::getDocument
will continue to refer to the document in which the running script is embedded (if any), so if a script is invoked from within the document in which it is embedded, then XScriptContext::getInvocationContext
will equal XScriptContext::getDocument
.
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:
User Interface Elements
Type | Property | Value | Comment |
Label | Text | The document contains forms and/or reports with macros and/or scripts embedded. | |
Label | 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.
Migration Wizard
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 ... |
The menu item is available only if any of the database document's sub documents contains scripts or macros.
When the user selects this menu item, a wizard will guide her through the migration, which effectively consists of the following steps:
- close all sub components of the database document, namely forms, reports, and any open designers
- backup the database document
- migrate the scripts and macros while displaying a progress bar
- show a summary
Preparation
The first step of the wizard looks as follows:
- page contains explanatory text only
- 'Finish' button is disabled
- in the roadmap, steps "3. Migrate" and "4. Summary" are disabled
- when leaving the page by pressing 'Next' or clicking another step in the wizard's roadmap, all sub documents of the database document are closed
- when closing the sub documents is not successful, e.g. because the user vetoes closing a modified sub document, the wizard will stay open, but not advance to another page
User Interface Elements
Type | Property | Value | Comment |
Label | Text | Welcome to the Database Macro Migration Wizard | |
Label | Text | This wizard will guide you through the task of migrating your macros and scripts.
After you finished it, all macros and scripts which were formerly embedded into your forms and reports will have been moved to the database document. In this course, libraries and modules will be renamed as needed. If your forms and reports contain references to those macros and scripts, they will be adjusted, where possible. Before the migration can start, all forms, reports, queries and tables must be closed. Press 'Next' to do so. |
Backup
- allows user to choose a location/name to backup her document to
- input field for backup location:
- is the usual auto-completion input field, as known from e.g. the internal File-Open-dialog and the "Load URL" box in the standard toolbar
- will be pre-filled with a location/name which is the database document's location/name, with an additional part ".backup" before the extension
- 'Browse' button:
- will open a file picker (effectively a "Save As" dialog), titled "Backup"
- closing this dialog with OK will fill in the chosen file name into the input field
- wizard logic:
- 'Finish' button is disabled
- in the roadmap, steps "4. Summary" is disabled
- upon pressing 'Next', or clicking onto "3. Migration" in the roadmap
- the document is backed up to the chosen location
- if the backup fails, the message of the error which happened will be shown - the same which would be shown when the user would have initiated a normal File/Save As operation
User Interface Elements
Type | Property | Value | Comment |
Label | Text | Backup your Document | |
Label | Text | To allow you to go back to the state before the migration, the database document will be backed up to a location of your choice. Every change done by the wizard will be made to the original document, the backup will stay untouched. | |
Label | Text | Save To: | |
Button | Text | Browse ... | |
Label | Text | Press 'Next' to save a copy of your document, and to begin the migration. |
Migrate
- migration will start as soon as the page is entered
- for every form/report:
- the document be loaded (hidden from the user)
- the macro, script and dialog libraries in the document will be moved to the database document, and renamed by prefixing the library name with
- "Form_" respectively "Report_"
- the name of the form/report itself, with an appended _
- example: In a form named "customers", the library "Standard" would be renamed to "Form_customers_Standard"
- the document will be stored
- 'Current object' contains the name of the form or report which is currently being processed
- 'Current action' is either one of
- "loading ..." when the form/report is being loaded
- "migrating libraries ..." when the macro, script and dialog libraries are being migrated
- "saving ..." when the form/report is being saved
- 'Current progress' shows the progress of the current action.
- when loading and saving the form/report, this progress bar is the same as would normally appear at the bottom of the window into which the document would be loaded
- 'Overall progress' shows the relative number of processed documents, both as number and as progress bar
- the explanatory text at the bottom of the page
- is initially hidden
- will appear when the migration was finished
- wizard logic:
- 'Back', 'Next', 'Finish', 'Cancel' buttons are initially disabled
- in the roadmap, all steps except the current one are initially disabled
- 'Next', 'Finish', 'Cancel' will be enabled as soon as the migration was finished
- in the roadmap, '4. Summary' will be enabled as soon as the migration was finished
- error handling
TODO: There's more to come here ...
User Interface Elements
Type | Property | Value | Comment |
Label | Text | Migration Progress | |
Label | Text | The database document contains $forms$ form(s) and $reports$ report(s), which are currently being processed: | $forms$ and $reports$ will be replaced by actual numbers at runtime |
Label | Text | Current object: | |
Label | Text | Current action: | |
Label | Text | loading ... | |
Label | Text | migrating libraries ... | |
Label | Text | saving ... | |
Label | Text | Current progress: | |
Label | Text | Overall progress: | |
Label | Text | document $current$ of $overall$ | $current$ and $overall$ will be replaced by actual numbers at runtime |
Label | Text | All documents have been successfully processed. Press 'Next' to show a detailed summary. |
Summary
- shows a summary to what changes were
User Interface Elements
Type | Property | Value | Comment |
text particle | text | Database Document | |
text particle | text | saved copy as $location | $location$ will be replaced at runtime with a file location$ |
text particle | text | Form $name$ | $name$ will at runtime be replaced with the actual name of a form document |
text particle | text | Report $name$ | $name$ will at runtime be replaced with the actual name of a report document |
text particle | text | moved $type$ library $old$ to $new$ | $type will be replaced with either one of "OpenOffice.org Basic", "dialog", "script". $old$ and $new$ will be replaced with actual names of the library. |
text particle | text | dialog | This word will appear as part of the phrase "... moved $type$ library ..." (see above) |
text particle | text | script | This word will appear as part of the phrase "... moved $type$ library ..." (see above) |
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
The development of this feature will produce the following milestones:
Milestone | Due | |
M1 |
|
2nd January 2008 |
M2 |
|
31st January 2008 |
M3 |
|
20th February 2008 |
M4 |
|
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 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 |
done |
M1 | create a ThisDatabaseDocument variable in the document's basic |
done |
M1 | properly propagate JavaScriptEditor modifications to the document | done |
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 (temporarily) set ThisComponent to its ScriptInvocationContext |
done |
M1 | allow JavaScript/BeanShell script providers to be created with an XScriptInvocationContext (instead of a model's TDOC URL) |
done |
M4 | let the Basic IDE manipulate a document's ThisComponent to be the component of the document's active sub/frame |
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.
- In the course of the implementation, we fixed the issue which requested to be able to store menu/toolbar/keyboard customizations in form/report documents. That is, you can explicitly tell a certain toolbar/item to appear in one concrete document only. It would be desirable to allow the same for tables and queries, and perhaps even the relation designer: For all of those, you might wish to do a customization for one concrete object (table/query) only, not for all objects of this type.
Going further, you might even want to have a database-document-wide configuration for all objects of a certain type. That is, you might want to have a certain toolbar appearing in all tables of the database document, but *not* in the tables of other database documents.
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 |
Test case specification | not available |
Contacts
Role | Name |
Developer | Frank Schönheit |
Quality Assurance | Marc Neumann |
Documentation | Uwe Fischer |
User Experience | Bettina Haberer |