When you write a macro within libreOffice, you will quickly realise something. It’s not really convenient to execute macros through the Macro Manager. This is because you need to access that menu, and it takes a few clicks to do so. (Quickest way to access the APSO Macro manager being [Alt] + [Shift] + [F11]). Creating a button on your spreadsheet is easy. You can assign this button to your macro. When you click on the button, it will execute the macro.
So first we’ll Switch to Design Mode. This allows us to create a button on the spreadsheet. Then, we’ll assign the python macro to this button.

Switch to Design Mode: (Back to Top)

The first step is to set the document to ‘Design Mode’ . Select ‘Design Mode’ From ‘Menu Tools/Forms/Design Mode’.

Create a button: (Back to Top)
Then simply by clicking on Menu ‘Insert>Form Controls>Push Button’:

Once you have the little cross to insert the button, click for the button’s upper left corner. Then hold and release where you want the bottom right corner of the button.

Assign the python macro: (Back to Top)
Once you have the button displayed, right click on it and select ‘Control…’

Then in the window ‘Properties’ select the ‘Events’ tab, scroll down a bit to find in the list of events the one called ‘Mouse button pressed’. On the right of this ‘Mouse button pressed’ entry click on the button ‘[…]’.

A window named “Assign Action’ pops up, click on the button ‘[Macro]’ on the right hand side of this window.

You should then get the ‘Macro Selector’ with your Macro Libraries. Simply go to the library where your macro is saved and select the macro ‘HelloWorld’,then press ‘OK’.

Then ‘OK’ again in ‘Assign Macro’ window, than close the ‘Properties’ window.
The last thing to do is exit the ‘Design’ mode. This allows you to click on the button. Do that by going to ‘Tools>Forms>Design Mode’.

And now when you click on the button… tada…
If you get this ERROR!

The function HelloWorld requires all information from LibreOffice Context to work. This information is needed in the form of an argument. So we need to pass the argument ‘*args’ in your function called by the Push Button.
For example in the program HelloWorld done in a previous post, in your code instead of:
def HelloWorld():
You should have:
def HelloWorld(*args):
Save your program again and then when you press on the button the cell A1 will display ‘Hello World!’ !!!

So there is the final version of the macro:

# Created by Gweno 16/08/2019 for tutolibro.tech
# This program displays 'Hello World!" in cell A1 of the 
# current Calc document.

def HelloWorld(*args):
    """Write 'Hello World!' in Cell A1"""
    
# get the doc from the scripting context 
# which is made available to all scripts
    desktop = XSCRIPTCONTEXT.getDesktop()
    model = desktop.getCurrentComponent()
    
# access the active sheet
    active_sheet = model.CurrentController.ActiveSheet

# write 'Hello World' in A1
    active_sheet.getCellRangeByName("A1").String = "Hello World!"

You can clone or download this code from gitHub here.

Good luck! and leave a comment if you are having problem to have this macro to work.

If you like this tutorial, you could buy me a coffee to help me continue writing add-free tutorials.

Thank you!

In this Part 1 of LibreOffice Calc & Python programming tutorial we are looking at:

• some Software you need
• the APSO extension that’ll make things much easier
• an extra step for Linux users
• useful documentation
• further notes

Software

LibreOffice

You will of course need LibreOffice, you can download the latest version here.
LibreOffice is normally shipped with a PyUNO bridge. This allows it to bind its components with the Python language. It also makes it possible to program LibreOffice with Python. (see at end of this article if you’re using a Linux ).

Python 3

You also need the Python 3 programming language on your computer.
It may be installed already. For now I let you do it yourself, but I might write a quick help later. Just web search for ‘python 3’ for your Operating system.

IDE / Text Editor

