Skip to content

API : Plugins

Jump to bottom
Damien BUTY edited this page May 20, 2020 · 2 revisions

Plugins are a way to augment your aido application by extending its database, adding methods and properties to the Slash class, or exposing helpers to other plugins and Slashes.

They are recommended because they allow you to reuse parts of your code in different slashes and organize your code in separate concerns. In general we recommend separating :

  • aido-related code (such as manipulating the view and state) in your extended Slash class
  • domain-related code (such as manipulating your application's database, external APIs etc...) in plugins

Plugins are always initialized in the order they are placed in the plugins init configuration option.

Plugin factory

A plugin is a function which returns a standard plugin object containing its name and any of 4 plugin hooks.

function pluginFactory(koa, utils) {
  return {
    name: 'my-plugin',
    // Plugin hooks
    extendDb: () => {},
    initPlugin: () => {},
    getHelpers: () => {},
    slashFactory: () => {},
  }
}

Arguments

The plugin factory will be called with the following arguments :

pluginFactory(koa, utils)
  • koa (Object)
  • koa.router (Object) : This is the koa-router underlying your aido server. You can use it to declare new routes on your server for serving static files or whatever fits your needs.
  • koa.app (Object) : This is the koa application underlying your aido server
  • koa.app.context (Object) : The koa base context for all queries
  • koa.app.context.options (Object) : The init configuration options of the aido application
  • koa.app.context.database (Object) : The database object of the aido application
  • koa.app.context.bot (Object) : The Slack API client (see here for more information)
  • utils (Object) : A collection of utilities to interact with your aido instance
  • utils.registerSlash (function) : Used to register a new Slash command. See here for reference
  • utils.registerView (function) : Used to register a new view. See here for reference
  • utils.emitSlash (function) : Manually trigger a Slash command on a user. See here for reference
  • utils.emitAction (function) : Manually trigger an action on a user. See here for reference
  • utils.helpers (Object) : Helpers exposed by other plugins (see below)
  • utils.middleware (Object)
  • utils.middleware.checkToken (function) : This is the koa middleware used to validate that a request comes from the Slack application, using the Signing Secret or Verification Token. Please refer to the source code if you intend to use it.
  • utils.middleware.initSlash (function) : This is the koa middleware used to instantiate the Slash command and execute its hooks in sequence. Please refer to the source code if you intend to use it.

Return value

The plugin factory is expected to return a standard plugin object, containing the following. Plugin hooks can be either synchronous or asynchronous functions, and are executed when the server starts, in the order they appear in :

return {
  name: 'myPlugin',
  // Plugin hooks
  extendDb: () => {},
  initPlugin: () => {},
  getHelpers: () => {},
  slashFactory: () => {},
}
  • name (String) : The name of your plugin. This will be used as a namespace for any helpers exposed by the plugin (in this case, utils.helpers.myPlugin.someHelper)
  • extendDb (function) : You may use this hook to perform any required database preparation, such as creating tables and provisioning your models. It is executed with the following argument :
  • initPlugin (function) : You may use this hook to perform any initialization task of your plugin. It is executed with the following argument :
  • getHelpers (function) : You may use this hook to provide helpers methods and properties for other plugins to use. The return of this function will be exposed in utils.helpers.myPlugin. It is executed with the following argument :
  • slashFactory (function) : You may use this hook to extend the base Slash class with new methods and properties. It must return a javascript Class. It is executed with the following argument :
    • oldSlash (Class) : The original Slash. Please note that at this point it might have already been extended by previous plugins, so any methods and properties added by these plugins are already available.
function slashFactory(oldSlash) {
  // Extend the oldSlash class
  class Slash extends oldSlash {
    // Add a method to it
    newMethod {
      // ...
    }
  }
  // Return the extended Slash class
  return Slash
}

Examples

Don't hesitate to read the source code of the polls example project for a simple example.

You can also check the following aido plugins for more specific use cases :

Clone this wiki locally