GET_STARTED.md

Getting Started

Requirements

• Node 16
• Npm 8

Setup

Run the following scripts using npm run to setup your development environment.

• start serves a development server at http://localhost:8080. By default, the app.config.json is used to start the map. You can provide alternative --modules if you wish. npm start -- --host -- --module "config/www.config.json" --module "config/dev.config.json" will load the map with the above two modules loaded.
• lint runs eslint for linting.
• build runs a build script, builds all javascript libraries to the dist folder. This is done for publishing the @vcmap/ui npm package.
• build-preview builds all javascript libraries including all plugins to the dist folder.
• preview serves the content of the dist folder at http://localhost:4173. Can be used to check the build application. Don't forget to run build and build-preview before using the preview command! You can provide a plugin-regsitry (e.g. a VC Publisher) from which to pull plugins instead of using the currently built ones. npm run preview -- --host -- --plugin-registry http://localhost:3000 will pull plugins from a publisher running locally.
• install-plugins to integrate externally managed and developed plugins, use the plugins/package.json and this script to install them.

NPM Link

Before linking a package, delete the vitejs dependency Cache in node_modules/.vite/. Otherwise vitejs will still use the optimized dependency

To develop @vcmap/core at the same time, you can integrate it using npm link.

• call npm link in the @vcmap/core folder
• call npm link @vcmap/core in the @vcmap/ui folder

To develop @vcmap/core and @vcmap/cesium at the same time use.

• prepare @vcmap/cesium
  • install dependencies npm i
  • build cesium npm run release
  • call npm link in the @vcmap/cesium folder
• prepare @vcmap/core
  • install dependencies npm i
  • call npm link
• call npm link @vcmap/core @vcmap/cesium in the @vcmap/ui folder

For Source direct debuggable openlayers Source Code change the vite.config.js file and replace the optimizeDeps with the following snippet:

    optimizeDeps: {
      exclude: [
        'ol',
      ],
      include: [
        'ol > pbf',
      ],
    },

Or you can set the convenient env variable NO_OPTIMIZED_CORE environment variable to not optimize @vcmap/core`.

NO_OPTIMIZED_CORE=true npm start

Setting up IDE

Make sure ESlint and prettier are activated

Webstorm

• eslint

Settings: Languages & Frameworks/JavaScript/CodeQuality Tools/ESLint
- set Eslint configuration: Automatic EsLint Configuration

• prettier

Settings: Languages & Frameworks/JavaScript/Prettier
- set Prettier configuration: Automatic Prettier Configuration

• select the node_modules/@vcmap/core package, right click and check Include JavaScript Files to jump to code instead of index.d.ts.

VS Code

• eslint:

Side Panel: Extensions > Search for EsLint > Install

• prettier

Side Panel: Extensions > Search for Prettier > Install
Settings: Default Formatter: Prettier

FormatOnSave does not work for Vue files in VS Code. Use shortcut "shift-alt-f" instead.

Testing

To run the whole test Suite call npm run test; see vitest for API and testing documentation.

Use of JSDoc

We use jsdoc for a) documentation of our public API and b) for typechecking our JS code using the typescript compiler. To enforce these rules we use the eslint jsdoc plugin.

• You should add jsdoc doclets to:
  • Classes, function, enums and module scope constants
  • Class properties
  • Class methods
• You should add generic types to generics, such as Array, Object, Promise etc. (Array<string>).
• You should add access tags to @private or @protected methods and properties. @public is implied for the rest.
• You should tag getters with @type and not @returns.
• You should denote properties which only have a getter with @readonly.
• Exporting Symbols:
  • All exported functions/Classes will be added to the index.js in the build step.
  • use @private to not add an exported function the index.js
• You should use the preferred tags outlined by eslint jsdpc plugin , with the following exceptions: @extends over @augments and @const over @constant.
• You should type inherited methods for typescript and add @inheritDoc to use the parents description in the docs (if they are the same). This makes it easier to maintain descriptions and keeps them consistent.

Overview UI Elements

RED: ButtonLocation; GREEN: WindowSlot; ORANGE: Toolbox; BLACK: other elements (not complete)

Documentation

1. Actions
2. Attributions
3. Buttons
4. Callbacks
5. Categories
6. Collections
7. Content Tree
8. Context Menu
9. Feature Info
10. Fonts
11. Help
12. Init
13. Internationalization
14. Legend
15. Notifier
16. Search
17. State
18. Toolbox
19. UI Colors
20. UI Components & Styles
21. UI Configuration
22. Windows