Development:Plugin Developers Guide

'''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.'''

Directory Structure
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  directory there will be a   file which contains the   class. This plugin class extends the builtin openlp.org Plugin class. This provides your plugin with a number of key methods to override.

Naming Conventions

 * All code should follow the Python syntax guidelines, known as PEP 8.
 * 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.

Note: This is a cut down version of the Plugin class.

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  directory. Let's call it.
 * Create a  file in that directory. This converts the directory into a Python module, so that openlp.org can load your plugin.
 * Create a file named.

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.

An Explanation
So how does the plugin work?


 * Import the  module for use with file paths in our plugin.
 * Import the  classes, so that we can use them in our code.
 * Make our class descend from the  class.
 * Create a constructor:
 * Call the  class's constructor to set up some basic information.
 * Load an icon for our plugin into the plugin's  property.
 * Implement the  hook:
 * Create an instance of the  class.
 * Implement the  hook:
 * Create an instance of the  class.


 * Add a toolbar to the item.
 * Add a button to the toolbar, with the following parameters:
 * Caption
 * Tooltip
 * Icon
 * Slot (a function to react to the  signal/event)
 * Object name
 * Create the Slot with an applicable action (in our case, showing a "Hello World" dialog).

Plugin Hooks
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 manager.

A plugin's media item is passed to this function, which should return a  object which can be written to the service file.

A  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 the plugin.

Render the screenth screenful of the  (a   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 creation.

Configuration File
Each plugin comes with a built-in  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:. On Windows, this file is found in:.

For example:

[]

This is location where the last file loaded into the plugin came from.

This is a count of how many files are to be loaded into the plugin's list

The location and name of the file to be loaded into the plugin's list.

PluginUtls Class
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.

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 plugin

Extracts the directory part of the filename and saves that in the configuration file

Settings Tabs
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.