Using Python scripting in Collabora Online
This document describes the Python scripting feature to manipulate documents being edited in Collabora Online.
Python scripting allows for document manipulation while being edited in Collabora Online. The use-case assumes a web page has a Collabora Online document instance open in an iframe and that the functionality that wants to access the Python scripting is on the parts of the web page outside that iframe.
Python script files
The Python script files containing functions to be called should be located in the LibreOffice installation, in the folder
(In the LibreOffice sources, they are in
Currently, this folder contains
SetSellColor.py and files that are used by the demo web page
(see below), and a few others. Customer-specific Python files should be placed in the same location. After editing script files, the Collabora Online instance must be restarted.
These server-side scripts are read-only during run-time and cannot be modified via Online. Furthermore, the execution of Python scripting is limited to the Python script files in the aforementioned directory, which are prepared in advance. Arbitrary Python code execution is not possible, nor is the execution of dynamically code generated code. These are to guarantee strong security constraints.
Additional security is provided by not enabling the Python script provider by default. To enable it, you need to explicitly install, from the respective customer or CODE repositories, the following packages:
collaboraofficebasis-python-script-provider, makes it possible to implement
uno“scripts” in python,
collaboraofficebasis-pyuno, makes it possible to implement
unocomponents in python.
In the Online sources there is a web page
browser/html/framed.doc.html that are examples of web pages
that run an unmodified Collabora Online instance inside an HTML
iframe, and then from the HTML code outside the iframe calls Python scripts in the underlying LibreOffice instance to manipulate data in the document open in the Collabora Online instance. Various parameters can be passed to the Python scripts, and return values handled.
are just for demonstration purposes and very bare-bones visually.
The parameter to
postMessage is a stringified JSON object. The interesting fields in that are:
MessageId, which should be
ScriptFile, which should be the file name of the Python source file containing the Python function to be called,
Function which should be the name of the Python function to be called,
Values which should be a JSON object containing the
parameters to that Python function.
receiveMessage() is set up to handle postMessage() events posted to the HTML page from the iframe, and handle especially those corresponding to return values from called Python functions. Those are distinguished by having a
receiveMessage() knows it is handling a return value from a Python script, it checks the
commandName field which contains the LibreOffice
vnd.sun.star.script URL of the called Python function. In the
demonstration framed.html it is
receiveMessage that then directly does what is necessary depending on the function called. In a more real-life use case, this could be done in some more generic and complex manner of course.
These scripts are provided as samples and as starting points for experimentation and further development. Users are encouraged to make copies of them and modify as necessary. Note that they may get overwritten when upgrading the Online packages, so making separate copies is highly recommended to avoid losing any changes.
The first form sets the colour of a cell in the (Calc) document open in the Collabora Online instance. The (zero-based) x and y coordinates of the cell, and the colour (in HTML format, like #A0FFA0 for a very light green) are input fields of the form.
In this case the Python file is called
SetCellColor.py, the function is called
SetCellColor, and the parameters are the x and y coordinates and the colour.
The second form has no input fields and causes the function GetNamedRanges() in the Python file
NamedRanges.py to be called. That function takes no parameter but returns a value that is a list of named ranges in the document. The
receiveMessage() function inserts these into a textarea element.
The third form is used to add a named range to the document. The input fields are as expected, the name and the range. The called Python function is
AddNamedRange, also in
Finally, and simplest sample, is a form to delete a named range.
This script demonstrates inserting a custom text into a Writer document, replacing any selection (if exists), otherwise inserting at the cursor’s position.