Creating plugins

Plugins provide an easy way to extend the functionality of Porla. Use them to automatically categorize, tag and manage torrents, or send notifications, etc.

info

This is not a Lua language guide but rather a quick-start on how to get started with your own plugin.

Basics

Plugins must return a table. Any errors in the init function will fail the load.

example.lua

return {
    init = function()
        print("Hello, world!")
    end
}

This will print "Hello, world!" to the Porla log at the info level every time the plugin is loaded. Reload the plugin from the plugin settings to see it happen multiple times.

Name and version

A plugin in a directory or a zip file can ship a plugin.json next to plugin.lua. Porla shows its name and version in the plugin list. It's optional: without it, the directory or file name is used, and single-file .lua plugins can't have one.

plugin.json

{
  "name": "My plugin",
  "version": "1.2.0"
}

Configuration

Users can pass configuration to a plugin. This configuration must be valid Lua as well. The Lua object is passed as the first argument to the init function.

Any errors in parsing the config will fail the load.

example-with-config.lua

return {
    init = function(config)
        print("Hello, " .. config.name .. "!")
    end
}

Update the plugin to have the following configuration.

return {
    name = "vktr"
}

If no configuration is provided, config will be nil.

Destroying

When a plugin is destroyed (unloaded) Porla will try to call the destroy function if one is provided.

This provides an simple way of doing any last-minute cleanup.

warning

The destroy is sync and the Lua state will be destroyed immediately after the function returns. Asynchronous callbacks will not work here.

example-with-destroy.lua

return {
    init = function()
        print("Hello, world!")
    end,

    destroy = function()
        print("Goodbye, cruel world")
    end
}