Merge pull request #76 from force-h2020/74-changes-slots

Adds change_slots event to notify UI of slot-modifying changes

doc/source/plugin_development.rst

@@ -11,14 +11,31 @@ one of the above pluggable entities and its associated classes.
 To implement a new plugin, you must
 
 - define the entity you want to extend (e.g. ``MyOwnDataSource``) as a derived
-  class of the appropriate class (e.g. BaseDataSource), and reimplement
-  the appropriate methods.
-- Define the model that this DataSource needs, by extending
+  class of the appropriate class (e.g. ``BaseDataSource``), and reimplement
+  the appropriate methods:
+
+   - ``run()``: where the actual computation takes place, given the
+     configuration options specified in the model (which is received as an
+     argument). It is strongly advised that the ``run()`` method is stateless.
+   - ``slots()``: must return a 2-tuple of tuples. Each tuple contains instances
+     of the ``Slot`` class. Slots are the input and output entities of the
+     data source or KPI calculator. Given that this information depends on the
+     configuration options, ``slots()`` accepts the model and must return the
+     appropriate values according to the model options.
+
+- Define the model that this ``DataSource`` needs, by extending
   ``BaseDataSourceModel`` and adding, with traits, the appropriate data that
   are required by your data source to perform its task.
+  If a trait change in your model influences the input/output slots, you must
+  make sure that the event ``changes_slots`` is fired as a consequence of
+  those changes. This will notify the UI that the new slots need to be
+  recomputed and presented to the user. Failing to do so will have unexpected
+  consequences.
 - Define the Factory, by reimplementing BaseDataSourceFactory and reimplementing
   its ``create_*`` methods to return the above entities.
 - Define a ``Plugin`` by reimplementing ``BaseExtensionPlugin`` and
   reimplementing its initialization defaults methods to return your factory.
 - add the plugin class in the setup.py entry_point, under the namespace
   ``force.bdss.extensions``
+
+

force_bdss/core_plugins/dummy/csv_extractor/csv_extractor_model.py

-from traits.api import Int, String
+from traits.api import Int, String, on_trait_change
 
 from force_bdss.api import BaseDataSourceModel
 
@@ -8,3 +8,7 @@ class CSVExtractorModel(BaseDataSourceModel):
     row = Int()
     column = Int()
     cuba_type = String()
+
+    @on_trait_change("cuba_type")
+    def _notify_changes_slots(self):
+        self.changes_slots = True

force_bdss/core_plugins/dummy/kpi_adder/kpi_adder_model.py

-from traits.api import String
+from traits.api import String, on_trait_change
 
 from force_bdss.api import BaseKPICalculatorModel
 
@@ -6,3 +6,7 @@ from force_bdss.api import BaseKPICalculatorModel
 class KPIAdderModel(BaseKPICalculatorModel):
     cuba_type_in = String()
     cuba_type_out = String()
+
+    @on_trait_change("cuba_type_in,cuba_type_out")
+    def _notify_slots_changed(self):
+        self.changes_slots = True

force_bdss/data_sources/base_data_source_model.py

-from traits.api import ABCHasStrictTraits, Instance, List, String
+from traits.api import ABCHasStrictTraits, Instance, List, String, Event
 
 from force_bdss.core.input_slot_map import InputSlotMap
 from .i_data_source_factory import IDataSourceFactory
@@ -25,6 +25,12 @@ class BaseDataSourceModel(ABCHasStrictTraits):
     #: referenced somewhere else (e.g. the KPICalculators).
     output_slot_names = List(String(), visible=False)
 
+    #: This event claims that a change in the model influences the slots
+    #: (either input or output). It must be triggered every time a specific
+    #: option in your model implies a change in the slots. The UI will detect
+    #: this and adapt the visual entries.
+    changes_slots = Event()
+
     def __init__(self, factory, *args, **kwargs):
         self.factory = factory
         super(BaseDataSourceModel, self).__init__(*args, **kwargs)

force_bdss/kpi/base_kpi_calculator_model.py

-from traits.api import ABCHasStrictTraits, Instance, List, String
+from traits.api import ABCHasStrictTraits, Instance, List, String, Event
 
 from ..core.input_slot_map import InputSlotMap
 from .i_kpi_calculator_factory import IKPICalculatorFactory
@@ -25,6 +25,12 @@ class BaseKPICalculatorModel(ABCHasStrictTraits):
     #: referenced somewhere else (e.g. the KPICalculators).
     output_slot_names = List(String(), visible=False)
 
+    #: This event claims that a change in the model influences the slots
+    #: (either input or output). It must be triggered every time a specific
+    #: option in your model implies a change in the slots. The UI will detect
+    #: this and adapt the visual entries.
+    changes_slots = Event()
+
     def __init__(self, factory, *args, **kwargs):
         self.factory = factory
         super(BaseKPICalculatorModel, self).__init__(*args, **kwargs)