Difference between revisions of "Documentation/Administration Guide/Using Custom Macros and Libraries"

Latest revision as of 16:01, 27 May 2021

>]]

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.

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

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

dialog.xlb

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

*.xba

A 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

A 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.

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.

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.

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/

   On Windows, the location of the custom library you created is C:\Documents and Settings\username\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\username\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 → 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:

 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.