From 7b743f36bbf8dd6c2e49390ce7e4b7b78f4798b4 Mon Sep 17 00:00:00 2001 From: Lucas Moura Date: Thu, 30 Jul 2015 11:40:43 -0300 Subject: [PATCH] Update plugins dev documentation --- docs/source/plugindev.rst | 42 +++++++++++++++++++++++++----------------- 1 file changed, 25 insertions(+), 17 deletions(-) diff --git a/docs/source/plugindev.rst b/docs/source/plugindev.rst index d650e3e..1f3b673 100644 --- a/docs/source/plugindev.rst +++ b/docs/source/plugindev.rst @@ -45,9 +45,9 @@ signals structure, some steps are required: CELERY_RESULT_BACKEND='djcelery.backends.cache:CacheBackend', ) -* The plugin should import the method from colab.signals.tasks in order for the - plugin to use the necessary method to handle signals -* In the apps.py file it is necessary to declare a list variable containing all the +* You must create signals.py in plugin root directory to implement both, + registered signals and connect signals. +* In the signals.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 not strictly necessary. * It is also necessary to declare a variable containing the name of the plugin @@ -55,17 +55,10 @@ signals structure, some steps are required: 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. -* In order to actually register the signals, it is necessary to call the method +* 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. This method - should be called on the app method named __init__. Since the plugin class is a - subclass of AppConfig, the constructor of the parent must be calles as weel. - -.. code-block:: ṕython - def __init__(self, app_name, app_module): - super(ProxyGitlabAppConfig, self).__init__(app_name, app_module) - register_signal(self.short_name, self.signals_list) - + 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 @@ -81,12 +74,27 @@ signals structure, some steps are required: * 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. This calling must be into ready function in apps.py, as - you can see below: + method as arguments. This calling must be into ready function in apps.py. + .. code-block:: python - def ready(self): - connect_signal(self.signal_name, self.sender, handling_method) + from colab.plugins.utils.signals import AbstractSignal + from colab.signals.signals import register_signal, connect_signal + from colab.plugins.PLUGIN.tasks import HANDLING_METHOD + + class PluginSignals(AbstractSignal): + short_name = PLUGIN_NAME + signals_list = [SIGNAL1, SIGNAL2] + + 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 -- libgit2 0.21.2