Merge pull request #314 from hotwired/enochtamulonis/main

Readme documentation improvements

README.md

@@ -10,7 +10,7 @@
 
 ## Requirements
 
-1. Android SDK 26+ is required as the `minSdkVersion` in your build.gradle.
+1. Android SDK 26+ is required as the `minSdkVersion` in your `build.gradle.kts` file.
 1. This library is written entirely in [Kotlin](https://kotlinlang.org/), and your app should use Kotlin as well. Compatibility with Java is not provided or supported.
 1. This library supports web apps using either Turbo 7 or Turbolinks 5.
 1. `Turbo` (or `Turbolinks`) is exposed on the `window` object on the WebView page being loaded.

docs/INSTALLATION.md

@@ -1,42 +1,47 @@
 # Installation
 
 ## Gradle
-Add the dependency from Maven Central to your app module's (not top-level) `build.gradle` file:
 
-```groovy
-repositories {
-    mavenCentral()
-}
+Add the dependency from Maven Central to your app module's (not top-level) `build.gradle.kts` file:
 
+```kotlin
 dependencies {
-    implementation 'dev.hotwire:turbo:<latest-version>'
+    implementation("dev.hotwire:turbo:<latest-version>")
 }
 ```
+
 [![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/).*
-
 ## Required `minSdkVersion`
-Android SDK 26 (or greater) is required as the `minSdkVersion` in your app module's `build.gradle` file:
-```groovy
+
+Android SDK 26 (or greater) is required as the `minSdkVersion` in your app module's `build.gradle.kts` file:
+
+```kotlin
+compileSdk = 34
+
 defaultConfig {
-    minSdkVersion 26
+    minSdkVersion = 26
+    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
 <uses-permission android:name="android.permission.INTERNET"/>
 ```
 
 # 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,10 +51,11 @@ export GITHUB_USER='<your username>'
 export GITHUB_ACCESS_TOKEN='<your personal 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
+```kotlin
 repositories {
     maven {
         name = "GitHubPackages"
@@ -63,7 +69,7 @@ repositories {
 }
 
 dependencies {
-    implementation 'dev.hotwire:turbo:<latest-version>'
+    implementation("dev.hotwire:turbo:<latest-version>")
 }
 ```
 

docs/QUICK-START.md

@@ -8,28 +8,31 @@
 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"
 
     override val startLocation = "https://turbo-native-demo.glitch.me/"
 
     override val registeredActivities: List<KClass<out AppCompatActivity>>
         get() = listOf(
-            // Leave empty unless you have more 
+            // Leave empty unless you have more
             // than one TurboActivity in your app
         )
 
@@ -52,9 +55,11 @@ 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:
@@ -87,6 +92,7 @@ A Turbo Activity is straightforward and needs to implement the [`TurboActivity`]
 Your Activity should extend Android Jetpack's [`AppCompatActivity`](https://developer.android.com/reference/androidx/appcompat/app/AppCompatActivity). In its simplest form, your Activity will look like:
 
 **`MainActivity.kt`:**
+
 ```kotlin
 class MainActivity : AppCompatActivity(), TurboActivity {
     override lateinit var delegate: TurboActivityDelegate
@@ -100,14 +106,15 @@ class MainActivity : AppCompatActivity(), TurboActivity {
 }
 ```
 
-*Note that `R.layout.activity_main` refers to the Activity layout file that you already created. `R.id.main_nav_host` refers to the `MainSessionNavHostFragment` that you created, hosted in the layout file.*
+_Note that `R.layout.activity_main` refers to the Activity layout file that you already created. `R.id.main_nav_host` refers to the `MainSessionNavHostFragment` that you created, hosted in the layout file._
 
 Refer to the demo [`MainActivity`](../demo/src/main/kotlin/dev/hotwire/turbo/demo/main/MainActivity.kt) as an example. (Don't forget to add your Activity to your app's [`AndroidManifest.xml`](../demo/src/main/AndroidManifest.xml) file.)
 
 ## Create a Web Fragment
 
 ### Create the TurboWebFragment class
-You'll need at least one web Fragment that will serve as a destination for urls that display web content in your app. 
+
+You'll need at least one web Fragment that will serve as a destination for urls that display web content in your app.
 
 A web Fragment is straightforward and needs to implement the [`TurboWebFragment`](../turbo/src/main/kotlin/dev/hotwire/turbo/fragments/TurboWebFragment.kt) abstract class. This abstract class implements the [`TurboWebFragmentCallback`](../turbo/src/main/kotlin/dev/hotwire/turbo/fragments/TurboWebFragmentCallback.kt) interface, which provides a number of functions available to customize your Fragment.
 
@@ -120,17 +127,21 @@ In its simplest form, your web Fragment will look like:
 @TurboNavGraphDestination(uri = "turbo://fragment/web")
 class WebFragment : TurboWebFragment()
 ```
+
 The library automatically inflates a default `R.layout.turbo_fragment_web` layout to host a `TurboView`. If you'd like to create your own custom layout for your web Fragment, you can override the `onCreateView()` function and inflate your own layout. See the demo [`WebHomeFragment`](../demo/src/main/kotlin/dev/hotwire/turbo/demo/features/web/WebHomeFragment.kt) as an example of of providing your own layout.
 
-You can also provide your own custom progress view or error view by overriding the `createProgressView()` and `createErrorView()` functions in your web Fragment. 
+You can also provide your own custom progress view or error view by overriding the `createProgressView()` and `createErrorView()` functions in your web Fragment.
 
 Refer to demo [`WebFragment`](../demo/src/main/kotlin/dev/hotwire/turbo/demo/features/web/WebFragment.kt) as an example.
 
 ## Create a Path Configuration
+
 See the documentation to learn about setting up your [path configuration](PATH-CONFIGURATION.md)
 
 ## Navigation
+
 See the documenation to learn about [navigating between destinations](NAVIGATION.md).
 
 ## Advanced Options
+
 See the documentation to [learn about the advanced options available](ADVANCED-OPTIONS.md).