Frontend for the COVID Impact Map
- Ensure you have NPM installed.
- Clone the repo locally.
- In a terminal run
npm install
in the directory where you cloned the repo. You should only have to do this once, unless you or someone else adds a dependency to the project, in which case you'll need to runnpm install
again before continuing to build.
In your local clone of the repo's directory, run npm run-script build if you're on Windows, or npm run-script build-nix if you're on MacOS/Unix.
Windows users, run npm run-script serve
. Mac/Unix users run npm run-script serve-nix
. This will build the solution, bundle all js and css, copy the index.html, and launch the site locally with webpack.
While the project is running, the dist folder will contain 3 files: index.html
, bundle.js
, and bundle.css
.
bundle.js will be automatically rebuilt will the server is running if you change any of the .ts
files, but any changes made to css files or index.html will not take effect until the server is restarted.
In your terminal window, press ctrl+c
to stop the server, then run npm run-script serve
(or npm run-script serve-nix
) to rebuild the project and start the server back up.
The UI is written in Typescript which is compiled to Javascript. The project makes use of the Web Components Javascript Standard, CSS, and, of course HTML.
It is not necessary to clone or build the full COVID Impact Map if you're just looking to work on the UI in development mode.
For production release, the UI is compiled via TS through Bazel's rules_nodejs, then rollup, then terser, but you don't need to install or understand these parts of the tool chain to work on the UI project!
The full app version of the Covid Impact Map that's pushed to production references this UI project as a dependency. (The UI's dependency info is defined in package.json, and the dependency is pulled into the main app via its config/build.bzl).
The architecture is based on a simplification of the Redux pattern.
-
Bootstrapper: Responsible for initializing dependencies, creating the AppMain view, and appending it to the document
-
Dispatcher: triggered by a view to dispatch a message (possibly with data attached) to the store.
-
Store: a central location that stores the state of the application. querying data when triggered, and notifying view observers. The store listens to messages from the dispatcher, updates itself accordingly (if applicable) and exposes observables which can be subscribed to when changes are made
-
Views are custom elements which render the UI. They define the template for custom html elements (such as single-hospital-details), listens to store updates by subscribing to observables exposed by the store then updates its own contents accordingly. The Views also send dispatch messages when applicable.
All custom views extend BaseView which itself extends HTMLElement from the Web Components Javascript Standard. The ViewRegistry class registers all custom elements and their selectors to the window. For example: the class SingleHospitalDetails is registered as single-hospital-details. Note: all view selectors are derived from their class names (pascal case => html-tag format).
All views are given their own randomly generated ID unless one is already specified.
The css folder has multiple css files, global.css and one for each view (unless a view does not need one). When the project is built, the css files are combined into one.