Dashboard filters
*****************


Overview
========

Taranta allows changing device value on widgets on a dashboard at runtime.
More specifically, the user can define one or more filters within the dashboard,
each filter with a name, tag & default value. The dashboard can then be configured with widgets where,
instead of specifying the full device name, the user can use the ``tag`` value from one of the defined filter.
System internally replaces the filter [tag] with its corresponding default value.

To add more flexibility to this :doc:`/filter_widget` is used. A filter widget is used to control one dashboard filter.
Using Filter widget, a we can change the default value of a filter at runtime.
 
How to use dashboard filters
============================

Let's first create a filter, to create it, click on the dashboard configuration (config icon) next to dashboard name.
This will open a popup with Variables, Environment & Filter menu's.
Navigate to Filter menu, click on ``Add new filter`` button to add a new filter.

*Note: While adding filter, the system will automatically add square brackets around the tag field of the filter.*

\ |IMG1|\


Once a filter is added, its tag & default value can be updated at a later stage.
On this interface user can search, view, edit & delete filters associated with a dashboard.
Users can also change the default value of a filter from here.
To change the name of a filter, user has to delete the filter and re-create it with the new name.

*Note: While defining the filter, note the tag value, which would be used while configuring a widget as shown below:*

\ |IMG2|\

Filter basically replaces the [tag] value with its value. During edit mode on a dashboard,
a filter can be used in the widget inspector panel to configure a device.

In above image, we see the Attribute Plot widget, which is using the tag value **[station]** from ``MyFilter`` filter(default value: 2)
to define the attribute(test/tarantatestdevice/[station]/Power)
Here the system will replace the filter tag **[station]** by its default value **2**.
The Attribute Plots second line would be showing values for ``test/tarantatestdevice/2/Power`` attribute.
And we can say that Attribute Plot is subscribed to filter ``MyFilter`` for Power attribute.


\ |IMG3|\

This works well but how about changing the default value of filter in runtime. Such that Attribute Plot can pull Power values from ``test/tarantatestdevice/3`` device in run mode,
To do so :doc:`/filter_widget` is used. Drag the Filter Widget from the Widgets Library, link it to ``MyFilter`` as shown below:
we can also add some predefined values under Filter Option using "+" icon.


\ |IMG4|\

During run mode we can see the Filter widget with its default value (2) and the predefined value (3).

\ |IMG5|\


If you want the Attribute Plot widget to pull **Power** attributes value from **test/tarantatestdevice/3** instead of **test/tarantatestdevice/2**,
you will just have to change the filter widget's value to **3**.
After this Attribute Plot widget will render values for test/tarantatestdevice/3/Power attribute.
Also if the user want to change the filter widget value which is not present in the dropdown,
they just have to type the value and select that value from the dropdown.

\ |IMG6|\ 

Similarly as many as wigets can be subscribed to one or more filters as per our needs.
For eg. Below dashboard has two widgets subscribed to filter Myfilter (tag: [station], default value: 2) as below:

\ |IMG7|\

User can use as many filter while defining TRL (Tango Resource Locator) in a widget. Remember it should result in a valid device.
For eg. In below image, attribute display is using filter ``device class`` & ``device`` to define the TRL.

\ |IMG8|\

In run mode these two filters can be used by the Attribute Display to fetch attribute values,
giving them more flexibility when chosing different devices.

\ |IMG9|\


During run mode, If a user changes the value of a filter widget ("5" in our case), 
for which a device is not present, 
all the widgets that are using this filter will show a warning message (Device testdb://test/tarantatestdevice/5 is not available) on the hover.
The widget that has zero subscription to a valid device will be disabled (Attribute Display in below dashboard).

\ |IMG10|\


.. bottom of content

.. |IMG1| image:: _static/img/define_filter.png
   :height: 409 px
   :width: 699 px

.. |IMG2| image:: _static/img/subscribed_widget_edit.png
   :height: 437 px
   :width: 617 px

.. |IMG3| image:: _static/img/subscribed_widget_run.png
   :height: 347 px
   :width: 602 px

.. |IMG4| image:: _static/img/define_filter_widget.png
   :height: 418 px
   :width: 757 px

.. |IMG5| image:: _static/img/filter_widget_run_mode.png
   :height: 491 px
   :width: 562 px

.. |IMG6| image:: _static/img/filter_widget_change_value.png
   :height: 492 px
   :width: 565 px

.. |IMG7| image:: _static/img/multiple_widget_filter.png
   :height: 547 px
   :width: 865 px

.. |IMG8| image:: _static/img/multiple_filter_edit.png
   :height: 368 px
   :width: 586 px

.. |IMG9| image:: _static/img/multiple_filter_run.png
   :height: 368 px
   :width: 586 px

.. |IMG10| image:: _static/img/invalid_filter_Value.png
   :height: 501 px
   :width: 615 px