Plugins offer a mechanism to extend Saleor's Python core with new functionality. They are loaded by the core process and use predefined callbacks to execute custom code in response to certain events.
Saleor ships with some plugins included, you can find those in the
saleor/payment/gateways/ directories of the core.
Base plugin class
BasePlugin class is located in the
saleor.plugins.base_plugin. It's an abstract class implementing the entire API of callback methods available to plugins.
Multiple plugins are executed as a pipeline. Each callback receives a
previous_value parameter: the first plugin receives the default value, each consecutive plugin receives the value returned by the previous one.
Saleor allows you to change the configuration of any given plugin over API.
CONFIG_STRUCTURE describes the shape of the configuration: field names, their types, and labels to use in the user interface.
DEFAULT_CONFIGURATION provides initial values for those fields.
The plugin configuration can be further validated by overwriting the
validate_plugin_configuration method like in the following example:
Saleor will use this data to create default configuration in DB which will be served by the API.
Writing a new plugin
Make sure that each plugin inherits from the
BasePlugin class and that it overwrites base methods.
You can write your plugin as a class which has callable instances, like the one below:
There is no need to implement all base methods as the
PluginsManager will use default values for methods that are not implemented.
Loading your plugin
Saleor uses the entry points API of Python's
setuptools to automatically discover installed plugins. To make a plugin discoverable, include a
saleor.plugins entry point in your
setup() call. The syntax is
package_name = package_name.path.to:PluginClass:
If your plugin is a Django app, the package name (the part before the equal sign) will be added to Django's
INSTALLED_APPS so you can take advantage of Django's features such as ORM integration and database migrations.
Some plugin operations should be done asynchronously. Saleor uses Celery and will discover all Celery tasks declared in
tasks.py in the plugin directories.
BasePlugin has an abstract method
webhook method can be used for processing the payload received over HTTP. It is useful in case when a plugin can receive the data from the external services, like payment gateway or external notification system.
The above method will be called when we execute the request to
PluginManager will identify the owner of the request and will pass the data to the expected plugin. Everything in the URL path after the
PLUGIN_ID(my.plugin) will be passed to the plugin as a
Plugin as a response needs to return the object of type inherited from
Customizing the plugins manager
PluginsManager class is located in the
saleor.plugins.manager module. It is a class responsible for handling all declared plugins and serving a response from them. Unless further customized this class is used to interface with the plugins. Should you need to use a custom sub-class (or an entirely new implementation), you can tell Saleor to use it by setting
settings.PLUGIN_MANAGER to the Python path of your custom implementation.