You will also need a text editor or even better an IDE (Integrated Development Environment) to write your python program. The advantage of an IDE versus a simple text editor is that it offers tools to organise your codes, an IDE can also makes it easier to spot errors and offers all sort of features to speed up and ease coding like word auto-completion, search and replace.
If you are a programmer you may already have a preference for a simple editor or a clever one. I am using a free open-source IDE called geany, but other popular ones are Eclipse, code::block and the famous Microsoft Visual Studio. They all have their pros and cons, here is the Top 20 of the most popular ones. Geany is perfect for ‘small jobs’ like we are going to do, but again it’s also fine to use a text editor like notepad.

JRE install

If your computer does not have Java Runtime Environment already you will need to install it through the Oracle website. You can also follow instruction here. JRE is indeed required to be able to use macros within LibreOffice.

APSO extension

By default LibreOffice Python Macros are independent from any LibreOffice file. So to execute a python program within a LibreOffice Calc Spreadsheet for example you would need to go in Tools/Macro/Run Macro and select the python program from a list corresponding to a folder on your Hard drive. And this list, for example ‘MyMacro’, would be accessible for any LibreOffice file (Calc, Text, Base, etc…). This is great but not helpful when you want a particular python program to be used specifically for a particular file.
APSO is a LibreOffice extension that helps with organising Python Macros within your LibreOffice files. You just need to download the APSO extension here and then install the tool via Tools/Extensions Manager. One great advantage of APSO is its EditorKicker that you can set up to use your preferred text editor or IDE to edit your Python program.
One last note about using APSO, although the programs themselves are saved in the same folders than all other programs, the ones you choose to be embed in a particular file will be linked to that file, or rather for example LibreOffice calc file will have a link to the python program in its parameters and you will be able to see your program attached to LibreOffice documents currently opened.

Extra step for linux

I had to do one extra step when I was using LibreOffice 5 under Linux mint Operating System: adding some library. Without it it was not possible to do any Python macros within LibreOffice. This is an easy step, just open a terminal, type and execute:

sudo apt-get install libreoffice-script-provider-python

It will be the same for Ubuntu. For other linux distro you will need to check yourself but it’d be similar using the in-house package manager.

Documentation

It is not easy to find helpful documentation for programming Python Macros for LibreOffice. Firstly it’s hard to find a site or forum that have real documentation about using Python for LibreOffice, and secondly the tasks explained are usually too complicated for a beginner. However this is the best place I found so far with a list of links to Python program examples. You will not that most of the examples are using a Python library created by ‘Danny’.

Further notes

In my tutorial we will create everything from scratch and develop simple and useful functions.
I still haven’t decided what topic to cover to illustrate this tutorial. I am hesitating between continuing the time schedule, starting invoice manager or a garden planner.
If you have any preference please let me know in your comment.

If you like this tutorial, you could buy me a coffee to help me continue writing add-free tutorials.

Thank you!

This article helps you decide whether to embed your python macro in the file. It also explores saving it in a macro repository.

With the APSO add-on (see previous article) you can embed your macro within the LibreOffice File. This can be useful for example when you want to send your LibreOffice file with the Python Macro. A downside is that the Python macro will not be accessible outside of the LibreOffice file you sent. So you will need to open the LibreOffice file. Then open the Python Macro organiser. This is necessary to edit the Python program.

There are alternatives to embedding the Python program. You can place it in an organized directory while still using APSO. This lets you re-use it for any other LibreOffice document. You can also edit the program without opening the LibreOffice document if you open it from the relevant folder. If you want to send your LibreOffice Document to someone, there is a trade-off. You will also need to send the Python macro.

I am in favor of keeping programs in a tidy manner. This approach allows me to re-use them across many different files. But the choice is entirely up to you. I hope

To illustrate these 2 cases, let’s have a look at an example:

I have a file called “HelloWorld.ods” and two Python files: the first one is called “HelloWorld.py” and the other file is called “Testing.py”. The first python file is embedded in the LibreOffice file, the second is in the shared Python Scripts directory.

