Dashboard Widget
================

Widget can be added to a specific dashboard by adding a new :class:`~dashboard_widgets.models.WidgetConfig`.

Config
------

Configuration specific to the selected widget type. Sample values:

- ``field_name`` - name of the field used in context of this widget (chart)

- ``field_name_top`` - name of the secondary field (top) used in context of this heat map

- ``field_names`` - same as ``field_name``, but multiple field names can be specified as an array. Generally all fields are used as default if not specified

- ``compliance`` - boolean (``true`` / ``false``), whether the widget should represent compliance values (otherwise count is used). Default: ``false``

- ``sub_observation`` - name of the subform used for this widget

- ``sub_observations`` - same as above, but allows selecting multiple subforms for widgets that support it. Must be an array. All subforms will be used if not specified in config.

- ``max_entries`` - limits data rendered by this widget to this many observations / rows (integer). If tvalue is not specified, there is no limit and all entries will be shown.

- ``count_entries`` - boolean (``true`` / ``false``), counting the number of observations with this field filled in against observations where it's not

- ``javascript_searchbar`` - boolean (``true`` / ``false``), displays an inline searchbar when the widget is viewed on a Public Dashboard. Case-insensitive. Rows where no data of any column matches the search term are hidden

.. note:: If field name is pluralized (field_names, sub_observations etc), it means that value must be an array. Exception: ``max_entries`` - is an integer


Filters
-------

Narrow down observations displayed in this widget. Use a json object to map field name to a value (or list of values) to filter by.

.. code-block:: json
    :caption: Example filters configuration with filtering on bool, text and array fields.

    {
        "boolean_field": true,
        "text_field": "test",
        "array_field": ["one", "two", "three"]
    }


Placeholders can be used to dynamically filter data based on system data or auditor currently viewing it.

- ``{auditor.pk}``: current auditor id

- ``{today}``: fetches current date ex: ``2023-01-01"``

- ``{now}``: Fetches current datetime ex: ``2023-01-01T00:00:00.000000+00:00``


.. code-block:: json
    :caption: Example filters configuration with filtering on bool, text and array fields.

    {
        "auditor_field": "{auditor.pk}",
        "date_field": "{today}",
        "datetime_field": "{now}",
    }

Alongside placeholders for date and datetime fields we can use certain lookups to filter data

Available lookups:

- ``gt``: Greater than
- ``gte``: Greater than or Equal

- ``lt``: Less than
- ``lte``: Less than or equal

.. code-block:: json
    :caption: Example filters configuration with filtering on bool, text and array fields.

    {
        "date_field__gt": "{today}",
        "datetime_field__gte": "{now}",
        "date_field__lt": "2023-01-01",
        "datetime_field__lte": "{now}",
    }