Custom Apache OpenOffice Basic Macros and Libraries

From Apache OpenOffice Wiki
Jump to: navigation, search


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

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

About Apache OpenOffice Basic Libraries and Modules

The default Apache OpenOffice 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 Apache OpenOffice Basic source code for a single Apache OpenOffice Basic module. The file name corresponds to the module name.
*.xdl
An XML file that stores the dialog elements of an Apache OpenOffice Basic dialog box. The file name corresponds to the dialog name.
*.pba
An Apache OpenOffice Basic module which is protected with a password, that is, the source code is encrypted. The file name corresponds to the module name.

About Apache OpenOffice Basic Configuration Files

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

Documentation caution.png

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 Apache OpenOffice. The following tags are used:

library:name
Specifies the name of the Apache OpenOffice Basic library.
xlink:href
Specifies the URL of the script.xlb file for the library. The URL must begin with the file:/// notation.
Documentation note.png You do not need to specify a value for the xlink:href tag if the library is in the <Apache OpenOffice 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 Apache OpenOffice 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 Apache OpenOffice 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 Apache OpenOffice Basic Configuration File

Distributing Apache OpenOffice Basic Libraries

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

Documentation note.png 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 Apache OpenOffice Basic Library Available to All Users on a Network

Use Apache OpenOffice 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 Apache OpenOffice server installation.
    cp -r install-dir/user/basic/custom library install-dir/share/basic/
    Documentation note.png 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 Apache OpenOffice on the workstations.

To Make a Custom Apache OpenOffice 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 Apache OpenOffice.

To Install a Custom Apache OpenOffice Basic Library With a Macro

You can create a macro that installs a Apache OpenOffice Basic library from an Apache OpenOffice document.

  1. In Writer, create a custom Apache OpenOffice Basic library in a new document.
  2. Save the document.
  3. Create an installation macro.
    1. Choose Tools → Macros → Organize Macros → Apache OpenOffice Basic. The Apache OpenOffice 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:
    6.  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 &lt;= 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
    7. Replace the SrcLibraryName and DestLibraryName variables with the name of your library.
    8. 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).
Personal tools
In other languages