View source for Documentation/OOoAuthors User Manual/Getting Started/Macro organization

{{DISPLAYTITLE:Macro organization}}
{{Documentation/GSMacroTOC
|ShowPrevNext=block
|PrevPage=Documentation/OOoAuthors User Manual/Getting Started/Sometimes the macro recorder fails
|NextPage=Documentation/OOoAuthors User Manual/Getting Started/How to run a macro
}}__NOTOC__
In OpenOffice.org, macros are grouped in modules, modules are grouped in libraries, and libraries are grouped in library containers. A library is usually used as a major grouping for either an entire category of macros, or for an entire application. Modules usually split functionality types such as user interaction and calculations. Individual macros are subroutines and functions.

[[Image:Hierarchy.png|thumb|none|500px|Macro Library hierarchy.]]

Use '''Tools > Macros > Organize Macros > OpenOffice.org Basic''' to open the OpenOffice.org Basic Macros dialog. All available library containers are shown in the ''Macro from'' list. Every document is a library container, capable of containing multiple libraries. The application itself acts as two library containers, one container for macros distributed with OpenOffice.org called OpenOffice.org Macros, and one container for personal macros called My Macros. As shown below, only two documents are currently open.

[[Image:LibraryContainers.png|thumb|none|500px|Library containers are shown on the left.]]

The OpenOffice.org Macros are stored with the application runtime code, which may not be editable to you unless you are an administrator. This is just as well since these macros should not be changed and you should not store your own macros in the OOo container.

Unless your macros are applicable to a single document, and only to a single document, your macros will probably be stored in the My Macros container. The My Macros container is stored in your user area or home directory.

If a macro is contained in a document, then a recorded macro will attempt to work on that document; primarily because it uses “ThisComponent" for its actions.

Every library container contains a library named ''Standard''. It is better to create your own libraries with meaningful names than to use the Standard library. Not only are meaningful names easier to manage, but they can also be imported into other library containers whereas the Standard library cannot.

{{Documentation/Caution|OpenOffice.org allows you to import libraries into a library container, but it will not allow you to overwrite the library named Standard. Therefore, if you store your macros in the Standard library, you cannot import them into another library container.}}

Just as it makes good sense to give your libraries meaningful names, it is prudent to use meaningful names for your modules. By default, OpenOffice.org uses names such as Module1. Feel free to use your own meaningful name.

As you create your macros, you must decide where to store them. Storing a macro in a document is useful if the document will be shared and you want the macro to be included with the document. Macros stored in the application library container named My Macros, however, are globally available to all documents.

Macros are not available until the library that contains them is loaded. The Standard library and Template library, however, are automatically loaded. A loaded library is displayed differently from a library that is not loaded. To load the library and the modules it contains, double-click on the library.

==Where are macros stored?==

OpenOffice.org stores user-specific data in a directory under the user's home directory. For example, on Windows, this is C:\Documents and Settings\<name>\Application Data. User macros are stored in OpenOffice.org2\user\basic. Each library is stored in its own directory off the basic directory.

It is not important to understand where macros are stored for casual use. If you know where they are stored, however, you can create a backup, share your macros, or inspect them if there is an error. For example, on one or more of my OpenOffice.org upgrades, all of my macros disappeared. Although the macros were still on disk, the macros were not copied to the new directories. The solution was to import the macros into the new installation.

Use '''Tools > Macros > Organize Dialogs''' to open the OpenOffice.org Macros organizer dialog. Another common way to open this dialog is to use '''Tools > Macros > Organize Macros > OpenOffice.org Basic''' to open the OpenOffice.org Macros dialog and then click the '''Organizer''' button (see Figure 6).

[[Image:MacroOrgLibraries.png|thumb|none|500px|Figure 6: The Libraries tab of the Macro Organizer dialog.]]

==Importing macros==

The OpenOffice.org Macro Organizer dialog provides functionality to create, delete, and rename libraries, modules, and dialogs. Select the library container to use and then click the '''Import''' button to import macro libraries. 

[[Image:ImportMacro.png|thumb|none|500px|Select a macro library to import.]]

{{Documentation/Tip|You cannot import the library named Standard.}}

{{Documentation/Tip|On Linux, the OpenOffice.org-specific files are stored in a directory whose name begins with a period. Directories and files with names beginning with a period are not shown in a normal selection dialog. To open the directory, I navigated to the parent directory, entered the name .openoffice.org2, and then clicked '''Open'''. This opened the directory, which was not initially shown.}}

Navigate to the directory containing the library to import. There are usually two files from which to choose, dialog.xlb and script.xlb. It does not matter which of these two files you select; both will be imported. Select a file and click '''Open''' to continue.

[[Image:MacroImportOptions.png|thumb|none|500px|Choose library import options.]]

If the library already exists, it will not be replaced unless '''Replace existing libraries''' is checked. If '''Insert as reference''' is checked, the library is referenced in its current location, but you cannot edit the library. If '''Insert as reference''' is not checked, however, the library is copied to the user's macro directory.

Macros can be stored in libraries inside OpenOffice.org documents. Select a document rather than a directory on disk (as shown in Figure 7) to import libraries contained in a document.

==Downloading macros to import==

Macros are available for download. Some macros are contained in documents, some as regular files that you must select and import, and some as macro text that should be copied and pasted into the Basic IDE; use '''Tools > Macros > Organize Macros > OpenOffice.org Basic''' to open the OpenOffice.org Macros dialog, choose the macro to edit, and then click '''Edit''' to open the macro in the Basic IDE.

Some macros are available as free downloads on the Internet (see Table 1).

''Table 1. Places to find macro examples.''

{|border="1" cellpadding=4 style="border-collapse:collapse;"
|-bgcolor=#EDEDED
!Location !! Description
|-
||[http://www.ooomacros.org/ http://www.ooomacros.org/]||Excellent collection of packaged macros.
|-
||[http://www.pitonyak.org/oo.php http://www.pitonyak.org/oo.php]||Reference materials regarding macros.
|-
||[http://www.pitonyak.org/database/ http://www.pitonyak.org/database/]&nbsp;&nbsp;&nbsp;||Reference materials regarding database macros.
|-
||[http://development.openoffice.org/ http://development.openoffice.org/]&nbsp;&nbsp;&nbsp;||Lots of links to everything.
|-
||[http://www.oooforum.org/ http://www.oooforum.org/]||Many examples and help.
|-
|}

{{Manual}}
[[Category:Getting Started (Documentation)]]