web-mapviewer

Branch	CI Status	E2E Tests	Deployed version
develop			https://sys-map.dev.bgdi.ch/
master			https://sys-map.int.bgdi.ch/

The next generation map viewer application of geo.admin.ch: Digital data can be viewed, printed out, ordered and supplied by means of web-mapviewer. The required data is available in the form of digital maps and imagery, vector data and also as online services.

Table of Contents

• Table of Contents
• Roadmap
• Contributing
• Project structure
  • Best practices
  • Architectural decisions
  • Vue Composition API
  • Store module
  • Testing
• Project setup
  • Pre-Requirements
  • Install
  • Environment variables
  • Tooling for translation update
  • List of npm scripts
  • What about package-lock.json file?
• Project deployment
  • Automatic deploy
  • Manual deploy
• Check External Layer Provider list

Roadmap

See ROADMAP.md

Contributing

See CONTRIBUTING.md

Project structure

This is a Vue app that is served through src/main.js, using Vuex as a state manager. The app is divided into modules (or chunks) that are stored into src/modules. The goal is for each of these modules to be able to be externalized if needed. They should explicitly state their dependencies to other modules' component or store element in their README.md (dependency to the main store's modules is not required to be stated)

Each module should have a root component, called {Name of the module}Module.vue that loads all needed component into the template. It should also have a README.md file at the root explaining what this module is about.

To make the code easier to navigate and maintain we consolidated the complete state in one place (src/store/). The store is divided into modules that mostly correspond to the application modules but also include modules for state that is used by multiple modules or would be too big for a single file.

Store plugins can be used to react to store changes. See the store read-me for more information.

Here's a sample of what project folder structure looks like :

├── adr
│   └── all architectural decisions made over the course of this project
│
├── tests
│   └── all test files
│
├── public
│   └── all files that don't need pre processing before going public
│       (index.html, favicon, etc...)
│
├── scripts
│   └── NodeJS scripts useful for dev tools or for deploy
│       (used by NPM targets)
│
├── src
│   ├── main.js
│   ├── App.vue
│   ├── modules
│   │   ├── <Module name>
│   │   │   ├── index.js
│   │   │   └── other moduleName related files such as
│   │           a components folder or a store folder
│   ├── store
│   │   ├── modules
│   │   │   ├── <Module name>.js

Best practices

• Prefer primitive data or javascript plain object in reactive data (Vue Component data or refs, Vuex store data)
• Don't use complex object as reactive data
• Avoid using javascript getter and setter in class that are used in reactive data

See also Store Best Practices

Architectural decisions

All project related architectural decision will be described in the folder /adr (ADR stands for "Architectural Decision Report"). For all more macro decisions (like the CI we use or other broad subjects), please refer to the /adr folder on the project doc-guidelines.

Vue Composition API

New components should be written using the Vue Composition API.

The structure of the file should be :