In the first case scenario, after opening HelloWorld.ods, I can go to the Python Script Organizer, in Tools>Macro>Organize Python Scripts (shortcut Alt+Shift+F11) from the APSO extension. Alternatively I can use the LibreOffice Standard Macro Organiser in Tools>Macro>Organise Macros>Python….

In the Python Scripts Organiser you will see that your Python Macro is listed within the LibreOffice File’s name.

When you choose to edit the Python Macro, select ‘Menu>Edit’ from the ‘Python scripts’ window. The edited file’s path is temporary. It is only used for the time of editing this Python program.

So where is the Python Script saved on your hard drive?
As I wrote earlier, it’s embedded in the LibreOffice File. If you don’t believe me, here is a trick to find out:
If I rename my ‘HelloWorld.ods’ in ‘HelloWorld.zip’. I can then unzip it to see the archived compressed files and folders that constitute the LibreOffice file itself(with e.g. Archive Manager on Linux, winzip on Windows, or Archive Utility on Mac). In the list of folders, I spot a folder called ‘Scripts’. Then, I find a sub-folder called ‘python’. OH SURPRISE! The python script is there!

If you want to do that too, when you’re done don’t forget to rename the file back with its ‘.ods’ extension.

In the second case scenario,we are saving our Python script our Python script ‘Testing.py’ is not listed in the Macro manager within the LibreOffice File, but this time I created it as part of my Library ‘MyPythonLibrary’ within another Library called ‘Tutorial’.

And this time if I edit ‘Testing’, I can see the path is not a temporary one. I can access it even when LibreOffice is closed.

In fact your Python programs can be directly accessed on your computer at the following location:
For Linux:
/home/<user name>/.config/libreoffice/4/user/Scripts/python
(to see folder ‘.config’ you need to ‘Show hidden files’ , the shortcut CTRL+h).
For Windows:
C:\Users\<user_name>\AppData\Roaming\LibreOffice\4\Scripts\python
For Mac:
(I think it’s)/Users/<user name>/Library/Application Support/LibreOffice/4/user\Scripts\python
(Please let me know in a comment if you know for sure what the folder is for Mac OS).

Time for your First LibreOffice line of code!

I know you can’t wait anymore! So let’s create our first program in Python in a LibreOffice Calc Document in this next post.

If you like this tutorial, you could buy me a coffee to help me continue writing add-free tutorials.

Thank you!

# Created by Gweno 16/08/2019 for tutolibro.org
# This program displays 'Hello World!" in cell A1 of the 
# current Calc document.

# get the doc from the scripting context 
# which is made available to all scripts
desktop = XSCRIPTCONTEXT.getDesktop()
model = desktop.getCurrentComponent()

def HelloWorld():
    """Write 'Hello World!' in Cell A1"""

    # access the active sheet
    active_sheet = model.CurrentController.ActiveSheet

    # write 'Hello World' in A1
    active_sheet.getCellRangeByName("A1").String = "Hello World!"

You can either copy this block of code above or better type it yourself. Typing the code yourself will take longer but it’s the best way to remember a new language.

The first lines starting with ‘#’ are comments.
A comment in a program is a line that is not processed when the program is executed. It helps the person reading the program to understand what the code is doing. Most of the time, this person is yourself. Comments will help you remember what you were trying to achieve with this code.

The blank space at the start of indented lines should be made of 4 spaces:
    active_sheet = model.CurrentController.ActiveSheet

If you don’t do that it will create an error because the Python interpreter will not recognise the line as being part of the function define by:
def HelloWorld():

The instruction ‘def’ is to ‘define a function’. A function is a set of written instructions. It can be run on its own. It can also be ‘called’ by other functions to be executed.
Our function here is called ‘HelloWorld’. The part between parenthesis ‘()’ is where you write the arguments to be used by the function. In our case we are not ‘passing’ any argument to the function ‘HelloWorld’ for now. That’s why we have nothing within the parenthesis ‘()’.
If you want to assign this macro to a button, you need to pass a specific argument. This argument is necessary for the macro to work when pressing the button. (see this post explains how to assign a button to a python macro)

