The Angular client for an acoustic workbench application.
Generally we try to stick to the Latest Stable Release (LSR) for all requirements and dependencies.
To install project dependencies run:
$ npm install
Normal development
$ npm start
Then open a web browser to https://development.ecosounds.org:4200
.
Server side rendering
$ npm run serve:ssr
Then open a web browser to http://localhost:4000
.
This website can be customised through the environment file located at ./src/assets/environment.json
(note: look at the docker section for deploying environment files). Here is a list of settings and some example values:
Parameter | Description | Example Value |
---|---|---|
endpoints.environment |
The environment for this instance. Currently used only for informational purposes. | development staging production |
endpoints.apiRoot |
Any API requests made from the app will use this value for its base and append routes to it | https://ecosounds.org https://ecosounds.org:3000 https://ecosounds.org/api |
endpoints.clientOrigin |
This is the origin of where the website will be hosted | https://ecosounds.org https://ecosounds.org:3000 |
endpoints.clientDir |
This is the directory on the clientOrigin which the website is hosted |
/website /web/angular |
keys.googleMaps |
Google maps API key | Check googles official setup guide |
keys.googleAnalytics |
Google analytics domain and tracking ID | Check googles official setup guide |
settings.brand.short |
This changes the logo branding of the website | Ecosounds |
settings.brand.long |
This changes the full length name of the website | Ecosounds - Acoustic Workbench |
settings.links |
This is a list of external links used throughout the website. Check the template for the list of modifiable links | |
settings.customMenu |
This is a list of custom menu items which changes the contents of the header with instance specific links. Check the template for examples |
To use the embedded Google Maps in both development and production, it is required that the keys.googleMaps
property is set.
If you have not set this value the embedded maps will not work, and an error will be thrown in the console with the message "Google Maps JavaScript API error: InvalidKeyMapError".
This project has a number of options when it comes to testing. For development we utilize the chrome browser for testing, however the application should support the following browsers: Chrome, Firefox, Edge. When attempting to test a specific file/component/service, either use the Test Explorer plugin for VSCode, or modify the src/test.ts
file so that its regex will find the file you wish to test.
Development Testing:
$ npm test
Chrome Browser Testing:
$ npm run test:chrome
Firefox Browser Testing:
$ npm run test:firefox
Edge (Chromium Based) Browser Testing:
$ npm run test:edge
All Supported Browsers Testing:
$ npm run test:all
On the completion of the unit tests, the system will automatically generate a code coverage report. You can view the report here: ./coverage/workbench-client/index.html
To build the application:
$ npm run build
To build the Server Side Renderer:
$ npm run build:ssr
Move the generated files from the /dist
directory to the required location.
When adding a library to the repository, you may wish to view its cost on the system. You can view the build size using the following command:
$ npm run stats
This will allow you to compare the bundle size impacts before and after the update by switching between checked out commits/branches.
Check our Wiki pages for help with common problems and using systems custom to our application.
Deploying to production can be as simple as copying the release assets to a statically served directory, setting up your routing, and adding an environment.json
file.
public
environment.json
and place it in the public/workbench-client/assets
directoryassets
folderNote: this configuration is a fully static SPA and may suffer from slow loading times and poor SEO.
Server side rendering allows a server to render the first page and send it to the browser while the rest of the application bundle downloads. To make this work you need to run our docker container which contains the web server. The docker repository for this website can be found here: https://hub.docker.com/repository/docker/qutecoacoustics/workbench-client
Template your environment.json
file, and example can be found at ./src/assets/environment.json
Run the following command (substituting in the path to your templated config file):
$ docker pull qutecoacoustics/workbench-client:latest
$ docker run -p 4000:4000 -v "$(pwd)/environment.json:/environment.json" qutecoacoustics/workbench-client:latest
Done!
To build the container locally for testing:
$ docker build -t qutecoacoustics/workbench-client .
$ docker run -p 4000:4000 -v "$(pwd)/environment.json:/environment.json" qutecoacoustics/workbench-client
$ docker run -p 4000:4000 -v "$(pwd)/environment.json:/environment.json" -e DEBUG=express:* qutecoacoustics/workbench-client
Apache License, Version 2.0
This work has been supported through several grants.
The most recent of which is the ARDC Platforms project. This project is currently sponsored by the Open Ecoacoustics ARDC Platforms project. See doi.org/10.47486/PL050 for more details.