plugins

Documentation

Overview

Package plugins defines the Plugin interface and other types that work in the plugins system.

Index

• func Activate(p Plugin)
• func Deactivate(pluginID string)
• func DoFilter(filter filters.Filter, payload proto.Message) (proto.Message, error)
• func DoHook(hook hooks.Hook, payload proto.Message) ([]proto.Message, error)
• func Serve(p Plugin)
• func ValidID(id string) bool
• type Plugin
• type PluginCapabilities

Functions

func Activate

func Activate(p Plugin)

Activate activates a plugin on the host side.

func Deactivate

func Deactivate(pluginID string)

Deactivate deactivates a plugin on the host side.

func DoFilter

func DoFilter(filter filters.Filter, payload proto.Message) (proto.Message, error)

DoFilter calls all of the registered filter handlers of the named filter serially. If an error is returned from any of the handlers, the data that is available at that point is returned with the error without further filtering.

func DoHook

func DoHook(hook hooks.Hook, payload proto.Message) ([]proto.Message, error)

DoHook calls all of the registered hook handles for the named hook with the given data. The slice returned indicates the number of hook handlers that were called.

If an error is returned from any of the handlers, the messages already received are returned along with the error, and no more handlers are called.

func Serve

func Serve(p Plugin)

Serve starts up a plugin's serving to the main host system. This function should be called within each plugin package's main function. This function blocks while the connection with the host system persists.

func ValidID

func ValidID(id string) bool

ValidID says whether id is a valid identifier for a plugin. An ID must be between 2 and 20 characters long, begin and end with a lowercase English character, and contain only lowercase English characters and underscores.

Types

type Plugin

type Plugin interface {
	// Identity returns the plugin's basic identifying metadata.
	// This function is called before the main plugin connection is established.
	Identity() (name string, id string, ver version.Version)

	// Specs returns the specifications within which the plugin works.
	//
	// For example, the plugin may indicate that it should be called asynchronously, or that it needs certain
	// database access capabilities, or that it depends on a particular version of the main app system or other
	// plugins.
	Specs() []specs.Spec

	// Hooks specifies all of the hooks which the plugin wants to handle with its hook handlers.
	Hooks() map[hooks.Hook]hooks.Handler

	// Filters specifies all of the filters which the plugins wants to handle with its filter handlers.
	Filters() map[filters.Filter]filters.Handler

	// CustomHooks returns the list of all of the custom hooks the plugin is registering.
	//
	// One plugin's custom hooks are not the same as another plugin's custom hooks with the same name because
	// the name of each of a plugin's custom hooks is prefixed with the plugin ID. So for one plugin to hook
	// into another plugin's registered custom hooks, the Plugin must list the other plugin's hook name with
	// the other plugin's ID followed by a dot followed by the hook name.
	//
	// So, for example, suppose a plugin with ID "alice" registers a custom hook named "jump" and another plugin
	// with ID "bob" wants to hook into that. The "bob" plugin needs to include its Handler with the hooks map
	// it returns in the Hooks function, the key of this custom hook being "alice.jump".
	CustomHooks() []hooks.Hook

	// CustomFilters returns the list of all of the custom filters the plugin is registering.
	// Namespacing across plugins works just as it does for hooks.
	CustomFilters() []filters.Filter
}

A Plugin is a plugin that responds to hooks that it has registered to handle.

type PluginCapabilities

type PluginCapabilities struct {
	data.SiteGetter
	data.SiteInserter
	data.SiteDeleter
	data.SiteManager

	data.BlobGetter
	data.BlobInserter
	data.BlobDeleter
	data.BlobManager

	data.ContentGetter
	data.ContentInserter
	data.ContentDeleter
	data.ContentManager

	data.UserGetter
	data.UserInserter
	data.UserDeleter
	data.UserManager

	data.UserMetaGetter
	data.UserMetaInserter
	data.UserMetaDeleter
	data.UserMetaManager

	data.OptionGetter
	data.OptionInserter
	data.OptionDeleter
	data.OptionManager

	email.Sender
}

PluginCapabilities contains the capabilities a Plugin may use for its features. Only the user-authorized and explicitly requested capabilities are set here as non-nil.