Explanations:
Lines 1,2,3,5,6: these lines start with a ‘#’ so they are comments.
Lines 4,9,18: these empty lines are only for making the program easier to read. They serve to separate the different sets of instructions within the program. The Python interpreter does not need them but these empty lines make the code more readable for us.

Line 7:
desktop = XSCRIPTCONTEXT.getDesktop()
This line is what allows us to use Python language to manipulate LibreOffice’s components. It is a bit complicated to explain exactly what this line does. In short, we define ‘desktop’ to hold the ‘XSCRIPTCONTEXT‘ interface provided by LibreOffice for our scripts (programs). The ‘getDesktop()’ function is used to obtain a reference for our scripts to operate on. (It is not a reference to a computer desktop!). (Click on the links above to read more in my ‘bitesize’ section).

Line 8:
model = desktop.getCurrentComponent()
Here, we define ‘model’ to be the current component of ‘desktop’. Thus, we are referencing the current document open. It should be a Calc document.

Line 10:
def HelloWorld():
Define a new function called ‘HelloWorld’ that has no arguments.
The ‘:’ at the end is essential, it’s to say that what is following is the actual code written for this function. And every line that follow this function’s 1st line should start with 4 spaces.
The function finishes when there is no lines after it. Or when the next non empty line is not a comment and starts with no space.
Line 11:
“””Write ‘Hello World!’ in Cell A1″””
This line is simply a description of the function. Also called a Docstring (DocStrings is short for Documentation Strings), it starts and ends with 3 quotation marks. It is not really useful for us right now. Still, it is good practice to have a short description for each of your functions. It’s different from a comment because this description can be displayed outside of the program as a ‘help’ note.
To display docstrings, you can use the built-in function ‘help’, like illustrated in the APSO console below:

Line 14:
    active_sheet = model.CurrentController.ActiveSheet
Here we are defining ‘active_sheet’ to be the current spreadsheet you are looking at.
Line 17:
    active_sheet.getCellRangeByName("A1").String = "Hello World!"
Finally! Now we have a reference to the current LibreOffice Context. We have the current LibreOffice Calc Document (component) and the current spreadsheet. Therefore, we can access the cell ‘A1’. We can then assign to its ‘String’ parameter the text “Hello World!

Exercise:
Add to function HelloWorld a line of code to display “Bye Bye World!” in cell ‘B2’. I am sure you can handle that!

If you like this tutorial, you could buy me a coffee to help me continue writing add-free tutorials.

Thank you!

Here is the plan for this part 2 of the tutorial:

• Get your workflow right: deciding between your macro embedded in the file or saved in a macro repository.
• First line of code and writing “Hello World!” in Cell A1.
• Assigning the macro to a LibreOffice Control Button.

Get your workflow right (Back to top)

With the APSO add-on (see previous article) you can embed your macro within the LibreOffice File. This can be useful when you want to send your file with the Python Macro. One downside if you do that is that the Python macro is not accessible outside of the LibreOffice file. So you’ll need to open the LibreOffice file and open the Python Macro organiser in order to edit the Python program. There are alternatives to embedding the Python program. You can place it in an organized directory while still using APSO. This allows you to re-use it for any other LibreOffice document. You can also edit the program without opening the LibreOffice document if you open it from the relevant folder. If you want to send your LibreOffice Document to someone, there is a trade-off. You will also need to send the Python macro.

I am in favor of keeping my programs in a tidy manner. This approach allows me to re-use them across many different files. However, the choice is entirely up to you.

To illustrate these 2 cases, let’s have a look at an example:

I have a file called “HelloWorld.ods” and two Python files: the first one is called “HelloWorld.py” and the other file is called “Testing.py”. The first python file is embedded in the LibreOffice file, the second is in the shared Python Scripts directory.

