Android article for Nested Categories

sdks-and-frameworks/android/searching/README.md

@@ -28,13 +28,17 @@ See the full list of parameters:
 
 #### &#x20;<a href="#example-of-creating-a-search-query" id="example-of-creating-a-search-query"></a>
 
+
+#### Example of Creating a Search Query <a href="#example-of-creating-a-search-query" id="example-of-creating-a-search-query"></a>
+
 {% tabs %}
+
 {% tab title="Java" %}
-#### Example of Creating a Search Query <a href="#example-of-creating-a-search-query" id="example-of-creating-a-search-query"></a>
 
-```
+{% code overflow="wrap" lineNumbers="true" %}
+```java
 void findRestroom() {
-    //Here we will create an empty query because we are only interrested in getting locations that match a category. If you want to be more specific here where you can add a query text like "Unisex Restroom"
+    //Here we will create an empty query because we are only interested in getting locations that match a category. If you want to be more specific here where you can add a query text like "Unisex Restroom"
     MPQuery mpQuery = new MPQuery
             .Builder()
             .build();
@@ -54,41 +58,14 @@ void findRestroom() {
     });
 }
 ```
+{% endcode %}
 
-### Display Search Results on the Map[​](https://docs.mapsindoors.com/searching#display-search-results-on-the-map) <a href="#display-search-results-on-the-map" id="display-search-results-on-the-map"></a>
-
-When displaying the search results it is helpful to filter the map to only show matching Locations. Matching Buildings and Venues will still be shown on the map, as they give context to the user, even if they aren't selectable on the map.
-
-#### Example of Filtering the Map to Display Searched Locations on the Map <a href="#example-of-filtering-the-map-to-display-searched-locations-on-the-map" id="example-of-filtering-the-map-to-display-searched-locations-on-the-map"></a>
-
-
-
-```
-MapsIndoors.getLocationsAsync(mpQuery, mpFilter, (locations, error) -> {
-    if (locations != null && !locations.isEmpty()) {
-        //Query with the locations from the query result. Use default camera behavior
-        mMapControl.setFilter(locations, MPFilterBehavior.DEFAULT);
-    }
-});
-```
-
-### Clearing the Map of Your Filter[​](https://docs.mapsindoors.com/searching#clearing-the-map-of-your-filter) <a href="#clearing-the-map-of-your-filter" id="clearing-the-map-of-your-filter"></a>
-
-After displaying the search results on your map you can then clear the filter so that all Locations show up on the map again.
-
-#### Example of Clearing Your Map Filter to Show All Locations Again <a href="#example-of-clearing-your-map-filter-to-show-all-locations-again" id="example-of-clearing-your-map-filter-to-show-all-locations-again"></a>
-
-```
-mMapControl.clearFilter();
-```
 {% endtab %}
 
 {% tab title="Kotlin" %}
-#### Example of Creating a Search Query <a href="#example-of-creating-a-search-query" id="example-of-creating-a-search-query"></a>
-
-
 
-```
+{% code overflow="wrap" lineNumbers="true" %}
+```kotlin
 fun findRestroom() {
     //Here we will create an empty query because we are only interrested in getting locations that match a category. If you want to be more specific here where you can add a query text like "Unisex Restroom"
     val mpQuery = MPQuery.Builder()
@@ -107,31 +84,132 @@ fun findRestroom() {
     }
 }
 ```
+{% endcode %}
+
+{% endtab %}
+
+{% endtabs %}
 
 ### Display Search Results on the Map[​](https://docs.mapsindoors.com/searching#display-search-results-on-the-map) <a href="#display-search-results-on-the-map" id="display-search-results-on-the-map"></a>
 
 When displaying the search results it is helpful to filter the map to only show matching Locations. Matching Buildings and Venues will still be shown on the map, as they give context to the user, even if they aren't selectable on the map.
 
 #### Example of Filtering the Map to Display Searched Locations on the Map <a href="#example-of-filtering-the-map-to-display-searched-locations-on-the-map" id="example-of-filtering-the-map-to-display-searched-locations-on-the-map"></a>
 
+{% tabs %}
 
+{% tab title="Java" %}
 
