[Tutorial] How to install a code snippet

[Hagar Delest]

To install the code:

• Select the whole code (note that there is a SELECT ALL button in the code section header that will do it for you)
• Copy that selection to the clipboard (CTRL+C)
• In OOo, go to Tools>Macros>Organize Macros>OpenOffice.org Basic
• Expand My Macros>Standard (or better: create a custom one, see post below) and select the Module1 sheet, then the Main entry and hit Edit button
• Select All the default entries (CTRL+A)
• Paste the clipboard (CTRL+V)
• (You can rename the Module1 to have a better name)

To run the code:

• Open a (new) document on which the macro applies
• Go to Tools>Macros>Run Macro... then expand the My Macros library until you find the macro name and hit the Run button (beware: macros are listed in the alphabetical order)
  Or better:
• Use the Tools>Macros>Organize Macros>OpenOffice.org Basic dialog because it keeps in memory the last library and module opened and macros are listed in the same order as in the Basic IDE interface.

To bind the code to a shortcut:

• [Tutorial] Binding a macro: Shortcut key, menu or toolbar

We have installed the macro in the user library (My Macros), it can also be installed in the main installation folder (OpenOffice.org Macros) or even in a document (say Untitled1 if you've just created a new document for the test). But if you save in the document, the macro will be available only if that document is opened (don't forget to save it BTW).

For any comment, please post in that thread: How to install a Code Snippet?

[Villeroy]

Addition to the above short answer, which puts everything in some module of default library "Standard":
There have been reports (and I suffered from this as well) that updating the office suite may overwrite library "Standard" with a new library "Standard" having a blank "Module1". I'd recommend that you organize your own set of libraries. This is particulary useful when you collect many snippets in modules, let's say one library for each office component Calc, Writer, Database, Drawing, another one for office in general (file pickers, dialogs).
How to add a new library:
- Tools>Macros>Organize>OOo Basic... [like above]
- Button [Organize...], tab library, button [New...]
- Go back to tab "Modules", browse "My Macros">"your_new_library">"Module1"
- Button

Edit:  lets you paste your copied code into the module described by Hagar de l'Est. - You may want to give a more descriptive name to "Module1". Right-click the "Module1"-tab and rename. The Basic organizer organizes ... Basic containers all have a default library "Standard". It is always loaded even when you don't need it. Basic containers are Office documents and the public container which has two places to store code: the individual user profile (in the GUI refered to as "My Macros") and the overall office installation for all users (in the GUI refered to as "OpenOffice.org Macros"). Documents are the best container for all macros supposed to carry their functionality with the document. The public container is the best place for macros supposed to work with any appropriate document. Libraries in containers: As office user you can easily add Basic-libraries to the document's container and the user-location ("My Macros") of the public container. If you want to store libraries publicly availlable under "OOo Macros" for all users of this installation, the easiest way is to export the respective library, which must not be "Standard", as an extension and install the extension with admin-privileges. Modules in libraries can be used to organize code within libraries. Modules can share global variables and userdefined types independend from each other. In most cases is not that important in which modle you paste code from a forum as long as you can find the snippet later, so it may be a good idea to rename "Module1" by a more descriptive name. Directly callable routines in modules (Basic Sub and Function) are those, which do not require additional arguments. They should be mentioned by the author ("to use this macro, call routine ..."). Typical examples: Code: Select all Sub Main Sub Start() '< the empty braces mean nothing Sub Run(Optional arg) Sub UpdateItems(oList, aItems()) Example "Run" may be called from other macros with additional info passed over. It should work also when called interactively by the user. Example "UpdateItems" requires two arguments. It is supposed to be called with the required information from other code. When called interactively by the user it will fail due to missing arguments. An organized set of libraries has several advantages in the long run. Any GUI-action or event will load the library on the fly unless the code has been moved meanwhile. Think first where to store your code before assigning any events or GUI-controls to the code. Code calling other code has to load the other code's library explicitly (not required for library "Standard"): Code: Select all REM load another library before calling any code in it: REM GlobalScope refers the public container (merged "MyMacros" and "OOo Macros") GlobalScope.BasicLibraries.loadLibrary("Calc") REM Call myRound in module Functions, library Calc myResult = Calc.Functions.getRound(myValue,3) Scripting languages other than Basic Simply dump the code files in the user profile or the installation path. Typical Linux paths: User profile, v2.x: ~/.openoffice.org2/user/Script/<Language> User profile, v3.x: ~/.openoffice.org/3/user/Script/<Language> Application, v2.x: /opt/openoffice.org2/share/Script/<Language> Application, v3.x /opt/openoffice.org/basis3.0/share/Scripts/<Language> Some Windows paths: - XP user profile: \Documents and Settings\<user name>\Application Data\OpenOffice.org\3\user\Scripts\<Language> - Vista user profile: \Users\<user name>\AppData\Roaming\OpenOffice.org\3\user\Scripts\<Language> - XP application: C:\Program Files\OpenOffice.org 3\Basis\share\Scripts\<Language> Mac user profile: /Users/<user name>/Library/Application Support/OpenOffice.org/3/user where <Language> is one of beanshell, java, javascript, python (or as documented for other languages) and <user name> is the name of the respective user. If the code compiles OK and can be used as macro, then it should appear in menu:Tools>Macros>Organize>[Language]... "My Macros" or "OpenOffice.org Macros" respectively. Notes on Python code: White space has a meaning in Python and this forum's software indents with additional space when you click the "Select All" command above each code section. Select and copy the code manually to avoid the extra indentation.

[Villeroy]

Again, from another view point, there are 2 places for macros:

1. Embedded in a document for document specific tasks, relying on a certain document or template. In Basic the global variable ThisComponent always refers to the containing office document. Code written in some other language can be embedded into a document with some XML-config in the document's zip container.
#################################################
2. Global macro container for general code that applies to many documents or the application as a whole. A macro in this name space is accessible when you load the document and call the macro from the user interface.
In Basic the global variable ThisComponent refers to the last active office document, including help files, not counting the Basic-IDE.

2.1 OpenOffice.org Macros: OOo comes with a set of preinstalled macros, stored in the installation directory. The macros therein are public to all users of this machine. This sub-container is read-only and installation requires admin-access. Extension packages are the best way to install Basic macros with in this section of the global container. Macros written in other languages are simple source code files which can be copied to the right place in the install directory.
2.2 My Macros: The sub-container where you install/edit/delete your own macros in your own user profile directory, visible to the current user, usable at any time from the user interface. Macros written in other languages are simple source code files which can be copied to the right place in the profile directory.
2.1. and 2.2 are sections of the same name space. You can not add library Tools to "My Macros" since library Tools is already in the other section. For the same reason you can not add library Standard to "OpenOffice.org Macros" since that special library is already part of the other section in the same name space.