Plugin Developer Documentation

Getting Started

To start a new plugin, run the command:

$ colab-admin startplugin plugin_name [directory]

Where plugin_name is the name of your new plugin. And directory, which is optional, specifies the directory where the structure of your plugin will be created.

Signals

Implement signals in plugins is optional! You may follow this steps only if you want to communicate with another plugins.

In order to configure a plugin to able to listen and send signals using Colab signals structure, some steps are required:

  • In the apps.py file it is necessary to declare a list variable containing all the signals that the plugin will dispatch. It is suggested to name the variable “registered_signals”, but that nomenclature is not strictly necessary.
  • It is also necessary to declare a variable containing the name of the plugin that will send the signal. It must be said that the name of the plugin cannot contain any special character, such as dot or comma. It is suggested to name the variable “short_name”, but that nomenclature is not strictly necessary.
  • Finally, the variable namespace should also be defined. This variable is the url namespace for django reverse.
  • In order to actually register the signals, it is necessary to implement the method register_signal, which require the name of the plugin that is registering the signals and a list of signals to be registered as parameters. You must not call this method nowhere.
  • In order to listen for a given signal, it is required to create a handling method. This method should be located at a file named tasks.py in the same directory as the plugins files. It also must be said that this method need to receive at least a **kwargs parameter. An example of a handling method can be seen below:
from colab.celery import app

@app.task(bind=True)
def handling_method(self, **kwargs):
    # DO SOMETHING
  • With signals registered and handling method defined you must connect them. To do it you must call connect_signal passing signal name, sender and handling method as arguments. These should be implemented on plugin’s apps.py. It must be said that the plugin app class must extend ColabPluginAppConfig. An example of this configuration can be seen below:
from colab.plugins.utils.apps import ColabPluginAppConfig
from colab.signals.signals import register_signal, connect_signal
from colab.plugins.PLUGIN.tasks import HANDLING_METHOD

class PluginApps(ColabPluginAppConfig):
     short_name = PLUGIN_NAME
     signals_list = [SIGNAL1, SIGNAL2]
     namespace = PLUGIN_NAMESPACE

     def registered_signal(self):
         register_signal(self.short_name, self.signals_list)

     def connect_signal(self):
         connect_signal(self.signals_list[0], self.short_name,
           HANDLING_METHOD)
         connect_signal(self.signals_list[1], self.short_name,
           HANDLING_METHOD)
  • To send a broadcast signal you must call send method anywhere passing signal name and sender as arguments. If necessary you can pass another parameters in **kwargs. As you can see below:
from colab.signals.signals import send

send(signal_name, sender)
  • If you want to run celery manually to make some tests, you should execute:
colab-admin celeryC worker --loglevel=debug

Storing TimeStamp

TimeStamp is a parameter to control the last time a model was updated, you should use it when you want the data updated after a given time. To do that, the colab model (colab.plugins.models) has a TimeStampPlugin class, used to store all last updates from timestamp from all plugins. The class methods used to handle TimeStamp can be seen bellow:

update_timestamp(cls,class_name):  # allow store a current datetime.
get_last_updated_timestamp(cls,class_name):   # allow get a datetime with last timestamp stored from class_name.

Example Usage:

from colab.plugins.models import TimeStampPlugin

class TestPlugin():

    def update_timestamp(self):
       TimeStampPlugin.update_timestamp('TestPlugin')

    def get_last_updated_timestamp(self):
       return TimeStampPlugin.get_last_updated_timestamp('TestPlugin')

Password Validation

Allows the plugin to define rules to set the password. The validators are functions which receive the password as only argument and if it doesn’t match the desired rules raises a ValidationError. The message sent in the validation error will be displayed to the user in the HTML form.

Example:

## myplugin/password_validators.py

def has_uppercase_char(password):
    for char in password:
        if char.isupper():
            return

    raise ValidationError('Password must have at least one upper case char')

## /etc/colab/plugins.d/myplugin.py

password_validators = (
    'myplugin.password_validators.has_uppercase_char',
)

Username Validation

Allows the plugin to define rules to set the username. The validators are the same as the password validators ones. Therefore, they follow the same structure.

Example:

## myplugin/username_validators.py

def has_uppercase_char(username):
    for char in username:
        if char.isupper():
            return

    raise ValidationError('Username must have at least one upper case char')

## /etc/colab/plugins.d/myplugin.py

 username_validators = (
    'myplugin.username_validators.has_uppercase_char',
)

Blacklist

If you don’t want a page to be accessed, you should add in your configuration file (/etc/colab/plugins.d) an array of regex strings named ‘blacklist’ that stands for the urls. The pages will then return a 403 error (forbidden).

Ex:

blacklist = [r'^dashboard$']

It also must be said that the full url that will be blocked is a combination of the plugin prefix and one of the elements of the blacklist array. For example, given a plugin with this configuration:

urls = {
    'include': 'colab_plugin.urls',
    'prefix':  '^plugin/',
    }

blacklist = [r'^feature$']

The actual url that will be blocked will them be: plugin/feature.

Change Header

If you want to change the header on your plugin pages, you should add in your configuration file (/etc/colab/plugins.d/) a boolean variable ‘change_header’, where True uses the slim header and False uses the default header. The default value of ‘change_header’ variable is False.

urls = {
    'include': 'colab_plugin.urls',
    'prefix':  '^plugin/',
    }

change_header = True