-```
+{% code overflow="wrap" lineNumbers="true" %}
+```java
 MapsIndoors.getLocationsAsync(mpQuery, mpFilter, (locations, error) -> {
+    if (locations != null && !locations.isEmpty()) {
+        //Query with the locations from the query result. Use default camera behavior
+        mMapControl.setFilter(locations, MPFilterBehavior.DEFAULT);
+    }
+});
+```
+{% endcode %}
+
+{% endtab %}
+
+{% tab title="Kotlin" %}
+
+{% code overflow="wrap" lineNumbers="true" %}
+```kotlin
+MapsIndoors.getLocationsAsync(mpQuery, mpFilter) { locations, error ->
     //Query with the locations from the query result. Use default camera behavior
     mMapControl.setFilter(locations, MPFilterBehavior.DEFAULT)
-});
+};
 ```
+{% endcode %}
+
+{% endtab %}
+
+{% endtabs %}
 
 ### Clearing the Map of Your Filter[​](https://docs.mapsindoors.com/searching#clearing-the-map-of-your-filter) <a href="#clearing-the-map-of-your-filter" id="clearing-the-map-of-your-filter"></a>
 
 After displaying the search results on your map you can then clear the filter so that all Locations show up on the map again.
 
 #### Example of Clearing Your Map Filter to Show All Locations Again <a href="#example-of-clearing-your-map-filter-to-show-all-locations-again" id="example-of-clearing-your-map-filter-to-show-all-locations-again"></a>
 
+{% tabs %}
+
+{% tab title="Java" %}
+
+{% code overflow="wrap" lineNumbers="true" %}
+```java
+mMapControl.clearFilter();
 ```
+{% endcode %}
+
+{% endtab %}
+
+{% tab title="Kotlin" %}
+
+{% code overflow="wrap" lineNumbers="true" %}
+```kotlin
 mMapControl.clearFilter()
 ```
+{% endcode %}
+
 {% endtab %}
+
 {% endtabs %}
 
+### Searching for Nested Categories <a href="#searching-for-nested-categories" id="searching-for-nested-categories"></a>
+
+If your solution uses nested categories, searching for them is now much more intuitive. When you search for a parent category, all of its sub-categories are automatically included in the search—no extra setup is required.
+
+#### Understanding Nested Categories
+
+Suppose you have three categories: `Restroom`, `Unisex`, and `Handicap`. Here, `Unisex` and `Handicap` are sub-categories of `Restroom`. This hierarchy allows you to organize your data more flexibly and makes searching more powerful.
+
+Before searching, you might want to inspect the category structure in the SDK. For example, you can check if a category has specific children, or list all sub-categories:
+
+{% code overflow="wrap" lineNumbers="true" %}
+```kotlin
+val categoryCollection = MapsIndoors.getCategories()
+
+// check whether a category has a named child category
+val isChild = categoryCollection?.getCategory("Restroom")?.childKeys?.contains("Unisex")
+if (isChild == true) {
+    print("Restroom has a child with the key 'Unisex'!")
+}
+
+// fetch sub-categories with the child keys
+val keys = categoryCollection?.getCategory("Restroom").childKeys
+for (key in keys ?: emptyList()) {
+    val category = categoryCollection?.getCategory(key)
+    if (category != null) {
+        print("Restroom has category ${category.value} as a child!")
+    }
+}
+```
+{% endcode %}
+
+#### Searching with Nested Categories
+
+When you perform a search for a parent category, such as `Restroom`, the SDK will automatically include all its sub-categories (`Unisex`, `Handicap`, etc.) in the search results. This means you only need to specify the parent category in your filter, and all relevant locations will be found.
+
+{% code overflow="wrap" lineNumbers="true" %}
+```kotlin
+// we are only searching for the category, so lets set an empty query
+val query = MPQuery.Builder().build()
+// add the super-category Restroom to the list of categories
+val filter = MPFilter.Builder().setCategories(listOf("Restroom")).build()
+
+MapsIndoors.getLocationsAsync(query, filter) { locations, error -> 
+
+    // lets see if we have found any Locations that have the type "Unisex"
+    if (locations?.any { loc -> loc.categories?.any { cat -> cat == "Unisex" } == true } == true) {
+        // success
+        print("Locations with Unisex category found")
+    }
+}
+```
+{% endcode %}
+
+
+> **Note:** When you search for a parent category, all of its sub-categories are always included in the results, there is no way to limit the search to only the parent category itself. If you need more granular control (for example, to only return locations with a specific sub-category), consider organizing your categories so that each search target has its own unique sub-category. This way, you can search for exactly the locations you want by specifying the appropriate sub-category in your filter.