docs » cp.plugins

This is a simple plugin manager.

Functions

It has a few core functions:

`plugins.init(...)`

This function will load all enabled plugins in the specified 'parent' folders. For example:

local plugins = require("cp.plugins")
plugins.init("~/Library/Application Support/CommandPost/Plugins")

This will load all plugins in the current user's Library/Application Support/CommandPost/Plugins folder.

`cp.plugins.getPluginModule(id)`

Once the plugins have been loaded, the module can be accessed by their ID via the getPluginModule(id) function. It will return the module returned by the plugin's init function. This can also be done via the default function for the library. Eg:

plugins("my.plugin.id").doSomething()

Plugin Modules

Plugins typically have two parts:

The plugin table, which defines details about the plugin, and
The module, or result, which could be anything, which is returned from the init function.

A plugin file should return a plugin table that allows the plugin to be initialised. The table will look something like this:

local module = {}

local module.init(otherPlugin)
    -- do stuff with otherPlugin here
end

local plugin = {
    id = "my.plugin.id",
    group = "foo",
    dependencies = {
        ["some.other.plugin"] = "otherPlugin",
    },
}

function plugin.init(dependencies)
   -- do stuff to initialise the module here
   module.init(dependencies.otherPlugin)
   return module
}

function plugin.postInit(dependencies)
   -- do stuff that will happen after all plugins have been initialised.
end

As you can see above, plugin module can have a few simple functions and properties. The key ones are:

`plugin.id`

This is a unique ID for the plugin. It is used to load the plugin externally, as well as to define dependencies between plugins.

`plugin.group`

This is the group ID for the plugin. This is used to group plugins visually in the Properties panel for Plugins.

`plugin.required`

This optional property can be specified for plugins which should never be disabled. This should only be set for plugins which will break the application if disabled.

`plugin.dependencies`

This is a table with the list of other plugins that this plugin requires to be loaded prior to this plugin. Be careful of creating infinite loops of dependencies - we don't check for them currently!

It is defined like so:

plugin.dependencies = {
    "cp.plugins.myplugin",
    ["cp.plugins.otherplugin"] = "otherPlugin"
}

As you can see, there are two ways of declaring a dependency. The first is with just the plugin ID, the second has an alias.

These can be accessed in the `init` and `postInit` functions like so:

```lua
function plugin.init(dependencies)
   local myPlugin = dependencies["cp.plugins.myplugin"]
   local otherPlugin = dependencies.otherPlugin -- or dependencies["cp.plugins.otherplugin"]
end

A plugin will only have its init function called after its dependencies have successfully had their init functions called. Additionally, if a plugin has a postInit, all declared postInits for dependencies will have been called prior to the plugin's postInit function.

`function plugin.init(dependencies[, environment]) -> module`

This function is basically required. It will be executed when the plugin is initialised. The dependencies parameter is a table containing the list of dependencies that the plugin defined via the dependencies property. The environment provides access to resources such as images, HTML files, or other lua modules that are bundled with the plugin. See Simple vs Complex Plugins below.

As you may have noted, there are two ways to specify a plugin is required. Either by simply specifying it as an 'array' item (the first example) or as a key/value (the second example). Doing the later allows you to specify an alias for the dependency, which can be used in the init(...) function, like so:

local plugin = {}

plugin.dependencies = {
    "cp.plugins.myplugin",
    ["cp.plugins.otherplugin"] = "otherplugin"
}

function plugin.init(dependencies)
    local myplugin = dependencies["cp.plugins.myplugin"]
    local otherplugin = dependencies.otherplugin

    -- do other stuff with the dependencies

    return myinstance
end

return plugin

Simple vs Complex Plugins

There are two types of plugin structures supported. The Simple version is a single .lua file that matches the above format for plugin. The Complex version is a folder containing an init.lua file that matches the above format.

The key advantage of Complex Plugins is that the folder can contain other resources, such as images, HTML templates, or other .lua files - including 3rd-party libraries if desired. These can be accessed via two main mechanisms:

The second environment parameter in the init function. This is a cp.plugins.env table, which provides access to files and templates inside the plugin folder. See the documentation for details.
The standard require method will allow loading of *.lua files inside the plugin from the init.lua.

For example, if you have a file called foo.lua in your folder, it can be required like so:

local foo = require("foo")

You do not have to know anything about where the plugin folder is stored, or use the plugin ID. Just use the local file path within the plugin. If you have another file in a foo folder called bar.lua, it can be loaded via:

local fooBar = require("foo.bar")

These modules will not be accessible to other plugins or to the main application. They are only available to code inside the plugin.

Submodules

cp.plugins.env
cp.plugins.plugin

API Overview

Constants - Useful values which cannot be changed
CACHE
SETTINGS_DISABLED
Variables - Configurable values
IDS
Functions - API calls offered directly by the extension
addDependent
disable
enable
getDependents
getPlugin
getPluginIds
getPluginModule
getPlugins
init
initPlugin
initPlugins
isDisabled
loadComplexPlugin
loadDependencies
loadSimplePlugin
postInitPlugin
postInitPlugins
scanDirectory
watchPluginPaths

API Documentation

Constants

CACHE

Signature	`cp.plugins.CACHE -> table`
Type	Constant
Description	Plugin Cache

SETTINGS_DISABLED

Signature	`cp.plugins.SETTINGS_DISABLED -> string`
Type	Constant
Description	Plugin Disabled Code

Variables

IDS

Signature	`cp.plugins.IDS -> table`
Type	Variable
Description	Plugin Status Codes

Functions

addDependent

Signature	`cp.plugins.addDependent(id) -> none`
Type	Function
Description	Adds the `dependentPlugin` as a dependent of the plugin with the specified id.
Parameters	`id` - The plugin package ID. `dependentPlugin` - The plugin which is a dependent
Returns	None

disable

Signature	`cp.plugins.disable(...) -> boolean, string`
Type	Function
Description	Disabled the plugin(s) with the specified IDs and reloads the application.
Parameters	`...` - The list of plugin package IDs.
Returns	`true` if the plugin was disabled, or `false` if any of the plugins failed. If disabling failed, the first ID that failed is returned as the second value.

enable

Signature	`cp.plugins.enable(...) -> boolean, string`
Type	Function
Description	Enables the plugin with the specified ID, and reloads the application.
Parameters	`...` - The plugin package ID.
Returns	`true` if the plugins had been disabled and are now enabled. If enabling failed, the plugin ID which could not be enabled is returned as the second value.

getDependents

Signature	`cp.plugins.getDependents(pluginId)`
Type	Function
Description	Retrieves the list of dependent plugins for the specified plugin id.
Parameters	`id` - The plugin ID.
Returns	The table of dependents.

getPlugin

Signature	`cp.plugins.getPlugin(id) -> plugin`
Type	Function
Description	Retrieves a plugin from the cache by ID.
Parameters	id - The ID of the plugin you want to get
Returns	The plugin

getPluginIds

Signature	`cp.plugins.getPluginIds() -> table`
Type	Function
Description	Retrieves an array of the loaded plugin IDs.
Parameters	None
Returns	the list of plugin IDs.

getPluginModule

Signature	`cp.plugins.getPluginModule(id) -> value`
Type	Function
Description	Returns an initialised plugin result with the specified `id`.
Parameters	`id` - The plugin package ID.
Returns	the result of the plugin's `init(...)` function call.

getPlugins

Signature	`cp.plugins.getPlugins() -> table`
Type	Function
Description	Retrieves an array of details about the set of loaded plugins.
Parameters	None
Returns	the list of plugins.

init

Signature	`cp.plugins.init(paths) -> cp.plugins`
Type	Function
Description	Initialises the plugin loader to look in the specified file paths for plugins.
Parameters	`paths` - An array of paths to search for plugins in.
Returns	`cp.plugins` - The module.

initPlugin

Signature	`cp.plugins.initPlugin(id) -> module`
Type	Function
Description	Initialises a specific plugin with the specified path.
Parameters	`id` - The LUA package to look in
Returns	the result of the plugin's `init(...)` function call.

initPlugins

Signature	`cp.plugins.initPlugins() -> none`
Type	Function
Description	Initialises all registered plugins.
Parameters	None
Returns	None

isDisabled

Signature	`cp.plugins.isDisabled(id) -> boolean`
Type	Function
Description	Checks if the specified plugin ID is disabled.
Parameters	`id` - The plugin package ID.
Returns	`true` if the plugin is disabled.

loadComplexPlugin

Signature	`cp.plugins.loadComplexPlugin(path) -> plugin`
Type	Function
Description	Loads a 'complex' plugin, which is a folder containing an `init.lua` file.
Parameters	`path` - The plugin package ID.
Returns	`true` if the plugin is successfully post-initialised.

loadDependencies

Signature	`cp.plugins.loadDependencies(plugin) -> table`
Type	Function
Description	Loads the list of dependencies for the provided plugin.
Parameters	`plugin` - The plugin object
Returns	an array of the dependencies required by the plugin, or `nil` if any could not be loaded.

loadSimplePlugin

Signature	`cp.plugins.loadSimplePlugin(id) -> plugin`
Type	Function
Description	Loads a 'simple' plugin, where it is defined by a single LUA script.
Parameters	`path` - The plugin package ID.
Returns	`true` if the plugin is successfully post-initialised.

postInitPlugin

Signature	`cp.plugins.postInitPlugin(id) -> boolean`
Type	Function
Description	Runs any post-initialisation functions declared for the specified plugin ID.
Parameters	`id` - The plugin package ID.
Returns	`true` if the plugin is successfully post-initialised.

postInitPlugins

Signature	`cp.plugins.postInitPlugins() -> none`
Type	Function
Description	Performs any post-initialisation required for plugins.
Parameters	None
Returns	None

scanDirectory

Signature	`cp.plugins.scanDirectory(directoryPath) -> cp.plugins`
Type	Function
Description	Scans the specified directory and loads any plugins in the directory,
Parameters	`directoryPath` - The path to the directory to scan.
Returns	boolean - `true` if the path was loaded successfully, false if there were any issues.

watchPluginPaths

Signature	`cp.plugins.watchPluginPaths() -> none`
Type	Function
Description	Watches the plugin paths for changes and reloads the application if any change.
Parameters	None
Returns	None

Files

cp.plugins.md

Latest commit

History

cp.plugins.md

File metadata and controls

docs » cp.plugins

Functions

plugins.init(...)

cp.plugins.getPluginModule(id)

Plugin Modules

plugin.id

plugin.group

plugin.required

plugin.dependencies

function plugin.init(dependencies[, environment]) -> module

Simple vs Complex Plugins

Submodules

API Overview

API Documentation

Constants

Variables

Functions

`plugins.init(...)`

`cp.plugins.getPluginModule(id)`

`plugin.id`

`plugin.group`

`plugin.required`

`plugin.dependencies`

`function plugin.init(dependencies[, environment]) -> module`