Merge pull request #534 from geoadmin/feat-docu-comp-api

Updated docu about composition API
geoadmin · Nov 16, 2023 · 7b12bae · 7b12bae
2 parents 3744dcd + 6db737d
commit 7b12bae
Show file tree

Hide file tree

Showing 14 changed files with 217 additions and 58 deletions.
diff --git a/.eslintrc.js b/.eslintrc.js
@@ -3,20 +3,26 @@ require('@rushstack/eslint-patch/modern-module-resolution')
 
 module.exports = {
     root: true,
-    extends: [
-        'plugin:vue/vue3-recommended',
-        'prettier',
-    ],
+    ignorePatterns: ['node_modules', '.github', 'dist'],
+    extends: ['plugin:vue/vue3-recommended', 'prettier'],
     env: {
         'vue/setup-compiler-macros': true,
     },
     overrides: [
         {
             files: ['cypress/integration/**.spec.{js,ts,jsx,tsx}'],
             extends: ['plugin:cypress/recommended'],
-            plugins: [
-                "cypress"
-            ],
+            plugins: ['cypress'],
+        },
+        {
+            files: ['*.md'],
+            excludedFiles: ['LICENSE.md'],
+            parser: 'eslint-plugin-markdownlint/parser',
+            extends: ['plugin:markdownlint/recommended'],
+            rules: {
+                'markdownlint/md013': 'off',
+                'markdownlint/md028': 'off',
+            },
         },
     ],
 }
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -39,8 +39,8 @@ This tag will be a bump in :
 
 CI is managed by AWS CodeBuild.
 
-- Every merge (commit) on `develop` will trigger a deploy on https://sys-map.dev.bgdi.ch/ by the CI
-- Every merge (commit) on `master` will trigger a deploy on https://sys-map.int.bgdi.ch/ by the CI
+- Every merge (commit) on `develop` will trigger a deploy on <https://sys-map.dev.bgdi.ch/> by the CI
+- Every merge (commit) on `master` will trigger a deploy on <https://sys-map.int.bgdi.ch/> by the CI
 
 ### structure/architecture of the app
 

