Template Panels App

Authors:

Mitchell Dickau -- mitchell.dickau@ec.gc.ca Eva Gnegy -- eva.gnegy@ec.gc.ca Jeremy Fyke -- jeremy.fyke@ec.gc.ca

Project description

This is a template for Panels apps that allow for data exploration, visualization, and download. Panels can be used to create a wide variety of apps and dashboards -- some examples can be found here. You'll see that some examples define apps as Python classes, and some apps are defined and Python functions. In this app template, we define our app as a class because, although it is slightly more complicated, this method allows for more dynamic functionallity.

Requirements

Local:

• Miniforge
• Mamba
• Create environment from `requirements.txt
  • mamba env create --name panel --file=requirements.txt

In PAVICS:

• None, the environment is pre-configured

How to serve the app

Locally

• Open Miniforge
• Navigate to repository directory
• Activate the environment you created in requirements
  • mamba activate panel
• Run panel serve --static-dirs assets=./assets --port=39998 --allow-websocket-origin=* app.py --dev

In PAVICS

To serve the template app and explore it's features, you can run the code in 'kill.ipynb' file, then run the code in 'serve.ipynb'. If you're using PAVICS, you can see the site you just served via https://pavics.ouranos.ca/jupyter/user-redirect/proxy/39158/app (this link is also in the 'serve.ipynb' file)

Once you have served the app, start customizing individual pages to explore Panels functionality.

App basics

Basic structure

The main code for the app is in the 'app.py' file. Within the 'app.py' file four modules are called which each represent the 'pages' that are listed on the sidebar menu in the app. Each of the four pages in the template app -- Text, Widgets, Plotting, and Dynamic plotting -- are listed in the directory as 'page[page name].py'. Within each page '.py' file is a class that defines the page.

Text and translation

We expect this template to primarily be used for apps on ClimateData.ca, which means that they should be available both in English and French. In this template app, the 'translation_module.py' module is imported in every 'page' so that translations can be doen easily when the user selected language, known as the LOCALE, is changed. See translation_module.py file for an example of how individual strings or larger texts stored as markdown files can be translated using this module.

'utils.py' module to store reusable functions

We expect many apps will have functions that are continuously used (e.g., plotting functions). Please use the 'utils.py' file to store functions that you call into multiple pages in your app.

Adding new pages:

1. Create a copy of one of the page*.py files, and rename it to your desired page name
2. In app.py
   • Add import _page_{your_page_file_name} at beginning of file
3. Add your page to the Pages enum
4. Add your page to the populate_main menu selector logic
5. Add markdown translations of your new page to directory docs/
6. Add translation file names to translation_keys.csv