| <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> |
| <html> |
| <head> |
| <title>Writing Scripts in BeanShell and Java</title> |
| |
| <meta HTTP-EQUIV="content-type" CONTENT="text/html; charset=UTF-8"> |
| </head> |
| <body> |
| <h1>Writing Scripts in BeanShell, JavaScript and Java</h1> |
| <a name="top"></a> |
| <h2>Contents</h2> |
| <ul> |
| <li> |
| <p><a href="#bsh">Hello World in BeanShell</a> </p> |
| </li> |
| <li> |
| <p><a href="#bshinvoke">Trying out your BeanShell script</a> </p> |
| </li> |
| <li> |
| <p><a href="#js">Hello World in JavaScript</a> </p> |
| </li> |
| <li> |
| <p><a href="#jsinvoke">Trying out a JavaScript script</a> </p> |
| </li> |
| <li> |
| <p><a href="#java">Hello World in Java</a> </p> |
| </li> |
| <li> |
| <p><a href="#context">Writing OpenOffice Scripts and the XScriptContext |
| type</a> </p> |
| </li> |
| <li> |
| <p><a href="#tips">Tips on writing OpenOffice scripts</a> </p> |
| </li> |
| <li> |
| <p><a href="#dtd">Parcel Descriptor DTD and sample XML</a> </p> |
| </li> |
| </ul> |
| <a name="bsh"></a> |
| <h2>Hello World in BeanShell</h2> |
| Here's a BeanShell script that inserts Hello World at the start of an |
| OpenOffice Writer document: |
| <p> </p> |
| <pre> |
| import com.sun.star.frame.XModel; |
| import com.sun.star.text.*; |
| import com.sun.star.uno.UnoRuntime; |
| import drafts.com.sun.star.script.provider.XScriptContext; |
| |
| model = context.getDocument(); |
| textdoc = (XTextDocument) |
| UnoRuntime.queryInterface(XTextDocument.class, model); |
| |
| oText = textdoc.getText(); |
| oCursor = oText.createTextCursor(); |
| oText.insertString(oCursor, "Hello World", false) |
| </pre> |
| <a href="#top">Top</a> <a name="bshinvoke"></a> |
| <h2>Trying out your BeanShell script</h2> |
| Trying out your Hello World BeanShell script is easy: |
| <ul> |
| <li>Start OpenOffice and open a new Writer document. </li> |
| <li>Select the Tools/Configure... menu item. </li> |
| <li>Select the menu tab. In the Category section select |
| OpenOffice Scripts/share/Java/selector |
| <li>In the Function list select ScriptSelector.showOrganizer |
| <li>Now click the New button to create a menu item for this script. You can |
| rename the menu item by clicking on it in the Menu entries list, and |
| move it around the menu hierarchy using the arrow buttons. |
| <li>Click OK to apply your change |
| <li>Select your new menu item |
| <li>A Script dialog appears, browse to a BeanShell script |
| e.g. Root/share/BeanShell/Highlight/highlighter.bsh and click Edit. |
| <li>A BeanShell Debugger window will appear. Click Clear to clear the window |
| and copy in the text of your Hello World example |
| <br><div style="text-align: center;"><img src="beanshell.gif" title="" |
| alt="" style="width: 477px; height: 319px;"><br></div> |
| </li> |
| <li>Now click on the Run button. |
| <li>You should see Hello World appear at the start of the Writer document. |
| <li>Click Close so that the highlighter.bsh script is not overwritten |
| </ul> |
| |
| <p> |
| If you are new to the OpenOffice API this is a great way to experiment |
| with it. </p> |
| <p> When you are happy with your BeanShell script, you can create a |
| Script Parcel which can be deployed to OpenOffice installations or |
| documents for use by others. This can be done <a |
| href="netbeans-devguide.html">using NetBeans</a> or <a |
| href="commandline-devguide.html">from the command line</a>. </p> |
| <p> |
| <a href="#top">Top</a> |
| |
| <a name="js"> |
| <h2>Hello World in JavaScript</h2> |
| </a> Here's a JavaScript script that inserts Hello World at the start of |
| an OpenOffice Writer document: </p> |
| <pre> |
| importClass(Packages.com.sun.star.uno.UnoRuntime); |
| importClass(Packages.com.sun.star.text.XTextDocument); |
| |
| var oModel = XSCRIPTCONTEXT.getDocument(); |
| var oTextdoc = UnoRuntime.queryInterface(XTextDocument, oModel); |
| var oText = oTextdoc.getText(); |
| var oCursor = oText.createTextCursor(); |
| |
| oText.insertString(oCursor, "Hello World", false); |
| </pre> |
| |
| <p> The XSCRIPTCONTEXT variable above is a global instance of the |
| XScriptContext type which is available to all JavaScript scripts |
| executed by the Scripting Framework. See <a href="#context">Writing |
| OpenOffice Scripts and the XScriptContext type</a> for the methods available |
| for the XScriptContext type. </p> |
| <p> <a href="#top">Top</a> </p> |
| <h2> <a name="jsinvoke"> Trying out a JavaScript script in |
| OpenOffice </a></h2> |
| Once again you can use the Edit/Debug Scripts dialog to open a |
| JavaScript script in an editor. The Rhino JavaScript Editor from the <a |
| href="https://developer.mozilla.org/en-US/docs/Mozilla/Projects/Rhino">Mozilla Rhino project</a> can be used |
| to debug and test your JavaScript scripts. |
| <ul> |
| <li>Create a menu item for the Script dialog as described in the |
| BeanShell instructions above |
| <li>Open the Script dialog, navigate to |
| Root/share/JavaScript/ExportSheetsToHTML/exportsheetstohtml.hs and |
| click edit.</li> |
| <li>A Rhino Debugger window will appear. Delete the text in the window and |
| paste in the Hello World code |
| <br><div style="text-align: center;"><img src="rhino.gif" title="" |
| alt="" style="width: 640px; height: 646px;"><br> </div> |
| </li> |
| <li>To run the script select File/Run and then click on the Go button. |
| </ul> |
| <p> The Rhino Debugger also includes debugging functionality, so you can |
| set breakpoints in your JavaScript script and step through the code as |
| it is executed. </p> |
| <p> |
| <a href="#top">Top</a> |
| |
| <a name="java"></a> </p> |
| <h2>Hello World in Java</h2> |
| Here's the Hello World script in Java: |
| <p> <font face="Courier, monospace" size="2"> |
| <pre> import com.sun.star.frame.XModel; |
| import com.sun.star.text.*; |
| import com.sun.star.uno.UnoRuntime; |
| import drafts.com.sun.star.script.provider.XScriptContext; |
| |
| public class MyClass { |
| |
| // The script method must be public |
| // It can either be static or non-static |
| |
| public void showForm(XScriptContext xSc) { |
| |
| // getting the text document object |
| XModel xmodel = xSc.getDocument(); |
| |
| XTextDocument xtextdoc = (XTextDocument) |
| UnoRuntime.queryInterface(XTextDocument.class, xmodel); |
| XText xtext = xtextdoc.getText(); |
| XTextCursor xtextcursor = xtext.createTextCursor(); |
| |
| xtext.insertString(xtextcursor, "Hello World", false); |
| } |
| } |
| </pre> |
| </font> </p> |
| <p> OpenOffice scripts in Java need to be compiled in order to execute them. |
| See the <a href="netbeans-devguide.html">Developing Scripts in NetBeans</a> |
| and <a href="commandline-devguide.html">Developing Scripts on the |
| command line</a> guides for instructions on how to compile and deploy |
| OpenOffice scripts in Java. </p> |
| <p> <a href="#top">Top</a> <a name="context"></a> </p> |
| <h2>Writing OpenOffice scripts and the XScriptContext type</h2> |
| The XScriptContext type is used to obtain the the document context, |
| desktop and component factory from an OpenOffice script. Any public Java |
| method which accepts XScriptContext as it's first parameter can be |
| executed as an OpenOffice script. For BeanShell scripts, an instance of |
| XScriptContext is available in a global variable called "context" which |
| can be used by the script. |
| <p> The following accessor methods are available on the XScriptContext |
| type: </p> |
| <ul> |
| <li>Current document - access the document context against which the |
| script was invoked |
| <p> <font face="Courier, monospace" size="2"> <XScriptContext |
| Instance>.getDocument()</font> <br> |
| returns <font face="Courier, monospace" size="2">::com::sun::star::frame::XModel</font> </p> |
| </li> |
| <li>OpenOffice Desktop - access the desktop of the running OpenOffice |
| <p> <font face="Courier, monospace" size="2"> <XScriptContext |
| Instance>.getDesktop()</font> <br> |
| returns <font face="Courier, monospace" size="2"> |
| ::com::sun::star::frame::XDesktop</font> </p> |
| </li> |
| <li>Component Factory - access a ComponentContext factory to create |
| other UNO components as required |
| <p> <font face="Courier, monospace" size="2"> <XScriptContext |
| Instance>.getComponentContext()</font> <br> |
| returns <font face="Courier, monospace" size="2"> |
| ::com::sun::star::uno::XComponentContext</font> </p> |
| </li> |
| </ul> |
| The Java or BeanShell script must import the XScriptContext interface, |
| using the following import directive: <font face="Courier, monospace" |
| size="2"> |
| <pre> import drafts.com.sun.star.script.provider.XScriptContext;<br></pre> |
| </font> |
| <p> <a href="#top">Top</a> <a name="tips"></a> </p> |
| <h2>Tips on writing OpenOffice scripts</h2> |
| <ul> |
| <li> |
| <p><b>Performance:</b> Currently scripts are being loaded by the |
| Scripting Framework each time they are run. As such it is important to |
| keep the size of your scripts and any dependent jar files they are using |
| reasonably small. In future releases this script loading will be |
| optimised by changing the point at which the scripts are loaded by |
| OpenOffice and using various caching schemes once they are loaded. |
| However, the initial load will always be effected by the script and |
| it's dependent jar/class file sizes. </p> |
| </li> |
| <li> |
| <p><b>Threading:</b> Scripts are run synchronously by the Scripting |
| Framework. If you wish to perform any background task or provide some |
| user interaction via a dialog for instance, then it is your |
| responsibility to spawn a thread in the running script which can manage |
| this process or interaction and let the script return promptly. Within |
| this running thread you should follow the normal UNO component |
| threading guidelines to ensure that they do not deadlock OpenOffice |
| through inappropriate use of the UNO API. </p> |
| </li> |
| </ul> |
| <a href="#top">Top</a> <a name="dtd"></a> |
| <h2>Parcel Descriptor DTD and sample XML</h2> |
| Each Script Parcel must contain a parcel-descriptor.xml file which provides |
| all the necessary metadata for the script. The DTD for the |
| parcel-descriptor.xml follows: |
| |
| <pre> |
| <?xml version="1.0" encoding="UTF-8"?> |
| <!-- DTD for Parcel Meta data for use in the OpenOffice Scripting Framework Project --> |
| |
| <!ELEMENT description (#PCDATA)> |
| <!ELEMENT displayname EMPTY> |
| <!ELEMENT functionname EMPTY> |
| <!ELEMENT prop EMPTY> |
| <!ELEMENT languagedepprops (prop+)> |
| <!ELEMENT script (description, displayname, functionname, languagedepprops*)> |
| <!ELEMENT parcel (script+)> |
| <!ATTLIST displayname |
| value CDATA #REQUIRED |
| > |
| <!ATTLIST locale |
| lang CDATA #REQUIRED |
| > |
| <!ATTLIST functionname |
| value CDATA #REQUIRED |
| > |
| <!ATTLIST prop |
| name CDATA #REQUIRED |
| value CDATA #REQUIRED |
| > |
| <!ATTLIST script |
| language CDATA #REQUIRED |
| > |
| <!ATTLIST parcel |
| language CDATA #REQUIRED |
| > |
| </pre> |
| |
| <p> |
| |
| The following is an example of a parcel-descriptor.xml file that |
| defines a script, implemented in Java. The languagedepprops element is |
| used to extend the JVM's classpath. |
| |
| <pre> |
| <?xml version="1.0" encoding="UTF-8"?> |
| <!--Sample Meta Data for use with the Scripting Framework Project in OpenOffice --> |
| <!DOCTYPE parcel SYSTEM "parcel.dtd"> |
| |
| <parcel language="Java"> |
| <script language="Java"> |
| <displayname value="Memory.usage"/> |
| <description> |
| Displays the memory current memory usage |
| </description> |
| <functionname value="memoryUtils.memoryUsage"/> |
| <languagedepprops> |
| <prop name="classpath" value="/opt/foo.jar:/usr/java/src.jar"/> |
| </languagedepprops> |
| </script> |
| </parcel> |
| </pre> |
| |
| <a href="#top">Top</a> |
| </body> |
| </html> |
