=====================
Dashboard boilerplate
=====================

To start using the dashboard boilerplate go to the `Cookiecutter template <https://gitlab.hevs.ch/SPL/miscellaneous/dashboard-boilerplate>`_ and follow the steps.


Application structure
=====================

The dashboard is a multi-pages application. Add your pages in the **pages** folder and create the associated menu
in the sidebar (no need to specifically import the page). Create separated elements you'll use several times or not in the **components** folder that you integrate into your pages.

Modify the appearance of your dashboard by adding custom CSS stylesheets in the **assets** folder or modify the
present stylesheets. Javascript files can be added to create specific functionalities that are executed on the user browser and not on the server. This can be useful sometimes to not overload the server or execute specific function
on the browser side.

If you need to create a documentation for your application, use the **help** section. Add markdown files
in the **help** folder and create the associated menu in the **help.py** page.


.. list-table:: Folders
    :widths: auto
    :header-rows: 1

    * - Folder
      - Description
    * - assets
      - Files automatically added by Dash in the application (CSS, javascript files, ...)
    * - components
      - Components used to build the different part of the application
    * - help
      - Contains markdown files for the `help` section of the dashboard
    * - pages
      - The different pages of the application
    * - static
      - Static elements like images, ...

The main logic to create the application is in the **app.py** file. The **app** object is then imported in the **index.py** file to run the application. The **layout.py** file contains the general structure of the interface and the logic to enable multi-pages. Import the **helpers.py** file whenever you create a components or a page. The **storage.py** file contains an important logic for the application and is described below in more detail.


.. list-table:: Files
    :widths: auto
    :header-rows: 1

    * - Folder
      - Description
    * - app.py
      - Main file of the application
    * - config.py
      - Configuration file for the application
    * - helpers.py
      - Most used imports and functions used in the code
    * - layout.py
      - The general layout of the dashboard
    * - storage.py
      - Create the storage of the application
    * - index.py
      - Entry point to start the application

Storage of the application
==========================

To build a more user friendly application and create interesting interactivity, we use the `dcc.Store <https://dash.plotly.com/dash-core-components/store>`_ element of Dash. It is used to `share data between the elements of your application <https://dash.plotly.com/sharing-data-between-callbacks>`_ through the callback system. And last but not least, it is used to store the state of the application between different usage within the same browser.

The dashboard use the local storage (``localStorage``) of the browser to store the variables. The actual state of that storage can be viewed by opening the Developers tools (F12 in most browser) and going to the `Application` tab. The **storage.py** creates the storage by reading user configured variables from the application's configuration file and by creating globally accessible interface related variables for the exchange of data between the components.

.. figure:: img/localstorage.png

   Browser localStorage


Debugging with VS code
======================

When opening the project in VS Code, hitting F5 will launch a debug session from where one can put breakpoints in the code and ... well, you can guess the rest.

Dash implements the *Code Reloading* and *Hot Reloading* mechanism which detects any change in your code to reload the app and refresh the browser automatically. Isn't it wonderful ;)

Find more information about the tools available to develop an Dash app by consulting the official `Dash Dev Tools <https://dash.plotly.com/devtools>`_ page, it is always the best source.

.. important::

    When the app reload and you encounter an invisible breakpoint due to a SystemExit exception while debugging with VSCode, simply disable the `Uncaught Exceptions` in the Breakpoints panel.

    .. figure:: img/vscode-error.png

    .. figure:: img/disable-uncaught-exceptions.png

:tag:`Python`
:tag:`Plotly Dash`
:tag:`Boilerplate`