Creating a plugin¶
You can extend pretalx with custom Python code using the official plugin API. Think of every plugin as an independent Django application living in its own python package installed like any other python module.
The communication between pretalx and the plugins happens using Django’s signal dispatcher feature. The core modules of pretalx expose signals which you can read about on the next pages.
To create a new plugin, create a new python package which must be a valid Django application and must contain plugin meta-data, as described below. You will need some boilerplate for every plugin to get started. To save your time, we created a cookiecutter template that you can use like this:
(env)$ pip install cookiecutter (env)$ cookiecutter https://github.com/pretalx/pretalx-plugin-cookiecutter
This will ask you some questions and then create a project folder for your plugin. Afterwards install your plugin into pretalx:
(env)$ cd pretalx-pluginname (env)$ python setup.py develop
If you already had it running, you’ll now have to restart your pretalx dev-server for it to recognize the new plugin.
About this Documentation¶
The following pages go into detail about the types of plugins supported. While these instructions don’t assume that you know a lot about pretalx, they do assume that you have prior knowledge about Django (e.g. its view layer, how its ORM works, topics covered in the Django tutorial.).
The plugin meta-data lives inside a
PretalxPluginMeta class inside your
configuration class. The meta-data class must define the following attributes:
The human-readable name of your plugin
A human-readable version code of your plugin
A more verbose description of what your plugin does.
A working example would be:
1from django.apps import AppConfig 2from django.utils.translation import ugettext_lazy as _ 3 4 5class FacebookApp(AppConfig): 6 name = 'pretalx_facebook' 7 verbose_name = _("Facebook") 8 9 class PretalxPluginMeta: 10 name = _("Facebook") 11 author = _("the pretalx team") 12 version = '1.0.0' 13 visible = True 14 restricted = False 15 description = _("This plugin allows you to post talks to facebook.") 16 17 18default_app_config = 'pretalx_facebook.FacebookApp'
Somehow, pretalx needs to know that your plugin exists at all. For this purpose, we
make use of the entry point feature of setuptools. To register a plugin that lives
in a separate python package, your
setup.py should contain something like this:
1setup( 2 args..., 3 entry_points=""" 4[pretalx.plugin] 5pretalx_paypal=pretalx_paypal:PretalxPluginMeta 6""" 7)
This will automatically make pretalx discover this plugin as soon as you have
installed it e.g. through
pip. During development, you can run
setup.py develop inside your plugin source directory to make it discoverable.
pretalx defines signals which your plugin can listen for. We will go into the
details of the different signals in the following pages. We suggest that you
put your signal receivers into a
signals submodule of your plugin. You
should extend your
AppConfig (see above) by the following method to make
your receivers available:
1class PaypalApp(AppConfig): 2 ... 3 4 def ready(self): 5 from . import signals # noqa
You can optionally specify code that you want to execute when the organiser
activates your plugin for an event in the
installed method, and code to
execute upon removal in the
1class PaypalApp(AppConfig): 2 ... 3 4 def installed(self, event): 5 pass # Your code here 6 7 def uninstalled(self, event): 8 pass # Your code here
AppConfig class may also implement the method
which checks if a plugin is available for a specific event. If not, it will not
be shown on the plugin list for that event, and cannot be enabled.
Your plugin may define custom views. If you put an
urls submodule into your
plugin module, pretalx will automatically import it and include it into the root
URL configuration with the namespace
your Django application label.
We recommend that non-backend-URLs start with a /p/ to avoid collisions with event names.
If you define custom URLs and views, you are on your own with checking that the calling user has logged in, has appropriate permissions, and more. We plan on providing native support for this in a later version.
Occasionally, your plugin may need system-level configuration that doesn’t need
its own API. In this case, you can ask users to provide this configuration via
pretalx.cfg file. Ask them to put their configuration in a section
with the title
[plugin:your_plugin_name], which pretalx will then provide
settings.PLUGIN_SETTINGS[your_plugin_name], like this:
[plugin:pretalx_soap] endpoint=https://example.com api_key=123456
Which you can use in your code like this:
from django.conf import settings assert settings.PLUGIN_SETTINGS["pretalx_soap"]["endpoint"] == "https://example.com"
New in version 1.1: The
PLUGIN_SETTINGS configuration was added in pretalx 1.1.