In the first case scenario, after opening HelloWorld.ods, I can go to the Python Script Organizer, in Tools>Macro>Organize Python Scripts (shortcut Alt+Shift+F11) from the APSO extension. Alternatively I can use the LibreOffice Standard Macro Organiser in Tools>Macro>Organise Macros>Python….

In the Python Scripts Organiser you will see that your Python Macro is listed within the LibreOffice File’s name.

When you choose to edit the Python Macro, select ‘Menu>Edit’ from the ‘Python scripts’ window. The edited file’s path is temporary. It is only used for the time of editing this Python program.

So where is the Python Script saved on your hard drive?
As I wrote earlier, it’s embedded in the LibreOffice File. If you don’t believe me, here is a trick to find out:
If I rename my ‘HelloWorld.ods’ in ‘HelloWorld.zip’ I can then unzip it to see the archived compressed files and folders that constitute the LibreOffice file itself (with e.g. Archive Manager on Linux, winzip on Windows, or Archive Utility on Mac). In the list of folders I can then spot a folder called ‘Scripts’, then a sub-folder called ‘python’, and OH SURPRISE! the python script is there!

If you want to do that too, when you’re done don’t forget to rename the file back with its ‘.ods’ extension.

In the second case scenario,we are saving our Python script our Python script ‘Testing.py’ is not listed in the Macro manager within the LibreOffice File, but this time I created it as part of my Library ‘MyPythonLibrary’ within another Library called ‘Tutorial’.

And this time if I edit ‘Testing’, I can see the path is not a temporary one and I can access it even when LibreOffice is closed.

In fact your Python programs can be directly accessed on your computer at the following location:
For Linux:
/home/<user name>/.config/libreoffice/4/user/Scripts/python
(to see folder ‘.config’ you need to ‘Show hidden files’ , the shortcut CTRL+h).
For Windows:
C:\Users\<user_name>\AppData\Roaming\LibreOffice\4\Scripts\python
For Mac:
(I think it’s)/Users/<user name>/Library/Application Support/LibreOffice/4/user\Scripts\python
(Please let me know in a comment if you know for sure what the folder is for Mac OS).

First line of code! (Back to top)

I know you can’t wait anymore! So let’s write our first line of code in Python, within a LibreOffice Calc Document.

So after creating a new Calc document, go in the Macro manager (if you have installed the APSO extension: ALT+Shift+F11), then as explained earlier in this lesson you can have your program either in calc document or in a library outside the document. To do so, choose between ‘My Macros’, ‘LibreOffice Macros’ or the name of the document itself.
I do prefer saving my python macros in the ‘My Macros’ Library.
You can also create sub-folders, called libraries, or directly create your program by choosing ‘Create Module’ in the ‘Menu’.

So go ahead and create a Module, name it “HelloWorld”, then once the module is listed and selected, click again on ‘Menu’ and choose ‘edit’.

And then you get either a default editor or the one you have linked with APSO to pop up with a new program that content nothing but a couple of lines like these:

The first line is a comment.
A comment in a program is a line that is not processed when the program is executed. So it’s not a line of code, it is usually to help the person who is going to read your program (most of the time, yourself) to understand what the following code is aiming to do.
So to write comments in your Python programs simply add a ‘#’ at the start of the line.
Don’t worry about the second line, in fact you can delete these two lines for now.
Instead you could like me write your name, the date and what the program is for:

# Created by Gweno 16/08/2019 for tutolibro.tech
# This program displays 'Hello World!" in cell A1 of the
# current Calc document.

Then Finally here is the code for writing “Hello World!” in cell A1:

# Created by Gweno 16/08/2019 for tutolibro.tech
# This program displays 'Hello World!" in cell A1 of the 
# current Calc document.

def HelloWorld():
    """Write 'Hello World!' in Cell A1"""

# get the doc from the scripting context
# which is made available to all scripts
    desktop = XSCRIPTCONTEXT.getDesktop()
    model = desktop.getCurrentComponent()

