EN/documentation/administration guide/using custom macros and libraries

OpenOffice.org Administration Guide

{{{parttitle}}}

[[{{{PrevPart}}}|< Previous Section ]]

[[{{{NextPart}}}| Next Section >]]

• Deploy OpenOffice.org using package managers

• Solaris Sparc/x86
• Linux x86
• Microsoft Windows
• Mac OS X

• Custom OpenOffice.org Basic Macros and Libraries
• OpenOffice.org Extension Manager
• Adding Template Files to an OpenOffice.org Installation
• Adding AutoText Files to an OpenOffice.org Network Installation
• Deactivating the OpenOffice.org Registration Wizard
• Accessing Email Clients
• Customizing the User Interface
• Restricting Functionality in OpenOffice.org
• Accessing OpenOffice.org User Profiles on an LDAP Server

< Previous Page

Next Page >

OpenOffice.org Basic is a programming language you can use to automate tasks in OpenOffice.org. OpenOffice.org Basic macros are stored in modules that in turn are stored in libraries. Libraries also act as containers for dialog boxes you create in OpenOffice.org Basic. You can store Basic libraries in any directory that a user can access.

Use OpenOffice.org extensions for packaging and deploying Basic Libraries. The OpenOffice.org Developer's Guide describes these Extensions in detail.

About OpenOffice.org Basic Libraries and Modules

The default OpenOffice.org Basic libraries are located in the install-dir/share/basic directory. A library contains the following files:

script.xlb

An XML file that contains the names of the modules in the library.

dialog.xlb

An XML file that contains the names of dialog boxes in the library.

*.xba

An XML file that stores the OpenOffice.org Basic source code for a single OpenOffice.org Basic module. The file name corresponds to the module name.

*.xdl

An XML file that stores the dialog elements of an OpenOffice.org Basic dialog box. The file name corresponds to the dialog name.

*.pba

An OpenOffice.org Basic module which is protected with a password, that is, the source code is encrypted. The file name corresponds to the module name.

About OpenOffice.org Basic Configuration Files

The script.xlc and dialog.xlc configuration files list the location of OpenOffice.org Basic libraries and dialog boxes. These files are located in the install-dir/user/basic/ directory which also contains the default Standard OpenOffice.org Basic library as well as the user-defined libraries.

You cannot change the location of the script.xlc and dialog.xlc configuration files.

The XML-based script.xlc file includes a list of all Basic libraries that are available to OpenOffice.org. The following tags are used:

library:name

Specifies the name of the OpenOffice.org Basic library.

xlink:href

Specifies the URL of the script.xlb file for the library. The URL must begin with the file:/// notation.

You do not need to specify a value for the xlink:href tag if the library is in the <OpenOffice.org installation directory>/user/basic directory.

xlink:type

This tag, required by the xlink:href tag, must be set to simple.

library:link

Specifies that the entry is a link to a library that is not in the default library location. The default location for OpenOffice.org Basic libraries is install-dir/user/basic. If you only use the default location for the libraries, set the value of this tag to false. For all other libraries, set the value of this tag to true.

library:readonly

Specifies whether a library is read-only. Set the value of this tag to true for read-only access.

The following XML code is for a script.xlc configuration file for OpenOffice.org Basic libraries. The only difference between this file and a dialog.xlc file is that the xlink:href tag points to the script.xlb file of a library instead of the dialog.xlb file.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE library:libraries PUBLIC 
"-//OpenOffice.org//DTD OfficeDocument 1.0//EN" "libraries.dtd">

<library:libraries 
xmlns:library="http://openoffice.org/2000/library" 
xmlns:xlink="http://www.w3.org/1999/xlink">

<library:library library:name="Standard" 
xlink:href="file:///.../user/basic/Standard/script.xlb/" 
xlink:type="simple" library:link="false"/>

<library:library library:name="FormWizard" 
xlink:href="file:///.../share/basic/FormWizard/script.xlb/" 
xlink:type="simple" library:link="true" library:readonly="false"/>
</library:libraries>

Sample OpenOffice.org Basic Configuration File

Distributing OpenOffice.org Basic Libraries

You can make custom OpenOffice.org Basic libraries available to either existing OpenOffice.org installations or new installations only.

The script.xlc and dialog.xlc configuration files are located in the following directories: Solaris and Linux platforms: install-dir/usr/basic/ Windows: C:\Documents and Settings\user-id\Application Data\install-dir\user\basic\

To Make a Custom OpenOffice.org Basic Library Available to All Users on a Network

Use OpenOffice.org to create a custom library as well as the macros in the library.

1. As root, copy the custom library from the user installation where you created the library to the OpenOffice.org server installation.
   cp -r install-dir/user/basic/custom library install-dir/share/basic/

   On Windows, the location of the custom library you created is C:\Documents and Settings\user-id\Application Data\installation-dir\user\basic\custom library