diff --git a/LICENSE.md b/LICENSE.md
@@ -31,4 +31,3 @@ Portions of web-mapviewer are based on works by others. A non-extensive list:
 [Font Awesome Fonts](https://scripts.sil.org/OFL)
 
 [Font Awesome Code](https://opensource.org/licenses/MIT)
-
diff --git a/README.md b/README.md
@@ -2,8 +2,8 @@
 
 | Branch  | Status                                                                                                                                                                                                                                                                                                                      | Deployed version             |
 | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------- |
-| develop | ![Build Status](https://codebuild.eu-central-1.amazonaws.com/badges?uuid=eyJlbmNyeXB0ZWREYXRhIjoiSFlMY3hpUEwvTGkzMDJaMzF1QUdxUm54MmdvR3JKMzVTT3JDdHRaK2JLaXFNZkxjVkoyM3JOaE1DSkJuRzR2MU5RRDdMNFczMWVXSEgvd291cXNkS3dZPSIsIml2UGFyYW1ldGVyU3BlYyI6Im9qVDhwZ2h1VnhSOU5GWE0iLCJtYXRlcmlhbFNldFNlcmlhbCI6MX0%3D&branch=develop) | https://sys-map.dev.bgdi.ch/ |
-| master  | ![Build Status](https://codebuild.eu-central-1.amazonaws.com/badges?uuid=eyJlbmNyeXB0ZWREYXRhIjoiSFlMY3hpUEwvTGkzMDJaMzF1QUdxUm54MmdvR3JKMzVTT3JDdHRaK2JLaXFNZkxjVkoyM3JOaE1DSkJuRzR2MU5RRDdMNFczMWVXSEgvd291cXNkS3dZPSIsIml2UGFyYW1ldGVyU3BlYyI6Im9qVDhwZ2h1VnhSOU5GWE0iLCJtYXRlcmlhbFNldFNlcmlhbCI6MX0%3D&branch=master)  | https://sys-map.int.bgdi.ch/ |
+| develop | ![Build Status](https://codebuild.eu-central-1.amazonaws.com/badges?uuid=eyJlbmNyeXB0ZWREYXRhIjoiSFlMY3hpUEwvTGkzMDJaMzF1QUdxUm54MmdvR3JKMzVTT3JDdHRaK2JLaXFNZkxjVkoyM3JOaE1DSkJuRzR2MU5RRDdMNFczMWVXSEgvd291cXNkS3dZPSIsIml2UGFyYW1ldGVyU3BlYyI6Im9qVDhwZ2h1VnhSOU5GWE0iLCJtYXRlcmlhbFNldFNlcmlhbCI6MX0%3D&branch=develop) | <https://sys-map.dev.bgdi.ch/> |
+| master  | ![Build Status](https://codebuild.eu-central-1.amazonaws.com/badges?uuid=eyJlbmNyeXB0ZWREYXRhIjoiSFlMY3hpUEwvTGkzMDJaMzF1QUdxUm54MmdvR3JKMzVTT3JDdHRaK2JLaXFNZkxjVkoyM3JOaE1DSkJuRzR2MU5RRDdMNFczMWVXSEgvd291cXNkS3dZPSIsIml2UGFyYW1ldGVyU3BlYyI6Im9qVDhwZ2h1VnhSOU5GWE0iLCJtYXRlcmlhbFNldFNlcmlhbCI6MX0%3D&branch=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.
 
@@ -87,17 +87,67 @@ All project related architectural decision will be described in the folder [`/ad
 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
-    - imports
-    - props (input)
-    - store link (input)
-    - computed (transformation of inputs)
-    - life-cycle hooks (mounted and such)
-    - interaction with the user (was called `methods` in the OptionAPI)
 
-Components that are extensively edited should be rewritten using the Composition API
+- `<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
+  1. props (input)
+  1. data
+  1. store mapping (input)
+  1. computed (transformation of inputs)
+  1. watchs
+  1. life-cycle hooks (mounted and such)
+  1. interaction with the user (was called `methods` in the OptionAPI)
+
+```vue
+<script setup>
+// 1. First put the imports
+import { computed, defineProps, onMounted, ref, watch } from 'vue'
+import { useStore } from 'vuex'
+
+// 2. Put all the props (input)
+const {myProp} = defineProps({
+  myProp: {
+    type: Boolean
+    default: false
+  }
+})
+
+// 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
 
@@ -210,16 +260,18 @@ A [test link](https://github.com/geoadmin/web-mapviewer/blob/bug_update_doc_rega
 A bash script [deploy.sh](https://github.com/geoadmin/infra-terraform-bgdi-builder/blob/master/projects/web_mapviewer/scripts/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]
+```bash
+./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.
+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.
+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](https://github.com/geoadmin/infra-terraform-bgdi-builder/tree/master/projects/web_mapviewer#deploy-on-prod) and use the script from within `infra-terraform-bgdi-builder/projects/web_mapviewer` to deploy **manually**.
 

diff --git a/ROADMAP.md b/ROADMAP.md
@@ -1,46 +1,61 @@
 # Roadmap
 
-Geo.admin.ch, in particular the map viewer of the Geoportal Bund https://map.geo.admin.ch, is being used actively (80K visits/day) by the public, authorities and third parties in version [mf-geoadmin3](https://github.com/geoadmin/mf-geoadmin3) and covers all functions according to the currently valid [NGDI](https://cms.geo.admin.ch/www.e-geo.ch/archives/pdf_egeo_de/ngdigesamtkonzeptv2.0.pdf) concept.
+Geo.admin.ch, in particular the map viewer of the Geoportal Bund <https://map.geo.admin.ch>, is being used actively (80K visits/day) by the public, authorities and third parties in version [mf-geoadmin3](https://github.com/geoadmin/mf-geoadmin3) and covers all functions according to the currently valid [NGDI](https://cms.geo.admin.ch/www.e-geo.ch/archives/pdf_egeo_de/ngdigesamtkonzeptv2.0.pdf) concept.
 
 geo.admin.ch receives a large number of feature requests, both from inside federal offices and from the broader open-source community. At the same time, backend, services and viewer (frameworks version used such as angular, python, cesium etc ) of mf-geoadmin3 are at the end of their life cycle and must be replaced. We bring together representatives from authorites coordinating agency for Federal geographical information, [GCG](https://www.geo.admin.ch/gkg), and engineering to prioritize this list. As new projects come into the queue, we regularly position them based on relative priority to other projects. As work gets done, projects will move up in the queue.
 
 The projects below are not associated with a particular map.geo.admin.ch version. We'll release them on completion, and they will be part of a specific version based on our release schedule, following semantic versioning. For example, features are released in the next minor after they are complete, or the next major if they include breaking changes.
 
-### Done
-#### Create basic application structure
+## Done
+
+### Create basic application structure
+
 We are setting up JS Code Structure, a bare map viewer with panning and investigate PWA technologies. This includes a set up of CI/CD and deployment processes. To ease collaboration , basic documentation is implemented
 
 #### Basic mapviewer with MVP feature set
+
 A basic viewer consisting of basic Permalink,/ URL mgmt., basic dataset mgmt., basic infoboxes (incl improvements), basic drawing, basic iFrame support and basic 3D.
 
 #### Draw & measure functions
+
 We will redefine the user learning journeys and refresh the approach to Add symbol, Add text, Add line / polygon, Measure, Measure Azimut, Profile, Share drawing / KML
 
 ### In progress
+
 #### Map window
+
 We will redefine the user learning journeys and refresh the approach to change language, display coordinates/ show mouse positons, Zoom to rectangle, copyright and possibly fullscreen.
 
 #### Navigation & orientation
+
 We will redefine the user learning journeys and refresh the approach to Geographical search (centre on coordinates), Geographical search (place name or postcode),Geolocation,
 
 #### Selection and display of data
-We will redefine the user learning journeys and refresh the approach to Full text search for data, Search for data attributes, Topic switcher, Search for data (catalogue/topics), Change the cartographic background, Change the visibility of the selected dataset, Change the order of the selected datasets, Remove selected datasets, View additional information about a data-set. View information about an object on the map , View information about an object on the map including highly customized tooltips with logic and dynamic data fetching) (EXPERTTOOLTIP),  Position information, Aerial photography, Time slider, Time copy/compare.
+
+We will redefine the user learning journeys and refresh the approach to Full text search for data, Search for data attributes, Topic switcher, Search for data (catalogue/topics), Change the cartographic background, Change the visibility of the selected dataset, Change the order of the selected datasets, Remove selected datasets, View additional information about a data-set. View information about an object on the map , View information about an object on the map including highly customized tooltips with logic and dynamic data fetching) (EXPERTTOOLTIP), Position information, Aerial photography, Time slider, Time copy/compare.
 
 #### Linking & integration
+
 We will redefine the user learning journeys and refresh the approach to Send/save/iFrame of the current map, Save/send a link to an object, Use parameters to call up a map (incl. drawings, external ogc layers), Mobile, Mobile Add link to homescreen/App, Mobile Offline SAVE VIEW DELETE.
 
 ### Future
+
 #### 3D
+
 We will redefine the user learning journeys and refresh the approach to Navigation, Mouse position, Feature tooltip, WMS import: preset, WMS import: permalink, KML import, Time support vector, Time support Raster.
 
 #### Advanced functions
+
 We will redefine the user learning journeys and refresh the approach to Import preset, Import URL WMS/WMTS/GeoJSON and KML, import: PRINT, Import permalink, Compare, Keyboard shortcuts, Report problem, Landscape mode (mobile)
 
 #### Print
+
 We will redefine the user learning journeys and refresh the approach to Print and Printing grids and annotation
 
 #### 3D nextgen
+
 We will define the user learning journeys to shadow calculation
 
 #### Draw & measure functions nextgen
+
 We will define the user learning journeys to shadow snapping and routing
diff --git a/adr/2020_04_06_javascript_framework_choice.md b/adr/2020_04_06_javascript_framework_choice.md
@@ -1 +1,3 @@
-Please refer to https://github.com/geoadmin/doc-guidelines/blob/master/adr/2020_04_06_next_gen_viewer.md
+# Javascript Framework Choice
+
+Please refer to <https://github.com/geoadmin/doc-guidelines/blob/master/adr/2020_04_06_next_gen_viewer.md>
diff --git a/adr/2020_05_28_test_framework.md b/adr/2020_05_28_test_framework.md
@@ -29,7 +29,6 @@ Good alternative to Selenium, is compatible with Saucelab (we already have some
 
 This could also be a good cross browser testing framework, but the cross browser feature will be hard to have deployed on every developers' machine.
 
-
 ### Cypress
 
 Made by devs for devs.
@@ -39,7 +38,6 @@ Made by devs for devs.
 - Solid and clear documentation
 - Newest addition (2017) to the big frameworks (very active community)
 
-
 ## Decision
 
 After playing a bit with these frameworks, Cypress clearly had something for it.
@@ -49,7 +47,6 @@ The documentation is well maintained and complete, tests are described with Moch
 Cypress will be a great help during the development phase of the new viewer.
 But we have to keep in mind that it doesn't really do cross browser testing.
 
-
 ## Consequences
 
 We start to use Cypress as our Unit test and integration test framework.

diff --git a/adr/2021_03_16_url_param_structure.md b/adr/2021_03_16_url_param_structure.md
@@ -8,7 +8,7 @@
 
 The mapviewer application is configured with several URL parameters. The current format for the layer configuration looks as follows (example for topic "Snow"):
 
-```
+```text
 ...
 layers=ch.swisstopo.pixelkarte-farbe-winter,ch.swisstopo.hangneigung-ueber_30,ch.swisstopo-karto.hangneigung,ch.bafu.wrz-jagdbanngebiete_select,ch.bafu.wrz-wildruhezonen_portal,ch.bazl.gebirgslandeplaetze,ch.swisstopo.schneeschuhwandern,ch.swisstopo-karto.schneeschuhrouten,ch.swisstopo-karto.skitouren,ch.swisstopo.skitourenkarte-50.metadata,ch.bav.haltestellen-oev&
 layers_opacity=0.85,0.5,0.2,0.6,0.6,1,0.7,0.8,0.8,1,1&
@@ -18,7 +18,7 @@ layers_visibility=true,false,true,true,true,false,true,true,true,false,false
 
 and including layers with different timestamps probably also
 
-```
+```text
 layers_timestamp=18641231,,,
 ```
 
@@ -33,7 +33,7 @@ The current format has some limitations:
 
 The new format looks as follows (in the generic form):
 
-```
+```text
 layers={layerID1},{visibility=t|f},{opacity=%f};{layerID2},{visibility=t|f},{opacity=%f}
 ```
 
@@ -56,7 +56,7 @@ In case a wrong format is given, the errors are printed on the console.
 
 The above example boils down to the following (given that all opacity values are the defaults defined in the topic):
 
-```
+```text
 ...
 layers=ch.swisstopo.pixelkarte-farbe-winter;
 ch.swisstopo.hangneigung-ueber_30,f;

diff --git a/adr/2021_04_14_drawing_library.md b/adr/2021_04_14_drawing_library.md
@@ -30,4 +30,4 @@ This leaves us with the OpenLayers approach, that has already proven itself on t
 
 Development of the drawing module can now start with OpenLayers as its backbone.
 
-In order to make it clear it is a different module as the map module, we will inject the current OpenLayers map instance with [Vue's provide/inject](https://v3.vuejs.org/guide/component-provide-inject.html) 
+In order to make it clear it is a different module as the map module, we will inject the curren/component-provide-inject.html)
diff --git a/adr/2022_05_09_mobile_click_behavior.md b/adr/2022_05_09_mobile_click_behavior.md
@@ -10,7 +10,7 @@ Currently, a short click will switch the app in fullscreen mode. A long click (w
 
 The issue is that there is no location popup possibilities with that (or at least it's unwanted if it pops up after a long click). We need to rework that.
 
-# Decision
+## Decision
 
 - Mobile layout (menu must be opened through header button)
   - Single touch (click) : identify, if no feature found, fullscreen toggle
@@ -26,5 +26,5 @@ This would allow mobile users to use all the features we provide (identify, loca
 
 ## Links
 
-* [JIRA ticket this ADR is based on](https://jira.swisstopo.ch/browse/BGDIINF_SB-2235)
-* [JIRA ticket where this became a problem](https://jira.swisstopo.ch/browse/BGDIINF_SB-2323)
+- [JIRA ticket this ADR is based on](https://jira.swisstopo.ch/browse/BGDIINF_SB-2235)
+- [JIRA ticket where this became a problem](https://jira.swisstopo.ch/browse/BGDIINF_SB-2323)
diff --git a/adr/2023_11_08_vue_composition_api.md b/adr/2023_11_08_vue_composition_api.md
@@ -11,19 +11,19 @@ Composition API should help us, in many cases, to build more reusable portions o
 
 This, in return, gives new challenges as it doesn't force us to structure our component in the same way (props, computed, etc...) through the linter.
 
-# Decision
+## Decision
 
 We will now be using the Composition API for new components, and transform Option API components into Composition API when extensive work is required on them
 
 ## Consequences
 
 - New components should be written with the Composition API
-    - `<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
-        - imports
-        - props (input)
-        - store link (input)
-        - computed (transformation of inputs)
-        - life-cycle hooks (mounted and such)
-        - interaction with the user (was called `methods` in the OptionAPI)
-- Components that are extensively edited should be rewritten using the Composition API 
+  - `<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
+    - imports
+    - props (input)
+    - store link (input)
+    - computed (transformation of inputs)
+    - life-cycle hooks (mounted and such)
+    - interaction with the user (was called `methods` in the OptionAPI)
+- Components that are extensively edited should be rewritten using the Composition API