# access the active sheet
    active_sheet = model.CurrentController.ActiveSheet

# write 'Hello World' in A1
    active_sheet.getCellRangeByName("A1").String = "Hello World!"

You can either copy this block of code above or better type it manually yourself. Typing the code yourself will take longer but it’s the best way to remember a new language.
When you type it make sure that you leave 4 empty spaces to indent the lines that are not starting at the beginning of their lines, like:
desktop = XSCRIPTCONTEXT.getDesktop()
If you don’t do that it will create an error because the Python interpreter will not recognise the line as part of the function define by:
def HelloWorld():
So the instruction ‘def’ is to ‘define a function’. A function is a set of written instructions that can be run on its own or ‘called’ by other functions to be executed.
Our function here is called ‘HelloWorld’ and the part between parenthesis ‘()’ is where you write the arguments to be used by the function. In our case we are not ‘passing’ any argument to the function ‘HelloWorld’ for now, that is why we have nothing within the parenthesis ‘()’.
You need to know that when we will assign our macro to a button we will need to pass a specific argument for our macro to work when we press the button.

Explanations:
Lines 1,2,3,8,9,13,16: these lines start with a ‘#’ so they are comments.
Lines 4,7,12,15,18: these empty lines are only for making the program easier to read,by separating the different set of instructions within the program. The Python interpreter does not need them but these empty lines make the code more readable for us.
Line 5:
def HelloWorld():
Define a new function called ‘HelloWorld’ that has no arguments.
The ‘:’ at the end is essential, it’s to say that what is following is the actual code written for this function. And every line that follow this function’s 1st line should start with 4 spaces.
The function finishes when either there is nothing after, or when a new line starts from the beginning with no space to start with (excluding comment lines).
Line 6:
"""Write 'Hello World!' in Cell A1"""
This line is simply a description of the function, it starts and ends with 3 quotation marks. It is not really useful for us right now but it is a good practice to have a short description for each of your function. It’s different from a comment because this description can be displayed from outside of the program as a ‘help’ note.
Line 10:
desktop = XSCRIPTCONTEXT.getDesktop()
This line is what allows us to use Python language to manipulate LibreOffice’s components. It is a bit complicated to explained exactly what this line does but in short:
We define ‘desktop’ to hold the ‘XSCRIPTCONTEXT‘ interface provided by LibreOffice for our scripts (programs). The ‘getDesktop()’ function is used to obtain a reference for our scripts to operate on. (It is not a reference to a computer desktop!). (Click on the links above to read more in my ‘bitesize’ section)
Line 11:
model = desktop.getCurrentComponent()
In the same way we define here ‘model’ to be the current component of ‘desktop’, so effectively we are referencing to the current document open, which should be a Calc document.
Line 14:
active_sheet = model.CurrentController.ActiveSheet
Here we are defining ‘active_sheet’ to be the current spreadsheet you are looking at.
Line 17:
active_sheet.getCellRangeByName("A1").String = "Hello World!"
Finally! Now that we have a reference to the current LibreOffice Context, the current LibreOffice Calc Document (component) and the current spreadsheet, we can access the cell ‘A1’ from that current spreadsheet and assign to its ‘String’ parameter the text “Hello World!”.

Exercise:
Add to function HelloWorld a line of code to display “Bye Bye World!” in cell ‘B2’. I am sure you can handle that!

Assign the macro to a LibreOffice Control Button. (Back to top)

You will quickly realise when you write a macro within libreOffice that it’s not really convenient to execute them through the Macro Manager because you need to access that menu and it takes a few clicks to do so (Quickest way to access the APSO Macro manager being [Alt] + [Shift] + [F11]). It is easy to create a button on your spreadsheet and to assign it to your macro and then when you’ll click on that button it will execute the macro.
So first we’ll create a button on the spreadsheet then we’ll assign the python macro to this button.