• <script setup> tag should be the first tag of the .vue file (instead of <template>, that's the new best practice with this approach)
• declares things in this order in the <script setup> tag
  1. imports
  2. props (input)
  3. data
  4. store mapping (input)
  5. computed (transformation of inputs)
  6. watchs
  7. life-cycle hooks (mounted and such)
  8. interaction with the user (was called methods in the OptionAPI)

<script setup>
// 1. First put the imports
import { computed, onMounted, ref, toRefs, watch } from 'vue'
import { useStore } from 'vuex'

// 2. Put all the props (input)
const props = defineProps({
  myProp: {
    type: Boolean,
    default: false,
  },
})
const { myProp } = toRefs(props)

// 3. reactive data
const myData = ref('My reactive value')

// 4. Put then all store mapping (input)
const store = useStore()

// 5. Computed properties
const myComputed = computed(() => store.state.myValue)

// 6. Watchs
watch(myComputed, (newValue) => {
  // do something on myComputed changes
})

// 7. Life-cycle hooks
onMounted(() => {
  // write you code here
})

// 8. Methods
function myMethod() {}
</script>

<template>
  <!-- Write your template here -->
</template>

<style lang="scss" scoped>
// Write your styles here
</style>

Components that are extensively edited should be rewritten using the Composition API

Store module

As there can be only one instance of a Vuex's store per app, the store module is there for that. It as the responsibility to instantiate Vuex, and add any module related state data to the store. See its README.md for more details.

Testing

Unit testing is done through the VueCLI unit test helper, and integration testing is done with Cypress.io. All things related to tests are in the /tests folder. See README.md for more documentation on testing in this project.

Project setup

Pre-Requirements

The followings programs/tools are required in order to develop on web-mapviewer

• Nodejs 18
• npm 9

Install

npm install

Environment variables

Environment variables are defined in the following files

• .env.development
• .env.integration
• .env.prodcution

The first one is used by npm run dev as well as for all development modes. The second is used to build for and deploy to our integration server. Otherwise .env.production is used by default. For more information about loading environment variables see Vue - Modes and Environment Variables

Tooling for translation update

Our translation master is hosted in a Google Spreadsheet, thus if you want to update translations you will need a valid Google API Key. One can be found in our gopass store infra-gopass-bgdi.

For this purpose you will need to install gopass, and to be more efficient use it with summon.

In order for them to function together, they need to be linked with

mkdir /usr/local/lib/summon
ln -s $(which gopass) /usr/local/lib/summon/gopass

Translations can then be updated with

summon -p gopass npm run update:translations

The file secrets.yml will tell summon which keys to get from gopass.

List of npm scripts

All script commands starting a webserver or using one (dev and all things related to cypress) will determine the port to use by looking for the next one available starting at 8080.

What about package-lock.json file?

The CI uses this file to ensure it will not stumble upon a minor version of a library that breaks the app. So this file needs to be versioned, and kept up to date (each time a new library or version of a library is added to package.json, npm install will update package-lock.json accordingly).

The CI will use npm ci, which act like npm install but it ignores the file package.json and loads all libraries versions found in package-lock.json (which are not volatile, e.g. ^1.0.0 or ~1.0.0., but fixed).

Project deployment

The application is deployed on three targets : dev|int|prod

Automatic deploy

After every successful build, a version of develop and master are deployed automatically.

On the dev and int targets, deployment is done automatically via the CI for web-mapviewer.

A test link is also added to the description of every PR.

Manual deploy

A bash script deploy.sh is used for manual deploy, either from a local directory or a bucket from the CI.

./scripts/deploy.sh: --staging STAGING {--version VERSION | --local-src DIR} [--preview TEST_LINK]

Deploy web-mapviewer on the given staging. Either deploy a version from the
build-artifacts-swisstopo bucket (with --version option), or a local build version
using the --local-src DIR option.

OPTIONS:
  -h|--help               Print the help and exit.
  -s|--staging STAGING    Staging to deploy; dev|int|prod. Default; dev
  -v|--version VERSION    Version to deploy.

On prod, check deploy on prod and use the script from within infra-terraform-bgdi-builder/projects/web_mapviewer to deploy manually.

NOTE:
If deploying manually to prod, wait until the CI has finished building the project, as the deploy script only copy files.

Depending on the target (dev|int|prod), you will have to build and bundle/minify the app (for int and prod) or simply build the app without minification (for dev) prior to deplay (npm run build:(dev|int|prod))

• Only develop branch can be deployed at the root of the dev bucket.
• Only master branch can be deployed at the root of int and prod buckets.

Check External Layer Provider list

In the Import tool we provide an hardcoded list of provider via the src/modules/menu/components/advancedTools/ImportCatalogue/external-providers.json file. Because we have quite a lot of provider, we have a CLI tool in order to check their validity. The tool can also be used with a single url as input parameter to see the url would be valid for our application.

npm install
./scripts/check-external-layers-providers.js

You can use -h option to get more detail on the script.