Update page and README.md

serbelga · Mar 21, 2024 · 7cd2d60 · 7cd2d60
1 parent b7b3874
commit 7cd2d60
Show file tree

Hide file tree

Showing 3 changed files with 163 additions and 152 deletions.
diff --git a/README.md b/README.md
@@ -1,157 +1,5 @@
 # Navigation Compose Extended
 
-## How to use
-
-### Navigate without arguments
-
-#### Define destinations
-
-```kotlin
-object SearchNavDestination : NavDestination<NavArgumentKey>() {
-    override val destinationId: String = "search"
-}
-
-object SearchResultNavDestination : NavDestination<NavArgumentKey>() {
-    override val destinationId: String = "searchresult"
-}
-```
-
-#### Set destinations in `NavHost`
-
-```kotlin
-val navController = rememberNavController()
-NavHost(
-    navController = navController,
-    startDestination = SearchNavDestination.route
-) {
-    composable(route = SearchNavDestination.route) { SearchScreen() }
-    composable(route = SearchResultNavDestination.route) { SearchResultScreen() }
-}
-```
-
-#### Navigate to Search Result destination using `NavAction`
-
-```kotlin
-val navController = rememberNavController()
-val navAction = rememberNavAction(navController)
-NavHost(
-    navController = navController,
-    startDestination = SearchNavDestination.route
-) {
-    composable(route = SearchNavDestination.route) {
-        SearchScreen(
-            navigateToSearchResult = {
-                navAction.navigate(
-                    SearchResultNavDestination.navRoute()
-                )
-            }
-        )
-    }
-```
-
-### Navigate with arguments
-
-#### Define `argumentsMap`
-
-```kotlin
-enum class SearchResultNavArgumentKeys(override val argumentKey: String) : NavArgumentKey {
-    SearchNavArgumentKey("search"),
-    CategoryNavArgumentKey("category")
-}
-
-object SearchResultNavDestination : NavDestination<SearchResultNavArgumentKeys>() {
-    override val destinationId: String = "searchresult"
-
-    override val argumentsMap: Map<SearchResultNavArgumentKeys, NavArgumentBuilder.() -> Unit> =
-        mapOf(
-            SearchResultNavArgumentKeys.SearchNavArgumentKey to {
-                type = NavType.StringType
-            },
-            SearchResultNavArgumentKeys.CategoryNavArgumentKey to {
-                type = NavType.StringType
-                nullable = true
-                defaultValue = "All"
-            }
-        )
-}
-```
-
-#### Set arguments in `NavHost`
-
-```kotlin
-NavHost {
-    composable(
-        route = SearchResultNavDestination.route,
-        arguments = SearchResultNavDestination.arguments
-    ) { 
-        ...
-    }
-}
-```
-
-#### Navigate to Search Result destination with arguments
-
-```kotlin
-SearchScreen(
-    navigateToSearchResult = { search, category ->
-        navAction.navigate(
-            SearchResultNavDestination.navRoute(
-                SearchResultNavArgumentKeys.SearchNavArgumentKey to search,
-            )
-        )
-    }
-)
-```
-
-### Navigate with Deep Links
-
-#### In the `AndroidManifest.xml`
-
-```xml
-<activity
-    ...>
-    <intent-filter>
-        <action android:name="android.intent.action.VIEW" />
-        <category android:name="android.intent.category.DEFAULT" />
-        <category android:name="android.intent.category.BROWSABLE" />
-        <data android:host="searchresult" android:scheme="sample" />
-    </intent-filter>
-</activity>
-```
-
-#### Define `deepLinkUris`
-
-```kotlin
-object SearchResultNavDestination : NavDestination<SearchResultNavArgumentKeys>() {
-
-    // ...
-
-    override val deepLinkUris: List<String> =
-        listOf(
-            "sample://searchresult",
-        )
-}
-```
-
-#### Set deep links in `NavHost`
-
-```kotlin
-NavHost {
-    composable(
-        route = SearchResultNavDestination.route,
-        deepLinks = SearchResultNavDestination.deepLinks,
-    ) { 
-        ...
-    }
-}
-```
-
-#### Trigger the deep link using adb
-
-```bash
-adb shell am start -d "sample://searchresult/Search?category=Category" -a android.intent.action.VIEW
-```
-
 ## License
 
 ```

diff --git a/docs/usage.md b/docs/usage.md
@@ -0,0 +1,162 @@
+## Create Destinations
+
+The `NavDestination` represents some Destination in the Navigation graph.
+
+```kotlin
+object SearchNavDestination : NavDestination<NavArgumentKey>() {
+    override val destinationId: String = "search"
+}
+
+object SearchResultNavDestination : NavDestination<NavArgumentKey>() {
+    override val destinationId: String = "searchresult"
+}
+```
+
+Using the `NavDestination` into the NavHost:
+
+```kotlin
+val navController = rememberNavController()
+NavHost(
+    navController = navController,
+    startDestination = SearchNavDestination.route
+) {
+    composable(route = SearchNavDestination.route) { SearchScreen() }
+    composable(route = SearchResultNavDestination.route) { SearchResultScreen() }
+}
+```
+
+We can navigate to some destination using the `NavAction`. In the following code, 
+we navigate to the `SearchResultNavDestination` using the `navigate` function that receives 
+a `NavRoute`:
+
+```kotlin
+val navController = rememberNavController()
+val navAction = rememberNavAction(navController)
+NavHost(
+    navController = navController,
+    startDestination = SearchNavDestination.route
+) {
+    composable(route = SearchNavDestination.route) {
+        SearchScreen(
+            navigateToSearchResult = {
+                navAction.navigate(
+                    SearchResultNavDestination.navRoute()
+                )
+            }
+        )
+    }
+}
+```
+
+## Navigate with arguments
+
+The `NavArgumentKey` represents some argument in the Navigation graph. 
+We can define multiple keys for our destinations.
+
+```kotlin
+enum class SearchResultNavArgumentKeys(override val argumentKey: String) : NavArgumentKey {
+    SearchNavArgumentKey("search"),
+    CategoryNavArgumentKey("category")
+}
+```
+
+Next, we set the `NavArgumentKey` into the `NavDestination` using the `argumentsMap` property.
+
+```kotlin
+object SearchResultNavDestination : NavDestination<SearchResultNavArgumentKeys>() {
+    override val destinationId: String = "searchresult"
+
+    override val argumentsMap: Map<SearchResultNavArgumentKeys, NavArgumentBuilder.() -> Unit> =
+        mapOf(
+            SearchResultNavArgumentKeys.SearchNavArgumentKey to {
+                type = NavType.StringType
+            },
+            SearchResultNavArgumentKeys.CategoryNavArgumentKey to {
+                type = NavType.StringType
+                nullable = true
+                defaultValue = "All"
+            }
+        )
+}
+```
+
+The `NavRoute` class will generate automatically the route with the arguments depending on if they 
+are nullable or have a default value.
+
+Arguments can be set to the `NavHost` using the `arguments` property:
+
+```kotlin
+NavHost {
+    composable(
+        route = SearchResultNavDestination.route,
+        arguments = SearchResultNavDestination.arguments
+    ) { 
+        ...
+    }
+}
+```
+
+The `navRoute()` function in the `NavDestination` class can receive the arguments as parameters. 
+In the following code, we are navigating to `SearchResultNavDestination` and we set a value for 
+the `SearchNavArgumentKey` argument.
+
+```kotlin
+SearchScreen(
+    navigateToSearchResult = { search, category ->
+        navAction.navigate(
+            SearchResultNavDestination.navRoute(
+                SearchResultNavArgumentKeys.SearchNavArgumentKey to search,
+            )
+        )
+    }
+)
+```
+
+## Navigate with Deep Links
+
+In the `AndroidManifest.xml`:
+
+```xml
+<activity
+    ...>
+    <intent-filter>
+        <action android:name="android.intent.action.VIEW" />
+        <category android:name="android.intent.category.DEFAULT" />
+        <category android:name="android.intent.category.BROWSABLE" />
+        <data android:host="searchresult" android:scheme="sample" />
+    </intent-filter>
+</activity>
+```
+
+Next, we define the deep link uri in the `NavDestination` `deepLinkUris` property:
+
+```kotlin
+object SearchResultNavDestination : NavDestination<SearchResultNavArgumentKeys>() {
+
+    // ...
+
+    override val deepLinkUris: List<String> =
+        listOf(
+            "sample://searchresult",
+        )
+}
+```
+
+Set the deep links in the `NavHost`:
+
+```kotlin
+NavHost {
+    composable(
+        route = SearchResultNavDestination.route,
+        deepLinks = SearchResultNavDestination.deepLinks,
+    ) {
+        ...
+    }
+}
+```
+
+Trigger the deep link using adb:
+
+```shell
+adb shell am start -a android.intent.action.VIEW -d "sample://searchresult"
+```
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -12,6 +12,7 @@ docs_dir: docs
 
 nav:
   - 'Overview': index.md
+  - 'Usage': usage.md
   - 'API Reference': api/
   - 'Sample App': https://github.com/serbelga/navigation-compose-extended/tree/main/sample-app