Skip to content

Esri/arcgis-maps-sdk-kotlin-toolkit

Repository files navigation

ArcGIS Maps SDK for Kotlin Toolkit

The ArcGIS Maps SDK for Kotlin Toolkit contains components that will simplify your Kotlin app development. It is built off of the new ArcGIS Maps SDK for Kotlin.

Toolkit Components

  • Authenticator - Displays a user interface when network and ArcGIS authentication challenges occur.
  • Compass - Shows a compass direction when the map is rotated. Auto-hides when the map points north.
  • FeatureForms - Provides a UI for editing feature attributes.
  • FloorFilter - Allows filtering of floor plan data in a geo view by a site, a facility in the site, or a floor in the facility.
  • GeoView-Compose - Compose wrappers for the MapView and SceneView.
    • Callout - Draws a callout on the GeoView to display Composable content.
  • Popup - View field values of features in a layer using the Popup API.

API Reference

View the API reference for the toolkit here.

Requirements

Please see the developer setup for a complete description of requirements

  • ArcGIS Maps SDK for Kotlin
    See this guide for complete instructions and other options for installing the SDK.
  • JDK 17

The ArcGIS Maps SDK for Kotlin Toolkit has a Minimum SDK version of 26, meaning that it can run on devices with Android Oreo (8.0) or newer.

Installation

Using the BOM

Add the maven repository to your project's gradle file:

repositories {
    maven {
        url = uri("https://esri.jfrog.io/artifactory/arcgis")
    }
}

The ArcGIS Maps SDK for Kotlin Toolkit is released with a "bill of materials" (BOM). The releasable BOM is versioned and represents a set of versions of the toolkit components which are compatible with one another. You may specify dependencies as follows

implementation(platform("com.esri:arcgis-maps-kotlin-toolkit-bom:200.5.0"))
implementation("com.esri:arcgis-maps-kotlin-toolkit-authentication")
implementation("com.esri:arcgis-maps-kotlin-toolkit-compass")
implementation("com.esri:arcgis-maps-kotlin-toolkit-geoview-compose")
implementation("com.esri:arcgis-maps-kotlin-toolkit-indoors")
implementation("com.esri:arcgis-maps-kotlin-toolkit-popup")

The template and TemplateApp modules are for bootstrapping new modules.

Please see the package structure documentation for more details.

Issues

Find a bug or want to request a new feature enhancement? Please let us know by submitting an issue.

Contributing

Esri welcomes contributions from anyone and everyone. Please see our guidelines for contributing.

Creating a New Toolkit Component

A new toolkit component can be added to this project by running the bash script at the top level ./new-component-starter.sh

This script will prompt for you to input a name for the new component and ask if you want to create a new app module for it. Capitalization isn't necessary, but it won't capitalize anything but the first letter if none is specified.

A new microapp can be added by running the bash script ./new-microapp-starter.sh. This script will prompt for you to input a name for the new microapp.

This script requires bash 4.0 or higher.

About this Repo

The project is structured into two folders, microapps and toolkit each containing many modules, and a folder for releasing a bill of materials (BOM).

arcgis-maps-sdk-kotlin-toolkit
├── bom
│   └── build.gradle.kts
├── microapps
│   └── TemplateApp
│   ├── ...App
├── toolkit
│   ├── template
│   ├── ...
├── build.gradle.kts
└── settings.gradle.kts

The toolkit folder contains releasable libraries -- these are the components of the toolkit. For each module in the toolkit folder there is a corresponding app in the microapps folder which depends on it. The apps are not released but are useful for working on a particular component in isolation.

The template and TemplateApp modules are for bootstrapping new modules.

Please see the package structure documentation for more details.

Testing

Running Local Tests

In order to run local (non-instrumented) tests of all modules and get an aggregated test report, run the following at the root folder of the project:

./gradlew testAggregatedReport --continue

The test report for local tests can be located under arcgis-maps-sdk-kotlin-toolkit/build/reports.

Running Connected Tests

In order to run connected (instrumented) tests of all modules and get the test reports in a centralized folder, run the following at the root folder of the project:

./gradlew connectedDebugAndroidTest --continue

The test reports for connected tests can be located under arcgis-maps-sdk-kotlin-toolkit/connectedTestReports.

Licensing

Copyright 2019-2022 Esri

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

A copy of the license is available in the repository's LICENSE file.