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,9 +45,9 @@ signals structure, some steps are required:
45 CELERY_RESULT_BACKEND='djcelery.backends.cache:CacheBackend', 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 signals that the plugin will dispatch. It is suggested to name the variable 51 signals that the plugin will dispatch. It is suggested to name the variable
52 "registered_signals", but that nomenclature not strictly necessary. 52 "registered_signals", but that nomenclature not strictly necessary.
53 * It is also necessary to declare a variable containing the name of the plugin 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,17 +55,10 @@ signals structure, some steps are required:
55 contain any special character, such as dot or comma. It is suggested to name 55 contain any special character, such as dot or comma. It is suggested to name
56 the variable "short_name", but that nomenclature is not strictly 56 the variable "short_name", but that nomenclature is not strictly
57 necessary. 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 register_signal, which require the name of the plugin that is registering the 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 * In order to listen for a given signal, it is required to create a handling 62 * In order to listen for a given signal, it is required to create a handling
70 method. This method should be located at a file named tasks.py in the same 63 method. This method should be located at a file named tasks.py in the same
71 directory as the plugins files. It also must be said that this method need to 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,12 +74,27 @@ signals structure, some steps are required:
81 74
82 * With signals registered and handling method defined you must connect them. 75 * With signals registered and handling method defined you must connect them.
83 To do it you must call connect_signal passing signal name, sender and handling 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 .. code-block:: python 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 * To send a broadcast signal you must call send method anywhere passing signal name 99 * To send a broadcast signal you must call send method anywhere passing signal name
92 and sender as arguments. If necessary you can pass another parameters in 100 and sender as arguments. If necessary you can pass another parameters in