Create a button:
Simply by clicking on Menu ‘Insert>Form Controls>Push Button’:

Then once you have the little cross to insert the button, just click for upper left corner of the button, then hold and release where you want the bottom right corner of the button.

Assign the python macro:
Once you have the button displayed, right click on it and select ‘Control…’

Then in the window ‘Properties’ select the ‘Events’ tab, scroll down a bit to find in the list of events the one called ‘Mouse button pressed’. On the right of this ‘Mouse button pressed’ entry click on the button ‘[…]’.

A window named “Assign Action’ pops up, click on the button ‘[Macro]’ on the right hand side of this window.

You should then get the ‘Macro Selector’ with your Macro Libraries. Simply go to the library where your macro is saved and select the macro ‘HelloWorld’,then press ‘OK’.

Then ‘OK’ again in ‘Assign Macro’ window, than close the ‘Properties’ window.
Last thing to do is to come out the ‘Design’ mode to be able to click on the button, do that by going to ‘Tools>Forms>Design Mode’.

And now when you click on the button… tada…
ERROR!

This is because to be able to work, the function HelloWorld need all information from LibreOffice Context in the form of an argument. So we need to pass the argument ‘*args’ in our function HelloWorld. So in your code in line 5 instead of:
def HelloWorld():
You should have:
def HelloWorld(*args):
Save your program again and then when you press on the button the cell A1 will display ‘Hello World!’ !!!

So there is the final version of the macro:

# Created by Gweno 16/08/2019 for tutolibro.tech
# This program displays 'Hello World!" in cell A1 of the 
# current Calc document.

def HelloWorld(*args):
    """Write 'Hello World!' in Cell A1"""
    
# get the doc from the scripting context 
# which is made available to all scripts
    desktop = XSCRIPTCONTEXT.getDesktop()
    model = desktop.getCurrentComponent()
    
# access the active sheet
    active_sheet = model.CurrentController.ActiveSheet

# write 'Hello World' in A1
    active_sheet.getCellRangeByName("A1").String = "Hello World!"

You can clone or download this code from gitHub here.

Good luck! and leave a comment if you are having problem to have this macro to work.

If you like this tutorial, you could buy me a coffee to help me continue writing add-free tutorials.

Thank you!

# Created by Gweno 24/10/2025
# For tutolibro.org
# Public Domain, feel free to copy, modify, use in your own scripts
# 
# email: gweno@tutolibro.org

# This needs to be run from any instance of LibreOffice already open

# Python modules to import for this script:
import uno
from com.sun.star.beans import PropertyValue

# UNO service definition for creating document
context = uno.getComponentContext()
service_manager = context.getServiceManager()
    
def create_instance(name, with_context=False):
    if with_context:
        instance = service_manager.createInstanceWithContext(name, context)
    else:
        instance = service_manager.createInstance(name)
    return instance

def new_document_from_template(*args):
    desktop = create_instance('com.sun.star.frame.Desktop', True)
    properties = (PropertyValue(Name='AsTemplate', Value=True),)
    # full path to template here
    path = 'file:///usr/lib/libreoffice/share/template/common/officorr/Modern_business_letter_serif.ott'
    doc = desktop.loadComponentFromURL(path, '_default', 0, properties)
    return doc

def main():
    """ Creates a new document from a LibreOffice Temple (*.ott)"""
    
    new_document_from_template()
    
    
if __name__ == "__main__":
    main()

First we need to import the uno library and the specific PropertyValue function

# Python modules to import for this script:
import uno
from com.sun.star.beans import PropertyValue

Then let’s set the couple of service definitions that we need:

# UNO service definition for creating document
context = uno.getComponentContext()
service_manager = context.getServiceManager()

We create 3 functions:

create_instance:

def create_instance(name, with_context=False):
    if with_context:
        instance = service_manager.createInstanceWithContext(name, context)
    else:
        instance = service_manager.createInstance(name)
    return instance

new_document_from_template:

