Warning!!!!: A lot has changed in
OpenLP and this guide is out dated. Whilst it may provide some value,
don't expect any code based on the page to work. The examples on this
page need updating before they will be functional.
All plugins need to have the same directory structure. The Songs
plugin's directory structure is illustrated below as an example:
Each plugin has a directory within the openlp.org "plugins" directory.
This directory is named the same as the plugin's name. Within the name
directory there will be a nameplugin.py file which contains the
NamePlugin class. This plugin class extends the builtin openlp.org
Plugin class. This provides your plugin with a number of key methods to
All code should follow the Python syntax guidelines, known as
The recommended naming convention for plugins is the plural of the
object it provides (e.g. Songs).
Plugin names should not contain spaces.
Base Plugin Class
The base Plugin class is shown below, with all the hooks that you need
to provide if you want to make use of its functionality.
class Plugin(object): def __init__(self, name=None, version=None): if name is not None: self.name = name else: self.name = 'Plugin' if version is not None: self.version = version self.icon = None self.config = PluginConfig(self.name) self.weight = 0 # Set up logging self.log = logging.getLogger(self.name) def check_pre_conditions(self): return True def get_media_manager_item(self): pass def add_import_menu_item(self, import_menu): pass def add_export_menu_item(self, export_menu): pass def get_settings_tab(self): pass def add_to_menu(self, menubar): pass def handle_event(self, event): pass def about(self): pass def save(self, data): pass def load(self, string): pass def render(self, theme, screen=None): pass def initalise(self): pass
Developing An Example Plugin
Starting The Plugin
So let's start by building a very basic plugin, one that will add an
item to the media manager, which will have a toolbar, and one button on
the toolbar that pops up a "Hello World" message (we had to get the
"Hello World" in *somewhere* ;-) ).
First create a directory in the plugins directory. Let's call it
Create a __init__.py file in that directory. This converts the
directory into a Python module, so that openlp.org can load your
Create a file named helloworldplugin.py.
The Plugin Code
Next we'll need some code in that new plugin file. Copy and paste the
following code into the new file. Don't forget to create yourself a
little icon, and update the path to the icon to match your icon's path.
import osfrom openlp.core.lib import Plugin, MediaManagerItemclass HelloWorldPlugin(Plugin): def __init__(self): # Call the parent constructor Plugin.__init__(self, 'HelloWorld', '1.9.0') # Create the plugin icon self.icon = QtGui.QIcon() self.icon.addPixmap(QtGui.QPixmap.fromImage(QtGui.QImage( os.path.join(os.path.asbpath(os.path.basename(__file__)), 'resources', 'images', 'helloworld.png'))), QtGui.QIcon.Normal, QtGui.QIcon.Off) def get_media_manager_item(self): # Create the MediaManagerItem object self.MediaManagerItem = MediaManagerItem(self.icon, 'Hello World') # Add a toolbar self.MediaManagerItem.addToolbar() # Create button for the toolbar self.MediaManagerItem.addToolbarButton('Hello World', 'Says, "Hello World"', os.path.join(os.path.asbpath(os.path.basename(__file__)), 'resources', 'images', 'helloworld.png'), self.onHelloWorldClick, 'HelloWorldItem') def onHelloWorldClick(self): QtGui.QMessageBox.information(None, 'Hello World!', 'This is just a little message box to say, "Hello World!"', QtGui.QMessageBox.StandardButtons(QtGui.QMessageBox.Ok), QtGui.QMessageBox.Ok)
So how does the plugin work?
Import the os module for use with file paths in our plugin.
Import the Plugin classes, so that we can use them in our code.
Make our class descend from the Plugin class.
Create a constructor:
Call the Plugin class's constructor to set up some basic
Load an icon for our plugin into the plugin's icon property.
Implement the get_media_manager_item() hook:
Create an instance of the XXXManagerItem class.
Implement the get_settings_tab() hook:
Create an instance of the XXXTab class.
Add a toolbar to the item.
Add a button to the toolbar, with the following parameters:
Slot (a function to react to the triggered() signal/event)
Create the Slot with an applicable action (in our case, showing a
"Hello World" dialog).
Hooks are special Python methods that are executed at various points
throughout openlp.org. The list below shows all of these hooks, when
each of them is activated, and what each one of them is supposed to do.
Show a dialog when the user clicks on the 'About' button in the plugin
A plugin's media item is passed to this function, which should return a
ServiceItem object which can be written to the service file.
A ServiceItem object from the service file is passed in. This function
parses and sets up an instance of the plugin's media item for use within
render(screen, service_item, theme)
Render the screenth screenful of the service_item (a ServiceItem
object), using theme settings in theme.
What is screen? An object, a number, a canvas?
Construct a MediaManagerItem object with all the buttons and things you
need, and return it for integration into openlp.org's Media Manager.
Given the import menu item, add an item to the Import menu.
Given the export menu item, add an item to the Export menu.
Add menu items to the menu, given the menubar.
Handle the event contained in the event object.
Called by the plugin manager to setup any additional features on
Each plugin comes with a built-in self.config object, which reads and
writes to a plugin-specific section of the openlp.org configuration
file. On Linux, Mac OS X, and other Unix-like operating systems, this
configuration file can be found in the following location:
~/.openlp/openlp.conf. On Windows, this file is found in:
C:\Documents and Settings\username\Application Data\.openlp\openlp.conf.
last dir = /home//somedirectory
This is location where the last file loaded into the plugin came from.
list count = 2
This is a count of how many files are to be loaded into the plugin's
list item 1 = /home//somedirectory/somefile.xyz
The location and name of the file to be loaded into the plugin's list.
A PluginUtils class can be added the the Plugin's definition to provide
access to a number of utility methods to reduce code duplication. These
methods will return empty lists or strings if the configuration tags
have not been defined.
add_to_context_menu(self, base, icon, text, slot)
Defines a Context menu item with icon 'icon' and text 'text'. Which is
connected to list 'base' and will trigger action 'slot' when selected.
Defines a Context separator item for the context menu
Reads the configuration data and returns a list of items to the added to
the display list.
Takes a display list 'displaylist' and saves the details in the
configuration file allowing the list to be reloaded later.
Reads the configuration file to provide the last directory used by the
Extracts the directory part of the filename and saves that in the
The Settings dialog calls each plugin using the get_settings_tab
method. The plugin is able to create a tab on the Settings Dialog by
returning a class extending SettingsTab.