Creating a plugin

It is possible to extend eventyay with custom Python code using the official plugin API. Every plugin has to be implemented as an independent Django ‘app’ living in its own python package installed like any other python module. There are also some official plugins inside the eventyay/plugins/ directory of your eventyay installation.

The communication between eventyay and the plugins happens mostly using Django’s signal dispatcher feature. The core modules of eventyay, eventyay.base, eventyay.control and eventyay.presale expose a number of signals which are documented on the next pages.

To create a new plugin, create a new python package which must be a valid Django app and must contain plugin metadata, as described below. There is some boilerplate that you will need for every plugin to get started. To save your time, we created a cookiecutter template that you can use like this:

$ pip install cookiecutter
$ cookiecutter https://github.com/fossasia/eventyay-plugin-cookiecutter

This will ask you some questions and then create a project folder for your plugin.

The following pages go into detail about the several types of plugins currently supported. While these instructions don’t assume that you know a lot about eventyay, they do assume that you have prior knowledge about Django (e.g. its view layer, how its ORM works, etc.).

Plugin metadata

The plugin metadata lives inside a eventyayPluginMeta class inside your app’s configuration class. The metadata class must define the following attributes:

Attribute	Type	Description
name	string	The human-readable name of your plugin
author	string	Your name
version	string	A human-readable version code of your plugin
description	string	A more verbose description of what your plugin does.
category	string	Category of a plugin. Either one of "FEATURE", "PAYMENT", "INTEGRATION", "CUSTOMIZATION", "FORMAT", or "API", or any other string.
visible	boolean (optional)	True by default, can hide a plugin so it cannot be normally activated.
restricted	boolean (optional)	False by default, restricts a plugin such that it can only be enabled for an event by system administrators / superusers.
compatibility	string	Specifier for compatible eventyay versions.

A working example would be:

try:
    from eventyay.base.plugins import PluginConfig
except ImportError:
    raise RuntimeError("Please use eventyay 2.7 or above to run this plugin!")
from django.utils.translation import gettext_lazy as _


class PaypalApp(PluginConfig):
    name = 'eventyay_paypal'
    verbose_name = _("PayPal")

    class EventyayPluginMeta:
        name = _("PayPal")
        author = _("the development team")
        version = '1.0.0'
        category = 'PAYMENT
        visible = True
        restricted = False
        description = _("This plugin allows you to receive payments via PayPal")
        compatibility = "eventyay>=2.7.0"


default_app_config = 'eventyay_paypal.PaypalApp'

The AppConfig class may implement a property compatibility_errors, that checks whether the eventyay installation meets all requirements of the plugin. If so, it should contain None or an empty list, otherwise a list of strings containing human-readable error messages. We recommend using the django.utils.functional.cached_property decorator, as it might get called a lot. You can also implement compatibility_warnings, those will be displayed but not block the plugin execution.

The AppConfig class may implement a method is_available(event) that checks if a plugin is available for a specific event. If not, it will not be shown in the plugin list of that event.

Plugin registration

Somehow, eventyay 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:

setup(
    args...,
    entry_points="""
[eventyay.plugin]
eventyay_paypal=eventyay_paypal:eventyayPluginMeta
"""
)

This will automatically make eventyay discover this plugin as soon as it is installed e.g. through pip. During development, you can just run python setup.py develop inside your plugin source directory to make it discoverable.

Signals

The various components of eventyay define a number of 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:

class PaypalApp(AppConfig):
    name = 'eventyay_paypal'

    def ready(self):
        from . import signals  # NOQA

You can optionally specify code that is executed when your plugin is activated for an event in the installed method:

class PaypalApp(AppConfig):
    name = 'eventyay_paypal'

    def installed(self, event):
        pass  # Your code here

Note that installed will not be called if the plugin is indirectly activated for an event because the event is created with settings copied from another event.

Views

Your plugin may define custom views. If you put an urls submodule into your plugin module, eventyay will automatically import it and include it into the root URL configuration with the namespace plugins:<label>:, where <label> is your Django app label.

Warning

If you define custom URLs and views, you are currently on your own with checking that the calling user is logged in, has appropriate permissions, etc. We plan on providing native support for this in a later version.