Download as
Browse Code »

Commit 7b743f36bbf8dd6c2e49390ce7e4b7b78f4798b4

Authored by Lucas Moura
Committed by Sergio Oliveira
1 parent c811c353
Exists in master and in 30 other branches 1.12.x, add_requests_as_dep, celery_service, change-passwd-signal, colab-signals, colab-vcard, colab_search, colab_tag, colab_tag_merge, detach_super_archives, fix-dashboard, fix-message-preview, fix_app_label, fix_header, fixed_gitlab_import, go_to_profile_panel, mobile_user_scalable, paginate-threads, profile_integration, refactor-data-import, remove-gitlab-plugin, removing_namespace, search_block, search_filters, split_screen, startplugin, timestamp_plugins, translation_review, user_regex, validate-passwd

Update plugins dev documentation 

Present how to implement plugins signals with new abstract methods.

Signed-off-by: Lucas Kanashiro <kanashiro.duarte@gmail.com>
Showing 1 changed file with 25 additions and 17 deletions   Show diff stats
docs/source/plugindev.rst
  Diff comments   View file @7b743f3
... ... @@ -45,9 +45,9 @@ signals structure, some steps are required:
45 45 CELERY_RESULT_BACKEND='djcelery.backends.cache:CacheBackend',
46 46 )
47 47  
48   -* The plugin should import the method from colab.signals.tasks in order for the
49   - plugin to use the necessary method to handle signals
50   -* In the apps.py file it is necessary to declare a list variable containing all the
  48 +* You must create signals.py in plugin root directory to implement both,
  49 + registered signals and connect signals.
  50 +* In the signals.py file it is necessary to declare a list variable containing all the
51 51 signals that the plugin will dispatch. It is suggested to name the variable
52 52 "registered_signals", but that nomenclature not strictly necessary.
53 53 * It is also necessary to declare a variable containing the name of the plugin
... ... @@ -55,17 +55,10 @@ signals structure, some steps are required:
55 55 contain any special character, such as dot or comma. It is suggested to name
56 56 the variable "short_name", but that nomenclature is not strictly
57 57 necessary.
58   -* In order to actually register the signals, it is necessary to call the method
  58 +* In order to actually register the signals, it is necessary to implement the method
59 59 register_signal, which require the name of the plugin that is registering the
60   - signals and a list of signals to be registered as parameters. This method
61   - should be called on the app method named __init__. Since the plugin class is a
62   - subclass of AppConfig, the constructor of the parent must be calles as weel.
63   -
64   -.. code-block:: ṕython
65   - def __init__(self, app_name, app_module):
66   - super(ProxyGitlabAppConfig, self).__init__(app_name, app_module)
67   - register_signal(self.short_name, self.signals_list)
68   -
  60 + signals and a list of signals to be registered as parameters. You must not
  61 + call this method nowhere.
69 62 * In order to listen for a given signal, it is required to create a handling
70 63 method. This method should be located at a file named tasks.py in the same
71 64 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:
81 74  
82 75 * With signals registered and handling method defined you must connect them.
83 76 To do it you must call connect_signal passing signal name, sender and handling
84   - method as arguments. This calling must be into ready function in apps.py, as
85   - you can see below:
  77 + method as arguments. This calling must be into ready function in apps.py.
  78 +
86 79  
87 80 .. code-block:: python
88   - def ready(self):
89   - connect_signal(self.signal_name, self.sender, handling_method)
  81 + from colab.plugins.utils.signals import AbstractSignal
  82 + from colab.signals.signals import register_signal, connect_signal
  83 + from colab.plugins.PLUGIN.tasks import HANDLING_METHOD
  84 +
  85 + class PluginSignals(AbstractSignal):
  86 + short_name = PLUGIN_NAME
  87 + signals_list = [SIGNAL1, SIGNAL2]
  88 +
  89 + def registered_signal(self):
  90 + register_signal(self.short_name, self.signals_list)
  91 +
  92 + def connect_signal(self):
  93 + connect_signal(self.signals_list[0], self.short_name,
  94 + HANDLING_METHOD)
  95 + connect_signal(self.signals_list[1], self.short_name,
  96 + HANDLING_METHOD)
  97 +
90 98  
91 99 * To send a broadcast signal you must call send method anywhere passing signal name
92 100 and sender as arguments. If necessary you can pass another parameters in
... ...