{"id":19881410,"url":"https://github.com/giscience/ors-map-client","last_synced_at":"2025-04-05T00:10:10.985Z","repository":{"id":37425697,"uuid":"278134196","full_name":"GIScience/ors-map-client","owner":"GIScience","description":"Openrouteservice API web SPA client using VueJS, Vuetify and Vue2Leaflet","archived":false,"fork":false,"pushed_at":"2024-10-22T13:58:24.000Z","size":56976,"stargazers_count":111,"open_issues_count":83,"forks_count":33,"subscribers_count":18,"default_branch":"main","last_synced_at":"2024-11-12T17:51:28.403Z","etag":null,"topics":["api","directions","isochrones","ors","places","routing","spa"],"latest_commit_sha":null,"homepage":"http://maps.openrouteservice.org","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/GIScience.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-07-08T16:01:03.000Z","updated_at":"2024-11-06T22:21:28.000Z","dependencies_parsed_at":"2023-02-16T08:31:39.981Z","dependency_job_id":"bb812fce-df58-4d57-b645-85002dc55b5b","html_url":"https://github.com/GIScience/ors-map-client","commit_stats":null,"previous_names":[],"tags_count":68,"template":true,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GIScience%2Fors-map-client","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GIScience%2Fors-map-client/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GIScience%2Fors-map-client/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GIScience%2Fors-map-client/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/GIScience","download_url":"https://codeload.github.com/GIScience/ors-map-client/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247266565,"owners_count":20910836,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","directions","isochrones","ors","places","routing","spa"],"created_at":"2024-11-12T17:14:09.490Z","updated_at":"2025-04-05T00:10:10.957Z","avatar_url":"https://github.com/GIScience.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ORS map client\n\n[![Test](https://github.com/GIScience/ors-map-client/actions/workflows/test.yml/badge.svg)](https://github.com/GIScience/ors-map-client/actions/workflows/test.yml)\n\nThis application implements a map client for the [openrouteservice API](https://openrouteservice.org/dev/#/api-docs/) as\nSingle Page Application (SPA). It is a base application that can be used for multiple purposes,\ncustomized via configurations and extended via plug-ins.\n\nThe base application is using Vue.js, Vuetify and a set of custom components, directives and services.\nThe structure uses a feature-by-folder design, allowing view, code and translation elements to be contained in a folder.\n\nThis app uses single file components and others non-native javascript code that are transpiled to native javascript\nduring the build process.\nTherefore, the app needs to be compiled before running it either in dev or production mode.\nThe Vue.js components allow a better code organization, weak and clear coupling between components and an easier\ncode understanding.\n\n![ORS map client](docs/ors-map-client.png?raw=true \"ORS map client\")\n\n## Set up and run\n\nThe app can be run with `docker`, `docker-compose`, and `natively`.\n\nFirst of all, checkout the repository to get the relevant code:\n\n```sh\ngit clone https://github.com/GIScience/ors-map-client.git\n# Go to your local repository root folder\ncd ors-map-client\n```\n\n### Configure\n\nIn order to run the app either with `docker`, `docker-compose`, or `native`, you have to configure you application\nfirst.\n\n1. Copy the files in the `src/config-example` to `src/config`, without `-example` in their names. The files are:\n\n   - app-config-`example`.js =\u003e **app-config.js**\n   - ors-map-filters`-example`.js =\u003e **ors-map-filters.js**\n   - layer-zoom-mapping`-example`.js =\u003e **layer-zoom-mapping.js**\n   - hooks`-example`.js =\u003e **hooks.js**\n   - theme`-example`.js =\u003e **theme.js**\n   - default-map-settings`-example`.js =\u003e **default-map-settings.js**\n   - settings-options`-example`.js =\u003e **settings-options.js**\n\n   If you are using a linux/unix compatible terminal, you can do that by running:\n\n   ```sh\n   cd src \u0026\u0026 cp config-examples/* config \u0026\u0026 for i in config/*-example.js; do mv -- \"$i\" \"${i%-example.js}.js\"; done\n   ```\n\n2. Set the app-config.js values for `orsApiKey` to be used when not running the app from valid ors domains\n\n3. The ORS menu is loaded/used by default. If you want to use a custom menu, have a look in the `hooks-example.js`.\n\nThe filters, theme and hooks of the map client can be [customized](#configuration-theming-customization-and-extension)\nif needed.\n\n### Run with `Docker`\n\n```shell\n# Build the image\ndocker build --tag ors-map-client:local .\n\n# Run a container\ndocker run -d -it -v \"$(pwd)\"/nginx/logs:/var/log/nginx:rw -p 127.0.0.1:8080:80 --name ors-map-client ors-map-client:local\n\n# Check the logs with\ndocker logs --follow ors-map-client\n```\n\nThe app should now be running at http://127.0.0.1:8080.\n\n### Run with `docker-compose`\n\n```shell\n# Build and run the image\ndocker-compose up -d\n\n# Check the logs with\ndocker-compose logs -ft\n```\n\nThe app should now be running at http://127.0.0.1:8080.\n\n### Run `natively`\n\nRun the app locally without docker in three steps: set the environment up, and define a configuration file.\n\n1. To manage dependencies and pack the app it is necessary to have Node version 16.\n   If you already have it, skip this step.\n   If you don't, please install it by running:\n\n```sh\ncurl -sL https://deb.nodesource.com/setup_16.x | bash - \u0026\u0026 \\\napt-get update \u0026\u0026 \\\napt-get install -y nodejs \u0026\u0026 \\\nnpm install -g pnpm \u0026\u0026 \\\nnpm update -g\n# The installation of dependencies is required before running the app:\npnpm install\n```\n\nAt this point the app is ready to run in `dev` mode. Do it by executing the following command in the app root folder:\n\n```sh\npnpm dev\n# This will start a standalone http node server and the host and port to access it will be displayed\n```\n\n## Build and deploy\n\nThe app must be built before it is deployed. To do so, run:\n\n```sh\ncd \u003cproject-root-folder\u003e/\npnpm build\n```\n\nThe built files are meant to be served by a web server like nginx or apache.\nYou can try if everything works locally e.g. with:\n\n```sh\npnpx http-server .\n```\n\n## Tests\n\nTesting is done using the [cypress](https://docs.cypress.io) testing framework.\n\nAll tests (End-to-end(e2e), component and unit) can be executed by running:\n\n```sh\npnpm test:ci\n```\n\nDuring development, you start the development server and use the following command which opens the cypress UI interface\nto view the test output and hot reload after making changes:\n\n```shell\n# and do 'pnpm dev' before\npnpm test\n```\n\nYou can run tests in any standard browser that you have installed.\nIf you are new to cypress check out\nthe \"[Getting started](https://docs.cypress.io/guides/getting-started/opening-the-app)\"\ndocumentation, and keep it close.\nAn overview on the usable [assertions](https://docs.cypress.io/guides/references/assertions) will help with simple\ntest cases.\n\n### Structure\n\nComponent tests should be written in the component itself e.g.\n`../fragments/MyComponent.cy.js` for `../fragments/MyComponent.vue`\n\nUnit tests for js source files should be created in a separate `./__tests__` folder next to the source file and for the\nsake of\nclarity be named the same e.g. `../support/__tests__/utils.cy.js` for `../support/utils.js`\n\nEnd-to-end tests should be created in `./cypress/e2e/test-name.cy.js`\n\n## Report a bug\n\nIf you identified a bug, please [create an issue](https://github.com/GIScience/ors-map-client/issues/new) with thorough\ndescription\nand steps to reproduce it (e.g. URL, Screenshot or Screen recording). Feel free to [contribute a fix](#contribute)\n\n## Feature improvements\n\nIf you have an idea for a new feature or want to improve an existing one, please also\n[create an issue](https://github.com/GIScience/ors-map-client/issues/new) first to discuss the idea.\nWe are happy if you also want to [contribute](#contribute) a pull request.\n\n## Contribute\n\nTo better understand and navigate the codebase best get to know the [project structure](docs/project-structure.md) first.\nMake sure to [set up](#set-up-and-run) and [configure](#configuration) the project, branch of current `main` and prefix\nyour branch name with `feat/` for features and `fix/` for bug fixes e.g.\n\n```sh\ngit switch -c feat/leaflet-control-for-statistics\n# or\ngit switch -c fix/map-moving-all-the-time\n```\n\n### set up pre-commit git hooks\n\nWe use `pre-commit` to make sure contributions have the same basic quality.\nBefore you commit make sure that your commit satisfies all `pre-commit` checks.\nFor details on individual checks see `.pre-commit-config.yaml`.\n\n```bash\n# Install the pre-commit git hooks to be automatically executed before committing.\npre-commit install --hook-type commit-msg --hook-type pre-push --hook-type pre-commit\n# Manually run all pre-commits. The first execution will setup the environment and can take some time.\npre-commit run --all\n```\n\n### Commits\n\n- This app uses [conventional commit syntax](https://www.conventionalcommits.org/en/v1.0.0/#summary) to automate\n  changelog entries.\n  You can use e.g. [conventional-commits-plugin](https://plugins.jetbrains.com/plugin/13389-conventional-commit) for\n  JetBrains IDEs or a global installation of the [commitizen npm package](https://github.com/commitizen/cz-cli) to help\n  you with the syntax.\n\n\u003e Note:\n\u003e Don't add `closing` or `fixes` keywords in commits but rather tag the issue in the pull request that solves it.\n\u003e This avoids multiple references in the issues after your branch is rebased on newer changes.\n\n### Add language\n\n#### Generate a translation file\n\nIf you just want to translate the application strings for a certain language, but you don't have the skills to `\"code\"`\nit into the app, just download the [en-translation-source-merged.json](/docs/en-translation-source-merged.json),\ntranslate it, and contact us.\n\n\\*_Check the file [src/i18n/i18n-builder.js](src/i18n/i18n-builder.js) to see how to generate merged translation\nsources_\n\n#### Add a language to the app\n\nThe app uses a feature-by-folder design, so each component might have its own translation strings.\nThat is why there is no single translation file. If you want to add a translation and `\"implement\"` it into the app,\nfollow the steps below.\n\n- Create a copy of the /src/i18n/translations/`en-us` folder giving it the identification of the target language.\n  For example: if you are adding the French from France, then the folder should be called `fr-fr`.\n\n- Edit the `builder.js` file inside the just created folder in order to replace the language pattern to the one you are\n  creating.\n  For example, similar to `/\\.i18n\\.en-us\\.js$` add `/\\.i18n\\.fr-fr\\.js$`.\n\n- Translate the language strings for each key in the `global.js` file\n\n- Search for each file inside the `/src` folder that ends with `i18n.en-us.js` and create a copy of it and each one so\n  that each new created file now ends with `i18n.fr-fr.js`. If you are using a linux/unix compatible terminal, you can\n  do that by running:\n\n  ```sh\n  find . -name \"*i18n.en-us.js\" -exec bash -c 'cp \"$0\" \"${0/i18n.en-us.js/i18n.fr-fr.js}\"' {} \\;\n  # where the last occurrence of locale id (in this case `fr-fr`) is the one you are creating\n  ```\n\n- Translate the language strings for each key in all the files created in the previous step.\n\n- Edit `/src/config/settings-options.js` and add the new locale object to the `appLocales` array (e.g.\n  `{ text: 'Français FR', value: 'fr-fr' }`).\n\n- Open the src/i18n/`i18n-builder.js` file and apply the following changes:\n\n  - Import the object from the new language builder that you just created\n    (e.g. `import frFRTranslations from './translations/fr-fr/builder'`)\n\n  - Inside the `build` method, add:\n\n    - the new language placeholder object to the messages object (e.g. `, 'fr-fr': {}`).\n\n    - the result of the new language building to the previously created message object\n      (e.g. `i18n.messages['fr-fr'] = frFRTranslations.build()`).\n\n  - Save all the files changed and rebuild the application.\n\n### Debug\n\nIf you are using [WebStorm](https://www.jetbrains.com/webstorm/download) you should set the\n_webpack config_ (settings -\u003e Languages \u0026 Frameworks -\u003e JavaScript -\u003e Webpack) to\n`{path to ors-map-client}/build/webpack.base.conf.js` to resolve file paths correctly.\n\nTo debug the application you must run it in [`dev` mode](#set-up-and-run).\nFor better debugging in your browser install the [Vue.js devtools](https://github.com/vuejs/vue-devtools#installation)\nextension.\nAfter doing that, open the application in the browser and press F12 and select the tab `Console`, `Vue` or `Sources`\n(and then expand e.g.: `webpack://src`).\n\n### USB debugging\n\nTo debug the client on a mobile phone you can follow\ne.g. [this guide](https://chenhuijing.com/blog/debugging-firefox-on-android/#%F0%9F%8F%80).\n\n## Releasing a new Version\n\n1. Create a `chore/release-v*.*.*` branch with the new version from `main` branch (\n   use [semantic versioning](https://semver.org/))\n   ```sh\n   git checkout main \u0026\u0026 git switch -c chore/release-v*.*.*\n   ```\n2. Run the release script to bump version, create changelog entries and release tag\n   ```sh\n   pnpm release\n   ```\n3. Make sure the changelog \u0026 version is what you expected and adjust if needed\n   - adjust branch name: `git branch -m chore/release-\u003cnew-version\u003e`\n   - adjust changelog or version in files. Then amend commit and re-tag:\n     ```sh\n     git commit --amend\n     git tag -fa v*.*.* -m 'v*.*.*'\n     ```\n4. Push the release branch to remote\n   ```sh\n   git push --set-upstream origin $(git_current_branch)\n   ```\n5. Click on the link to open a pull request for the release branch, create it and link relevant issues\n\n\u003e Note:\n\u003e Pre-commit hooks and test:ci tasks are run for every pull request and any change to it.\n\n## Deployment\n\nDeployments happen automatically if the conditions for\nthe [environment](https://github.com/GIScience/ors-map-client/settings/environments) are met:\n\n| Environment | Condition                                                     | Target                                    | Workflow dispatch  |\n| ----------- | ------------------------------------------------------------- | ----------------------------------------- | ------------------ |\n| Staging     | open pull request for / push to `chore/release-v*.*.*` branch | https://maps-staging.openrouteservice.org | :heavy_check_mark: |\n| Production  | merge `chore/release-v*.*.*` branch to `main`                 | https://maps.openrouteservice.org         | :heavy_check_mark: |\n| HEAL        | push to `heal` branch                                         | https://heal.openrouteservice.org         | :no_entry_sign:    |\n\nUse the workflow dispatch to deploy e.g. a feature branch to staging or an intermediate state of `main` to production.\n\n## Additional documentation\n\nThere is additional software documentation in the `/docs` folder:\n\n- [docs/project-structure.md](docs/project-structure.md) - explains the project \u0026 folder structure\n- [docs/dynamic-inputs.md](docs/dynamic-inputs.md) - describes how the inputs are rendered using a custom engine\n- [docs/search-results-criteria.md](docs/search-results-criteria.md) - explains the criteria for search results\n- [docs/plugins.md](docs/plugins.md) - explains how to add plugins\n\nFor a detailed explanation on how webpack works, check out the [guide](http://vuejs-templates.github.io/webpack/) and\n[docs for vue-loader](http://vuejs.github.io/vue-loader).\n\n### Configuration, theming, customization and extension\n\nThe map client app can be configured, customized and extended. Several aspects can be defined/changed in order to\ndisable features, customize visual identity and change/extend its features/behaviors.\nIt is also possible to add custom plug-ins to the app and subscribe to hooks, listen and emit events.\nThe items of the menu can also be customized via hooks.\n\nIt is possible to define your custom settings and plug-ins and keep getting updates from the ORS repository because\nthe `src/plugins` and `src/config` folders are not versioned.\nTo keep the original ors-map-client as a secondary repository, do the following:\n\n```sh\n# Rename the original remote\ngit remote rename origin ors-map-client-origin\n\n# Add your remote as the origin one\ngit remote add origin \u003cgit-repo-url\u003e\n\n# Set your new origin as the default upstream\ngit branch --set-upstream-to=origin/master\n```\n\nAfter doing this we recommend you to remove from `.gitignore` the lines that tell git to ignore the folders\n`/src/config`, `src/plugins` and eventually `/static`.\nThen, run the initial push to the just defined new origin repository, with the following command:\n\n```sh\ngit push -u origin master\n```\n\nThe ways to change/extend the app are:\n\n1. Define custom settings (see files in `src/config`) that will change the standard way that the app works.\n2. Add hook listeners in `src/config/hooks.js` and run custom code inside those hooks\n3. Create a plug-in that has its methods linked to hooks called during the app flow\n   (see `src/plugins/example-plugin/`)\n\n#### Configuration\n\nIt is possible to configure/disable some app features and behaviors by changing the values\nof the `src/config/app-config.js`. It is also possible to change the app theme/colors by changing the values of\n`src/config/theme.js`.\nThe app logo can also be changed in the `src/config/app-config` file.\nThe available filters/options to be used in the services are defined in the `src/config/ors-map-filters.js`.\nThey can be adjusted according the needs. Other files can be used to adjust app configurations are the\n`layer-zoom-mapping.js`, `settings-options.js` and the `default-map-settings.js`.\n\n#### Plug-ins\n\nIt is possible to add plug-ins to the application in order to change its behavior or extend it.\nPlease check [docs/plugins.md](docs/plugins.md) for more details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgiscience%2Fors-map-client","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgiscience%2Fors-map-client","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgiscience%2Fors-map-client/lists"}