Introduction to OpenOffice.org scripting features : Introduction to OpenOffice.org scripting features Laurent Godard
Agenda : Agenda Context
What is scripting ?
Tools
What does OpenOffice.org provide ?
Scripting OpenOffice.org
Presentation
Basic
Python
Scripting : Scripting Possibility to pilot OpenOffice.org elements for our own needs
Access its API/features by code
This can be done
From a code inside OpenOffice.org : macros
From outside OpenOffice.org : connection line
ooffice "-accept=socket,host=localhost,port=2002;urp;"
setup.xcu
Network connection on localhost and even network
From components deployed at OOo level : Add-ons
Once a connection is set up, scripting is almost the same
Context and definitions : Context and definitions Many languages
Java, C++, COM (VB, delphi), .Net, ...
Language uses OOo API via UNO bridges
Definitions : Definitions API : Application Programming Interface
Access to objects, properties and methods of OOo core
No need to know OOo source code but only the API it exposes
SDK : Software Development Kit
Toolbox dedicated to developers to use OpenOffice.org API and build their programs
UNO : Universal Network Object
Description of objects that allow to communicate with API no matter the localization of objects
The bridges for different languages allow its use in heterogeneous environments
Tools : Tools IDE
Integrated development environment
OOo dialog builder graphical tool
SDK
What does it contains as documentation ?
How to browse it ?
Helpers
What are the coding facilities introduced in scripting languages ?
Useful developments by community
Macro management : Macro management Hierarchical organization
The basic IDE – code : The basic IDE – code Syntax coloration
Step by step debugging tool
Call stack
Variable values and object explorer
The basic IDE – dialogs : The basic IDE – dialogs Build your own dialogs with integrated tools
Complex dialogs : Complex dialogs Paolo Mantovani
IDE for other languages : IDE for other languages Javascript
Beanshell
Nothing for Python, we have to use an external IDE and import the code into OOo
First Macro : First Macro Hello Message
No OOo interaction
Basic language compliant sub HelloMessage
aName = inputBox("What is your name ?")
msgbox "Hello " + aName
end sub
Going deeper : Going deeper Need to access OOo objects to create business helpers inside the office suite
Where to find them ?
The SDK provides many documentation on the API
Developers guide
Related OpenOffice.org projects
http://extensions.openoffice.org
http://api.openoffice.org
http://udk.openoffice.org
http://framework.openoffice.org
The SDK (OOoBasic Use) : The SDK (OOoBasic Use) A deployable archive
http://api.openoffice.org
around 30 Mb (100 Mb installed)
In english
IDL reference
Developers guide
Examples
OpenDocument and OpenOffice.org 1.x file specification
Building tools and Java/C++ reference (not needed for basic)
...
IDL Reference : IDL Reference Synthetic information
For a given service and interface, enumerates all properties and methods it offers
Some comment lines on each
Hyperlink navigation allowing exploration of returned types
Index and navigation pages
Alphabetical
Hyperlink navigation allowing deep exploration
Hyperlinks between IDL reference ans developers guide
Ideal for finding its way in the API
IDL Reference (II) : IDL Reference (II)
Developers Guide : Developers Guide Full documentation on UNO and API
more than 1000 pages
HTML or PDF
Cross hyperlink reference to IDL
Numerous code examples (Java) and UML diagrams
OOoBasic coding simplifications : OOoBasic coding simplifications ThisComponent, StarDesktop
CreateUNOService, CreateUNOStruct
ConvertToURL, convertFromURL
Get and set methods are binded to properties in read and write mode
setString, getString methods to String property
Collections are translated to arrays
getByIndex method calls not needed anymore
Structures and named constant recognized
com.sun.star.beans.PropertyValue
Introspection : dbg_methods, dbg_properties
Xray - OOoBasic : Xray - OOoBasic Navigate recursively into the API, plugged to the IDL B. Marcelly
XRay – SDK binding : XRay – SDK binding http://www.ooomacros.org/dev.php#101416
First OOo API use : First OOo API use Convert a document to PDF sub launchMacro()
call DocumentToPDF("test.odt","test.pdf")
end sub
sub DocumentToPDF(source, destination)
sourceURL = convertToURL(source)
sourceDoc = StarDesktop.loadComponentFromURL(sourceURL, "_blank", _
0, Array())
destinationURL = convertToURL(destination)
dim args(0) as new com.sun.star.beans.PropertyValue
args(0).Name = "FilterName"
args(0).Value = "writer_pdf_export"
sourceDoc.storeToURL(destinationURL,args())
sourceDoc.close(False)
end sub
Packaging as addon : Packaging as addon Can be distributed inside a document but then not integrated to OOo
Definition of an addon
A deployable set of code containing information on its availability and access in OpenOffice.org in a standalone file
Compressed file containing code, resources and configuration – a new filename extension defined : oxt (OOo 2.0.4)
Developers guide chapter 4
Paolo's previous year presentation
http://marketing.openoffice.org/ooocon2005/presentations/thursday_d4.pdf
addons.xcu : addons.xcu OOo GUI integration
XML file containing the toolbar and menu layout of the packaged code
Defines icons resources
Titles and Translations
Associates code to be launched to each interface elements
Toolbar
Main menu and submenus
Tools > Addons submenu
Help menu
Addon tool http://www.ooomacros.org/dev.php#101618
Addon tool : Addon tool B. Marcelly
Deploy to user : Deploy to user Using command line tool unopkg (OOo closed)
/program/unopkg
Package manager
Tools > Package manager
To all users in share directory or only at user level
OOo installation directory share/uno_packages
OpenOffice.org Packages
OOo user directory user/uno_packages
My Packages
Deploy to user : Deploy to user
Access with command lines : Access with command lines Macros can be accessed by launching a command line
Example : automatically export a file to PDF
soffice 'macro:///myLibrary.module.DocumentToPDF
("/home/lgodard/source.odt" ,
"/home/lgodard/result.pdf")'
PyUNO : PyUNO Python bridge to OOo API
Use for macros
Use for external/remote scripting
Deployable as addons
Code simplifications similar to OOoBasic ones
Object oriented so that we can create our own services
By overloading existing ones
Creating a totally new (defining a new IDL)
Simple as OOoBasic, powerful as Java ;)
See Paolo's Mantovani examples
http://www.paolo-mantovani.org/
Python example : Python example HelloWorld python script as a macro def HelloWorldPython( ):
"""Prints the string 'Hello World(in Python)' into the current document"""
#get the doc from the scripting context which is made available to all scripts
model = XSCRIPTCONTEXT.getDocument()
#get the XText interface
text = model.Text
#create an XTextRange at the end of the document
tRange = text.End
#and set the string
tRange.String = "Hello World (in Python)"
return None
PyXRAY : PyXRAY All written in pyUNo using OOo graphical toolkit
Points to the SDK offline and online
http://www.indesko.com/sites/en/downloads/pyxray___a_tool_for/view
Under development, need feed back from pyXray import XrayBox
...
desktop = smgr.createInstanceWithContext( "com.sun.star.frame.Desktop",ctx)
XrayBox(ctx,desktop)
# access the current writer document
model = desktop.getCurrentComponent()
XrayBox(ctx,model)
pyXRAY : pyXRAY
Python for remotely driving OOo : Python for remotely driving OOo Open OOo in listen mode
Command line
/program/soffice "-accept=socket,host=localhost,port=2002;urp;"
Every time
Configuration file /share/registry/data/org/openoffice/Setup.xcu
socket,host=localhost,port=2002;urp;
Host & port allow remote scripting
eg : oooconv
A converter farm on an intranet (XML-RPC and asynchronous using twisted framework)
http://svn.nuxeo.org/trac/pub/browser/OOo/oooconv
Example : doctests : Example : doctests http://blogs.nuxeo.com/sections/blogs/laurent_godard/2006_04_13_testing-pyuno-programs-with-doctests import doctest
import sys
def oooTesting():
r""" Let's define the listening host we have to reach and the port ...
>>> HOST = 'localhost'
>>> PORT = 11111
We now call out helper connecting class:
>>> ooo = OOoTools(HOST, PORT)
>>> ctx = ooo.ctx
>>> desktop = ooo.desktop
So, we are now connected to the listen OpenOffice.org instance
We now start with Calc manipulations by creating a blank spreadsheet file
>>> doc = desktop.loadComponentFromURL("private:factory/scalc",'_blank',0,())
We can verfiy that this new document is really a spreadsheet by checking
the supported OOo service:
>>> doc.supportsService("com.sun.star.sheet.SpreadsheetDocument")
True
The new Calc documents opens on a new blank activesheet we retreive
We also verify that this objetc is really a spreadsheet by checking
the relevant supported services.
>>> sheet = doc.CurrentController.ActiveSheet
>>> sheet.supportsService("com.sun.star.sheet.Spreadsheet")
True
Using UNO services : Using UNO services Overload existing services
Creating your own IDL
Define your own service and callable methods
More advanced use but powerful import uno
import unohelper
class EtatSyntheseJob( unohelper.Base, XJobExecutor ):
def __init__(self, ctx):
def trigger(self, args):
# pythonloader looks for a static g_ImplementationHelper variable
g_ImplementationHelper = unohelper.ImplementationHelper()
g_ImplementationHelper.addImplementation(EtatSyntheseJob, # UNO object class
"myownname.EtatSynthese", # implemenation name
("org.openoffice.pyuno.myownname.EtatSynthese",),) # list of implemented services
PyUNO needs you : PyUNO needs you Version 2.3.5
Following python versions would be great
Need an editor or at least a binding
Enhance addon management allowing several .py files in the extension file
Use pyUNO to create more and more Extensions
Extension project
http://wiki.services.openoffice.org/wiki/Extensions_development_python
More helpers
More documentation & feedback
Conclusion : Conclusion Create your daily business programs or helpers by implementing scripting Extensions
A lot of tools and documentation available
Extensions project and scripting framework
Helps you starting http://wiki.services.openoffice.org/wiki/Extensions
Distribute your useful tools, feel free to contribute
dev@extensions.openoffice.org
A download site is being setup (any help ?)
Tracks to follow at OOoCon 2006
Eg: Development track on wednesday afternoon (Juergen Schmidt about extensions infrastructure and Cedric Bosdonnat about URE for going further)
Thanks : Thanks Illustrations from Ben Bois