diff --git a/docs/INSTALLATION.md b/docs/INSTALLATION.md index 22cef7d6..bbf70fa3 100644 --- a/docs/INSTALLATION.md +++ b/docs/INSTALLATION.md @@ -1,42 +1,50 @@ # Installation ## Gradle -Add the dependency from Maven Central to your app module's (not top-level) `build.gradle` file: + +Add the dependency from Maven Central to your app module's (not top-level) `build.gradle.kts` file: ```groovy -repositories { - mavenCentral() -} dependencies { - implementation 'dev.hotwire:turbo:' + implementation("dev.hotwire:turbo:") } ``` + [![Download](https://img.shields.io/maven-central/v/dev.hotwire/turbo)](https://search.maven.org/artifact/dev.hotwire/turbo) See the [latest version](https://search.maven.org/artifact/dev.hotwire/turbo) available on Maven Central. -*Note: As of May 1, 2021, artifacts will no longer be released to JCenter, since [it's shutting down](https://jfrog.com/blog/into-the-sunset-bintray-jcenter-gocenter-and-chartcenter/).* +_Note: As of May 1, 2021, artifacts will no longer be released to JCenter, since [it's shutting down](https://jfrog.com/blog/into-the-sunset-bintray-jcenter-gocenter-and-chartcenter/)._ ## Required `minSdkVersion` -Android SDK 26 (or greater) is required as the `minSdkVersion` in your app module's `build.gradle` file: + +Android SDK 34 (or greater) is required as the `minSdkVersion` in your app module's `build.gradle.kts` file: + ```groovy +compileSdk = 34 + defaultConfig { - minSdkVersion 26 + minSdkVersion = 34 + targetSdk = 34 // ... } ``` ## Internet Permission + In order for a [WebView](https://developer.android.com/reference/android/webkit/WebView.html) to access the Internet and load web pages, your app must have the `INTERNET` permission. Make sure you include this permission in your app's `AndroidManifest.xml` file: + ```xml ``` # Pre-release Builds + Pre-release builds will be published to [GitHub Packages](https://github.com/features/packages). ## Personal Access Token + If you'd like to use a pre-release version, you'll need to create a [Personal Access Token](https://docs.github.com/en/free-pro-team@latest/packages/learn-github-packages/about-github-packages#authenticating-to-github-packages) in your GitHub account and give it the `read:packages` permission. Copy your access token to your `.bash_profile` (or another accessible place that's outside of source control): @@ -46,8 +54,9 @@ export GITHUB_USER='' export GITHUB_ACCESS_TOKEN='' ``` -## Gradle -Add the GitHub Packages maven repository and the dependency to your app module's `build.gradle` file: +## Gradle + +Add the GitHub Packages maven repository and the dependency to your app module's `build.gradle.kts` file: ```groovy repositories { @@ -63,7 +72,7 @@ repositories { } dependencies { - implementation 'dev.hotwire:turbo:' + implementation("dev.hotwire:turbo:") } ``` diff --git a/docs/QUICK-START.md b/docs/QUICK-START.md index 0724d47f..d9c4819e 100644 --- a/docs/QUICK-START.md +++ b/docs/QUICK-START.md @@ -8,20 +8,24 @@ 1. [Create a Path Configuration](#create-a-path-configuration) ## Create a NavHostFragment + A [`NavHostFragment`](https://developer.android.com/reference/androidx/navigation/fragment/NavHostFragment) is a component available in [Android Jetpack](https://developer.android.com/jetpack) and is primarily responsible for providing "an area in your layout for self-contained navigation to occur." The Turbo extension of this class, `TurboSessionNavHostFragment`, along with being responsible for self-contained `TurboFragment` navigation, also manages a `TurboSesssion` and a `TurboWebView` instance. You will need to implement a few things for this abstract class: -* The name of the `TurboSession` (this is arbitrary, but must be unique in your app) -* The url of a starting location when your app starts up. Note: if you're running your app locally without HTTPS, you'll need to adjust your `android:usesCleartextTraffic` settings in the AndroidManifest.xml (or use an Android Network security configuration), and target [`10.0.2.2` instead of `localhost`](https://developer.android.com/studio/run/emulator-networking). -* A list of registered activities that Turbo will be able to navigate to (optional) -* A list of registered fragments that Turbo will be able to navigate to -* The location of your `TurboPathConfiguration` JSON file(s) to configure navigation rules +- The name of the `TurboSession` (this is arbitrary, but must be unique in your app) +- The url of a starting location when your app starts up. Note: if you're running your app locally without HTTPS, you'll need to adjust your `android:usesCleartextTraffic` settings in the AndroidManifest.xml (or use an Android Network security configuration), and target [`10.0.2.2` instead of `localhost`](https://developer.android.com/studio/run/emulator-networking). +- A list of registered activities that Turbo will be able to navigate to (optional) +- A list of registered fragments that Turbo will be able to navigate to +- The location of your `TurboPathConfiguration` JSON file(s) to configure navigation rules In its simplest form, the implementation of your `TurboSessionNavHostFragment` will look like: **`MainSessionNavHostFragment`:** + ```kotlin +import dev.hotwire.turbo.session.TurboSessionNavHostFragment + class MainSessionNavHostFragment : TurboSessionNavHostFragment() { override val sessionName = "main" @@ -29,7 +33,7 @@ class MainSessionNavHostFragment : TurboSessionNavHostFragment() { override val registeredActivities: List> get() = listOf( - // Leave empty unless you have more + // Leave empty unless you have more // than one TurboActivity in your app ) @@ -52,14 +56,17 @@ See the [Fragment section](#create-a-web-fragment) below to create a `TurboFragm Refer to the demo [`MainSessionNavHostFragment`](../demo/src/main/kotlin/dev/hotwire/turbo/demo/main/MainSessionNavHostFragment.kt) for an example. ## Create an Activity + It's strongly recommended to use a single-Activity architecture in your app. Generally, you'll have one `TurboActivity` and many `TurboFragments`. ### Create the TurboActivity layout resource + You need to create a layout resource file that your `TurboActivity` will use to host the `TurboSessionNavHostFragment` that you created above. Android Jetpack provides a [`FragmentContainerView`](https://developer.android.com/reference/androidx/fragment/app/FragmentContainerView) to contain `NavHostFragment` navigation. In its simplest form, your Activity layout file will look like: **`res/layout/activity_main.xml`:** + ```xml