Plotly dashboard template

A template repository for creating data dashboards with Plotly.

This is a template, and should not be overwritten. There are instructions below on how to set up your own development repository.

Getting started

Creating a copy of the template

1. Choose a name for the repository to house your code. Please note this name should conform to snake case (e.g. example_data_dashboard) to avoid annoying errors later!
2. Create a new repository to house your dashboard from this template, instructions can be found here. Do not overwrite this template repository.
3. Update code with appropriate names everywhere #UPDATE can be found in template.

Configuring GitHub policies

By default, GitHub does not apply any branch protection policies to newly created repositories. We use these policies to enforce things like: Requiring pull requests to commit changes into the main branch, requiring any comments on pull requests to be resolved and requiring status checks to pass before pull requests can be merged.

1. Open the Settings menu for your GitHub repository (Your user needs to be assigned the Admin role to see this option. If it's missing contact your GitHub owner for permission)

   

2. Click the Add branch protection rule button

   

3. Set the options in the below screenshot

   

Installation

Getting Started

Set up your local development environment (DLUHC set up - others may vary)

Note: This section only needs completing once

1. Set your default browser to Google Chrome - instructions.

2. Open Anaconda Navigator via Start menu. Note: Anaconda asks if you want to update it, but it won't work.

3. Install and launch VS Code (Visual Studio Code) from within the Anaconda Navigator. Note after installing VS Code, a Getting Started walkthrough is shown. Click the back button to escape.

4. Navigate to the Git CMD from the start menu and execute the below commands. Once you have executed the commands close Git CMD.

   Note: You need to change the name/email to match your own and you need to include the quotation marks. You may like to copy the commands into a word document to edit them.

git config --global user.name "Your Name"
git config --global user.email "Your.Name@levellingup.gov.uk"

Downloading the code from GitHub

1. Create a folder on your desktop, for storing source code within if you don't have one already.
2. From VS Code open the Explorer window, the overlapping pages icon on left hand menu. Select the option to "Clone Repository". Click "Clone from GitHub"
3. If prompted, authorize with GitHub.
4. You should be prompted to enter a repository name. Type "communitiesuk/<Your repository name>". Then click on communitiesuk/<Your repository name>.
5. As a destination, select your folder for storing the source code. Select "Sign in with browser" if the GitHub authorisation popup is shown.
6. This pulls the code from GitHub to your local folder. Click "Open folder" option, and navigate to your newly created folder containing the repository code.
7. Select "Yes, I trust the authors".

Installing packages

1. Open a command prompt terminal within VS Code, in which you'll start executing some commands. By default, the initial terminal will be a powershell terminal, and you will need to switch to a command prompt shell.
2. Update the name field in environment.yml to the dashboard name
3. Create a new conda environment by typing conda env create -f environment.yml into the terminal and executing the command by pressing the Enter key.
4. Activate your conda environment with conda activate <dashboard name>
5. Close VS Code. Open Anaconda Navigator, select "< Dashboard name >" for the 'Application on' drop down menu, then select "Launch" VS Code. Click the bin icon on the terminal toolbar to close the terminal. Click the plus icon on the terminal toolbar to launch a new terminal.
6. Install the Microsoft Python extension for VS Code.
7. Follow the instructions for configuring the Python interpreter.

Configuring GitHub triggers

1. Navigate to check-before-merging.yml in the workflows folder
2. Uncomment the GitHub triggers for the Automated checks
3. Update the application-name environment variable to the application name, which should match the value set in the dashboard.

Setting environment variables

1. From VS Code, open the .env file. If this file does not exist, then create it at the root of the project. The .env file is excluded from git commits, so can contain secrets such as AWS Access keys as they will only be present on an individual developer laptop
2. Inside the .env file, add the new environment variable in the format ENVIRONMENT_VARIABLE=VALUE. An example is STAGE="production". There is a file called .env.example that be used for reference

Running the application

1. From your VS Code terminal, execute python run.py

2. Wait for the message "Dash is running on ..." message to appear

3. Navigate to http://localhost:8080/ in your browser within the AWS workspace. Note that http://localhost:8080/ is the address that dash will run on in your local machine.

4. Use Ctrl-C in the terminal to quit the python server.

   Note: Terminal can only handle one command at a time, if the python server is running the terminal will not handle any further commands. To restart the server use python run.py

Github Action workflows

The .github folder contains a range of workflows that may be useful in a new project. They will need updating to run correctly within Github. The files should be deleted if the specific workflow is not desired.

• after-merging.yml can be used to run accessibility checks on the dashboard via Cypress. This requires a Github secret to be set, secrets.CYPRESS_BASE_URL.
• attach-to-trello.yml is used to attach information about a pull request to its relevant Trello ticket. Trello key and token Github secrets are required for the Action to be able to connect to Trello.
• check-before-merging.yml runs the Python formatter, linter and tests on each pull request. It is advised that Github is configured so that PRs can't be merged unless these pass.
• dependabot-pr-merge.yml approves and merges PRs created by dependabot that are minor or patch changes to the current version of a package specified in requirements.txt.

Customisation

Adding figure to dashboard

1. Create figure function for specific chart type and save in figure folder on dashboard file
2. Set a variable equal to the figure function and pass in the necessary parameters
3. In order to return a graph, set a new variable and pass in dcc.Graph(with the id of your new figure)

barchart = bar_chart(df, "Category", "Value", color="Category")
barchart_dash = dcc.Graph(id="example bar chart", responsive=True, figure=barchart)
dashboard_content = [card(barchart_dash)]

Development

Running tests

Writing and running automated tests ensures software is correct, reduces risk that users will experience bugs, and allows developers to move much faster as they can make changes with confidence that any breaks will be caught be the test suite. Once you have set up unit tests:

python -u -m pytest tests

Running the code formatter

The code formatter ensures source code is formatted consistently. Running the code formatter makes changes automatically that then need to be committed.

black ./

Running the linter

The linter checks for basic logic errors and bugs. Linting reports rule violations that must be corrected manually.

pylint <Dashboard name>