{"id":20198515,"url":"https://github.com/eclipsesource/tabris-plugin-maps","last_synced_at":"2025-04-10T10:52:58.793Z","repository":{"id":35510600,"uuid":"39780766","full_name":"eclipsesource/tabris-plugin-maps","owner":"eclipsesource","description":"Maps plugin for Tabris.js","archived":false,"fork":false,"pushed_at":"2024-02-21T15:51:50.000Z","size":663,"stargazers_count":16,"open_issues_count":9,"forks_count":11,"subscribers_count":17,"default_branch":"master","last_synced_at":"2025-04-08T20:48:09.827Z","etag":null,"topics":["android","cordova-plugin","geolocation","map","tabris","tabris-js","widget"],"latest_commit_sha":null,"homepage":"","language":"Kotlin","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/eclipsesource.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}},"created_at":"2015-07-27T15:03:09.000Z","updated_at":"2025-03-30T01:51:39.000Z","dependencies_parsed_at":"2022-09-06T06:50:51.755Z","dependency_job_id":null,"html_url":"https://github.com/eclipsesource/tabris-plugin-maps","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eclipsesource%2Ftabris-plugin-maps","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eclipsesource%2Ftabris-plugin-maps/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eclipsesource%2Ftabris-plugin-maps/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eclipsesource%2Ftabris-plugin-maps/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/eclipsesource","download_url":"https://codeload.github.com/eclipsesource/tabris-plugin-maps/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248204388,"owners_count":21064821,"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":["android","cordova-plugin","geolocation","map","tabris","tabris-js","widget"],"created_at":"2024-11-14T04:31:58.084Z","updated_at":"2025-04-10T10:52:58.768Z","avatar_url":"https://github.com/eclipsesource.png","language":"Kotlin","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Tabris.js Maps Plugin\n\n\u003ca href=\"https://github.com/eclipsesource/tabris-plugin-maps/blob/master/.github/workflows/main.yml\"\u003e\u003cimg alt=\"Tabris.js Maps Plugin status\" src=\"https://github.com/eclipsesource/tabris-plugin-maps/workflows/Build%20example%20app/badge.svg\"\u003e\u003c/a\u003e\n\nThe `tabris-plugin-maps` plugin project provides a [Tabris.js](https://tabrisjs.com) API to show and interact with a map widget. The plugin currently supports Android (via [Google Maps](https://developers.google.com/maps/)) and iOS (via [Map Kit](https://developer.apple.com/maps/)).\n\n![Tabris maps on iOS and Android](assets/screenshots/maps.png)\n\n## Compatibility\n\nCompatible with [Tabris.js](https://www.npmjs.com/package/tabris) 3.2.0+. For older Tabris version see repository branches.\n\n## Example\n\nThe following snippet shows how the `tabris-plugin-maps` plugin can be used in a Tabris.js app:\n\n```javascript\nnew esmaps.Map({\n  left: 0, right: 0, top: 0, bottom: 0\n}).on('ready', function() {\n  // show paris with a radius of 2000 meters\n  this.moveToPosition([48.8644458, 2.3589976], 2000);\n}).appendTo(tabris.ui.contentView);\n```\n\nA more elaborate example can be found in the [example](example/) folder. It provides a Tabris.js app that demonstrates various features of the `tabris-plugin-maps` widget.\n\n## Integrating the plugin\nThe Tabris.js website provides detailed information on how to [integrate custom widgets](https://tabrisjs.com/documentation/latest/build#adding-plugins) in your Tabris.js based app.\n\n### Add the plugin to your project\n\nThe plugin should be added as an entry in the apps `config.xml` file:\n\n```xml\n\u003cplugin name=\"tabris-plugin-maps\" spec=\"^5.0.0\" /\u003e\n```\n\nTo fetch the latest development version use the GitHub url:\n\n```xml\n\u003cplugin name=\"tabris-plugin-maps\" spec=\"https://github.com/eclipsesource/tabris-plugin-maps.git\" /\u003e\n```\n\n#### Android\n\nOn Android a Google Maps API key has to be provided when adding the plugin to your Tabris.js app. The documentation for the Google Maps API explains how to [acquire an API key](https://developers.google.com/maps/documentation/android/signup).\n\nThe API key can be configured inside your app's `config.xml`:\n\n```xml\n\u003cplugin name=\"tabris-plugin-maps\" spec=\"^5.0.0\"\u003e\n  \u003cvariable name=\"ANDROID_API_KEY\" value=\"$ANDROID_API_KEY\" /\u003e\n\u003c/plugin\u003e\n```\n\nWhen the environment variable `ANDROID_API_KEY` is set, Tabris.js CLI will replace the value placeholder `$ANDROID_API_KEY` in the config.xml during build.\n\n## API documentation\n\nThe API consists of two objects: The `esmaps.Map` and the `esmaps.Marker` that can be created on an `Map`. Note that the properties and functions of the `Map` *can only be accessed _after_ the [`ready`](#ready) callback has fired*.\n\n### `Map`\n\n#### Properties\n\nThe following properties can be applied on top of the [common Tabris.js properties](https://tabrisjs.com/documentation/latest/api/Widget#properties). All properties can be read and written unless noted otherwise.\n\n##### `position` : _number[]_\n\n* The current center position of the map. The array has to be a two element tuple consisting of latitude and longitude.\n* Example: `[48.8644458, 2.3589976]`\n\n##### `region` : _object_\n\n* Describes the currently visible rectangle of the map. A region object has the two properties `southEast` and `northWest` that span the visible region of the map. In case the map is tilted the region is represented by the smallest possible rectangle that could contain the trapezoid representing the visible region.\n* Example: `{southWest: [48.8644458, 2.3589976], northEast: [48.8821597,2.3856527]}`.\n\n##### `camera` : _object_\n\n* Represents the orientation of the camera. The camera currently only holds the one property `position`. It is the same property as the top level property `position`.\n* Example: `{position: [48.8644458, 2.3589976]}`\n\n##### `showMyLocation` : _boolean_, default: `false`\n\n  * Displays the current location of the user on the map. To activate the option the app has to have the necessary permissions to retrieve the users location. Be aware that the position has to be obtained by the device so the effect might no be visible immediately.\n\n##### `showMyLocationButton` : _boolean_, default: `false`\n\n* Displays a button to animate the camera to the current location of the user when the location is available. Can only be activated when `showMyLocation` is enabled. The property is only available on Android but a similar effect can be achieved with the [`moveTo`](#functions) functions.\n\n##### `myLocation` : _number[]_\n\n* Retrieves the current location of the user. The returned array is a `position` array consisting of latitude and longitude. Can only be used when `showMyLocation` is enabled. Since the location obtained by `showMyLocation` is not available immediately this call can return `null` or `undefined`. The property is _read only_.\n* Example: `[48.8644458, 2.3589976]`\n\n##### `mapType` : _string_, supported values: `none`, `hybrid`, `normal`, `satellite`, `terrain`, `satelliteflyover`, `hybridflyover`, default: `normal`\n\n* Defines how the map is visualized. The most common properties are `normal` and `sattelite`. Not all variants are supported on each platform. `hybrid`, `normal`, `satellite` are supported on Android and iOS whereas `none`, and `terrain` is only available on Android and `satelliteflyover` and `hybridflyover` is only available on iOS.\n\n#### Events\n\n##### `ready`\n\n* The `ready` event is fired when the map is fully initialized and ready for user interaction. The [properties](#properties) and [functions](#functions) of the `Map` can only be accessed after the `ready` event has fired.\n\n###### Event Parameters:\n\n* `target` : _Map_\n  * The `Map` widget that is ready\n\n##### `tap`\n\n* The `tap` event is fired when a tap on a map is detected.\n\n###### Event Parameters:\n\n* `target` : _Map_\n  * The `Map` widget the tap occurred on\n* `position` : _number[]_\n  * A position array consisting of latitude and longitude: E.g. `[48.8644458, 2.3589976]`\n\n##### `longpress`\n\n* The `longpress` event is fired when a long press on a map is detected.\n\n###### Event Parameters:\n\n* `target` : _Map_\n  * The `Map` widget the long press occurred on\n* `position` : _number[]_\n  * A position array consisting of latitude and longitude: E.g. `[48.8644458, 2.3589976]`\n\n##### `cameraMoved`\n\n* The `cameraMoved` event is fired when the user changed the position of the map by interacting with the map via touch. The callback is not guaranteed to fire continuously but rather when the map has reached a resting position.\n\n###### Event Parameters:\n\n* `target` : _Map_\n  * The `Map` widget whose the camera position has changed\n* `camera` : _object_\n  * The `camera` object consists of the same properties as the [`camera`](#camera) property and contains the new orientation of the camera\n\n##### `cameraChanged`\n\n* The `cameraChanged` event is fired when the position of the map has reached its final destination by a programmatic camera change. E.g. by setting the [`position`](#position) or using one of the [`moveTo`](#functions) functions.\n\n###### Event Parameters:\n\n* `target` : _Map_\n  * The `Map` widget whose the camera position has changed\n* `camera` : _object_\n  * The `camera` object consists of the same properties as the [`camera`](#camera) property and contains the new orientation of the camera\n\n\n### Functions\n\n#### `moveToPosition(position, radius, [options])`\n\nThe function `moveToPosition()` updates the cameras center to a new position and makes sure the given radius is fully contained in the visible region. This function resets the maps tilt.\n\nExample:\n```js\nmap.moveToPosition([48.8644458, 2.3589976], 500, {padding: 16, animate: true});\n```\n##### Parameter\n\n* `position` : _number[]_\n  * The target center [`position`](#position) of the map as an array of latitude and longitude. E.g. `[48.8644458, 2.3589976]`.\n* `radius` : _number_\n  * The radius in meters that should be visible on the map. Effectively this parameter controls the \"zoom\" level of the map.\n* `options` : _object_\n  * The optional options object contains additional information for the camera placement:\n    * `padding` : _number_\n      * A padding placed around the given `radius` in device independent pixel. This allows to give some inset to the region that we want to point the map to.\n    * `animate` : _boolean_\n      * Whether to place the camera directly at the given position or to move the camera in an animate fashion.\n\n#### `moveToRegion(region, [options])`\n\nThe function `moveToPosition()` sets the cameras center to a new position and makes sure the given radius is fully contained in the visible region. This function resets the maps tilt.\n\nExample:\n```js\nmap.moveToRegion({southWest: [48.8644458, 2.3589976], northEast: [48.8821597,2.3856527]},\n                 {padding: 16, animate: true});\n```\n\n##### Parameter\n\n* `region` : _object_\n  * The visible area to show on the map. The format of the region parameter is the same as for the [`region`](#region) property. It consists of two properties `southEast` and `northWest` to span the visible region of the map. E.g. `{southWest: [48.8644458, 2.3589976], northEast: [48.8821597,2.3856527]}`\n* `options` : _object_\n  * The optional options object contains additional information for the camera placement:\n    * `padding` : _number_\n      * A padding placed around the given `radius` in screen pixel. This allows to provide some inset to the region to be shown on the map.\n    * `animate` : _boolean_\n      * Whether to place the camera directly at the given position or to move the camera in an animated fashion.\n\n#### `addMarker(marker)`\n\nThe function `addMarker(marker)` adds a marker to the map. When a map gets disposed all of its previously added markers are disposed with it.\n\n#### `removeMarker(marker)`\n\nThe function `removeMarker(marker)` removes a marker from the map.\n\n#### `getMarkers()`\n\nThe function `getMarkers()` returns an `array` of all currently added markers.\n\n##### Parameter\n\n* `options` : _Object_\n  * Contains a property `latLng` to indicate the position of the marker.\n\n### `Marker`\n\nA `Marker` is used to indicate places and positions on the Map.\n\n#### Properties\n\n##### `position` : _number[]_\n\n* The current position of the marker if set. The position is an array consisting of latitude and longitude: E.g. `[48.8644458, 2.3589976]`\n\n##### `image` : _Image_\n\n* Image to be shown instead of the standard marker image.\n\n#### Events\n\n##### `tap`\n\n* The `tap` event is fired when the user taps on a marker.\n\n#### Functions\n\n##### dispose()\n\n* Remove a marker from the map\n\n## Compatibility\n\nCompatible with [Tabris.js](https://www.npmjs.com/package/tabris) 2.4 and 2.5.\n\n## Development of the widget\n\nWhile not required by the consumer of the widget, this repository provides Android specific development artifacts. These artifacts allow to more easily consume the native source code when developing the native parts of the widget.\n\n### Android\n\nThe project provides a gradle based build configuration, which also allows to import the project into Android Studio.\n\nIn order to reference the Tabris.js specific APIs, the environment variable `TABRIS_ANDROID_PLATFORM` has to point to the Tabris.js Android Cordova platform root directory.\n\n```bash\nexport TABRIS_ANDROID_PLATFORM=/home/user/tabris-android\n```\n The environment variable is consumed in the gradle projects [build.gradle](project/android/build.gradle) file.\n\n## Copyright\n\nPublished under the terms of the [BSD 3-Clause License](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feclipsesource%2Ftabris-plugin-maps","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Feclipsesource%2Ftabris-plugin-maps","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feclipsesource%2Ftabris-plugin-maps/lists"}