2. In the script.xlc configuration file for the user installation, add a link to the script.xlb configuration file for the library.
   Use the following syntax for the link:

    <library:library library:name="Library Name"
    xlink:href="$(USER)/basic/Library Name/script.xlb/"
    xlink:type="simple" library:link="true" library:readonly="false"/>

3. In the dialog.xlc configuration file for the user installation, add a link to the script.xlb configuration file for the library.
   Use the following syntax for the link:

    <library:library library:name="Library Name"
    xlink:href="$(USER)/basic/Library Name/dialog.xlb/"
    xlink:type="simple" library:link="false"/>

4. Restart OpenOffice.org on the workstations.

To Make a Custom OpenOffice.org Basic Library Available to a Single User

1. Copy the custom library from the user installation where you created the library to the user installation where you want to deploy the library.
   • On the Solaris and Linux platforms, become root, and copy the library.

   cp -r ''install-dir''/user/basic/custom library ''install-dir''/user/basic/

   • On Windows, become a user with administrator privileges, and copy the library.
     

   The file name path for the library is C:\Documents and Settings\user-id\Application Data\install-dir\user\basic\custom library

2. In the script.xlc configuration file for the user installation, add a link to the script.xlb configuration file for the library.
   Use the following syntax for the link:

    <library:library library:name="Library Name"
    xlink:href="$(USER)/basic/Library Name/script.xlb/"
    xlink:type="simple" library:link="true" library:readonly="false"/>

3. In the dialog.xlc configuration file for the user installation, add a link to the script.xlb configuration file for the library.
   Use the following syntax for the link:

    <library:library library:name="Library Name"
    xlink:href="$(USER)/basic/Library Name/dialog.xlb/"
    xlink:type="simple" library:link="false"/>

4. Restart OpenOffice.org.

To Install a Custom OpenOffice.org Basic Library With a Macro

You can create a macros that installs a OpenOffice.org Basic library from an OpenOffice.org document.

1. In Writer, create a custom OpenOffice.org Basic library in a new document.
2. Save the document.
3. Create an installation macro.
1. Choose Tools → Macros → Organize Macros → OpenOffice.org Basic. The OpenOffice.org Basic Macros dialog box appears.
2. In the Macro from list, select your Writer document.
3. In the Macro name box, type a name from the installation macro.
4. Click the New button. The BASIC IDE window appears.
5. Type the following code:

 Sub AddBasicLibrary
  Dim SourceLibraryName As String, DestLibraryName As String
  Dim oSrcLib As Object, oDestLib As Object, iCounter As Integer
  Dim oLib As Object, oGlobalLib As Object
  
  ' set these 2 variables to your lib name
  SrcLibraryName = "TextLib" 
  ' The name of the library that contains the modules
  DestLibraryName = "NewLib" 
  ' This library will be created and is the 
  ' destination for the modules from the source document.
  
  oLib = BasicLibraries        ' For Basic libaries
  oGlobalLib = GlobalScope.BasicLibraries
  For iLib = 1 To 2 
    If oGlobalLib.hasByName( DestLibraryName ) = False Then
      oGlobalLib.createLibrary( DestLibraryName )
    End If
    If oLib.hasByName( SrcLibraryName ) Then
      oLib.loadLibrary( SrcLibraryName )
      oSrcLib = oLib.getByName( SrcLibraryName )
      sSrcModules = oSrcLib.getElementNames()
      iCounter = lBound( sSrcModules() )
  
      while( iCounter <= uBound( sSrcModules() ) )
        oDestLib = oGlobalLib.getByName(DestLibraryName)
        If oDestLib.hasByName( sSrcModules(iCounter) ) = False Then
          oDestLib.insertByName( sSrcModules(iCounter),_
          oSrcLib.getByName( sSrcModules(iCounter) ) )
        End If
        iCounter = iCounter + 1
      wend
    End If
  
    oLib = DialogLibraries   ' The same for the Dialog libraries
    oGlobalLib = GlobalScope.DialogLibraries
  Next iLib
 End Sub

6. Replace the SrcLibraryName and DestLibraryName variables with the name of your library.
7. Close the BASIC IDE window.
4. Add a push button to the document.
1. On the Form Controls toolbar, click the Push Button icon.
2. In your document, drag to draw the button.
5. Assign the installation macro to a button event.
1. Right-click the new button and choose Control.
2. Click the Events tab.
3. Click the ellipsis (...) next to a button event. For example, the Mouse button pressed event might be used.
4. In the Assign Action dialog box, click the Macro button. The Macro Selector dialog box appears.
5. In the Library list, select the library that contains the installation macro.
6. In the Macro name list, select the installation macro.
7. Click OK.
8. In the Assign Macro dialog box, click OK.
6. Save the document.

Content on this page is licensed under the Public Documentation License (PDL).