def new_document_from_template(*args):
    desktop = create_instance('com.sun.star.frame.Desktop', True)
    properties = (PropertyValue(Name='AsTemplate', Value=True),)
    # full path to template here
    path = 'file:///usr/lib/libreoffice/share/template/common/officorr/Modern_business_letter_serif.ott'
    doc = desktop.loadComponentFromURL(path, '_default', 0, properties)
    return doc

This function creates the new document itself from an template example within the shared library of LibreOffice.
Note the hard coded path, starting with ‘file://’ followed by the actual path for the file.
You can use your own template file. It doesn’t need to be a file with a ‘. ott’ extension. You can also us a or a regular ‘.odt’ file.
The example below shows the path for a simple odt file in my Templates folder. The new document will be new untitled file, copy of ‘MyDocs.odt’.

path = 'file:///home/gweno/Templates/MyDoc.odt'

I do recommend to use a dedicated template file wit ‘.ott’ for clarity and to be able to use it with the build-in LibreOffice Template management along with Templates features.

Finally, the main function just calls new_document_from_template:

def main():
    """ Creates a new document from a LibreOffice Temple (*.ott)"""
    
    new_document_from_template()

To execute.

Save the full code in a file in your usual python library for LibreOffice scripts to be able to execute this script from any open instance of LibreOffice.

Racers on the starting line:

1. Ronalbeano
2. Harry Cover
3. Brian
4. Milkman
5. War Pig
6. Insert your Name here
7. Jas Favola
8. Melodeon
9. Beans are Cool!
10. Wind Breaker
11. J Bean
12. Your Bean

Racers on the starting line:

1. Bean Bappé
2. Jack & the …
3. It’s Fun to grow a B.E.A.N
4. Mr Bean
5. Bean Where?
6. Jack’O Bean
7. Kyle Bean
8. Valbean
9. Bean Breaker

Podium for the 2024 edition of the Runner Beans Race:

Gold: Valbean
Silver: Mr Bean
Bronze: Bean Bappé

Usually the first statement, when scripting with python to work on a LibreOffice document, would be:
desktop = XSCRIPTCONTEXT.getDesktop()

getDesktop() is a method of the object XSCRIPTCONTEXT and returns the Desktop Reference on which our script can interact with. This reference is the main interface of the Desktop Service.

It allows to access useful methods from the Desktop interface like getCurrentComponent() or getComponents(). The ‘current Component’ being the active document on which you will be able to work directly, for example editing text or cells.

Still hungry?

The getDesktop() method is a method of class ScriptContext and is define in pythonscript.py. You can find pythonscript.py in /lib/libreoffice/program on Linux, probably in a similar path on MacOs and in C:\Program Files\LibreOffice\program on Windows (standard install).

If you like this tutorial, you could buy me a coffee to help me continue writing add-free tutorials.

Thank you!

When you program a script within LibreOffice, accessing the XSCRIPTCONTEXT object is the starting point for controlling LibreOffice documents.

SCRIPTCONTEXT is an object of class ‘pythonscript.ScriptContext’.
This object provides connections with running instances of LibreOffice and has four useful methods:
getDocument ()
getInvocationContext ()
getDesktop ()
getComponentContext ()

Still hungry?

Here pythonscript is the python program that defines the context for Python scripts in . You can find pythonscript.py in /lib/libreoffice/program on Linux, probably in a similar path on MacOs and in C:\Program Files\LibreOffice\program on Windows (standard install).
ScriptContext is a Class inherited from unohelper.base and defined in pythonscript.py.
On linux Mint, unohelper.py is in /lib/python3/dist-packages and MacOS (most likely), and in C:\Program Files\LibreOffice\program on Windows (standard install).
The unohelper.Base itself is a class inherited from XTypeProvider, the latest being imported from com.sun.star.lang and being inherited from XInterface.

If you like this tutorial, you could buy me a coffee to help me continue writing add-free tutorials.

Thank you!