Merge pull request #2072 from dhis2/androsdk-1779

docs: [ANDROSDK-1779] Update docs 1.9.0

docs/content/dev/architecture.md

@@ -4,10 +4,10 @@
 
 ## Frameworks and auxiliary libraries
 
-- [Dagger](https://google.github.io/dagger/)
+- [Koin](https://insert-koin.io/)
 - [Autovalue](https://github.com/google/auto/blob/master/value/userguide/index.md)
 - [Retrofit](https://square.github.io/retrofit/)/[OkHttp3](https://github.com/square/okhttp)
-- [SQLBrite](https://github.com/square/sqlbrite)
+- [SQLCipher](https://www.zetetic.net/sqlcipher/)
 
 ## Public API overview
 
@@ -38,4 +38,4 @@ Feature packages contain at least:
 
 ## Local database
 
-SQLBrite library is used for migrations. The database has a version number defined in `DbOpenHelper`. In case the device has an outdated database, it will execute the pending migrations up to the current version number. Migrations are defined in `assets/migrations`.
+The SDK runs the DB migrations itself. The database has a version number defined in `DbOpenHelper`. In case the device has an outdated database, it will execute the pending migrations up to the current version number. Migrations are defined in `assets/migrations`.

docs/content/developer/apk-distribution.md

@@ -0,0 +1,6 @@
+# APK distributin { #android_sdk_apk_distribution }
+The web app [APK distribution](https://apps.dhis2.org/app/dff273fc-909e-48af-b151-c4d7e9c8a12c) is used to determine the APK that must be used by the Android app. It is a way to control the version of the Android apps.
+
+This parameter is automatically used by the official Android Capture app, which will offer the update when a new version is identified. Other custom applications might use this parameter to control their own updates. This logic must be implemented at application level.
+
+Check more information about the app in the [docs](https://docs.dhis2.org/en/use/android-app/apk-distribution.html).

docs/content/developer/compatibility.md

@@ -13,3 +13,4 @@ Compatibility table between DHIS2 Android SDK library, DHIS2 core and Android SD
 | 1.6.X    | 2.30 -> 2.38     | 21 - 31     | 2.0.34 - 2.0.35   |
 | 1.7.X    | 2.30 -> 2.39     | 21 - 31     | 2.0.42 - 2.0.43   |
 | 1.8.X    | 2.30 -> 2.40     | 21 - 33     | 2.0.47 - 2.0.48   |
+| 1.9.X    | 2.30 -> 2.40     | 21 - 34     | 2.0.47 - 2.0.48   |

docs/content/developer/debugging.md

@@ -1,9 +1,14 @@
 # Debugging { #android_sdk_debugging }
 
 ## Android Studio
-You can debug your DHIS2 Android App using Android Studio. Follow the [instructions from the Android Developer Portal](https://developer.android.com/studio/debug) 
+You can debug your DHIS2 Android App using Android Studio. Follow the [instructions from the Android Developer Portal](https://developer.android.com/studio/debug)
 
-## Flipper (recommended)
+## HTTP Toolkit
+Using HTTP Toolkit you can explore and mock the HTTP requests when needed. It is easy to install and use ([HTTP toolkit page](https://httptoolkit.com)).
+
+It can be easily attached to emulators and rooted devices; in the case of non-rooted physical devices, it requires additional steps. 
+
+## Flipper
 Flipper is a platform for debugging mobile apps on iOS and Android developed by Facebook. Flipper provides many features, 
 provided by different plugins.
 

docs/content/developer/dhis2-services.md

@@ -29,45 +29,20 @@ Check the javadoc documentation in the IDE to know more details about each metho
 ## Value Type helper
 
 The SDK include a enum helper class called `ValueType`. This class defines all the different types of values that you can find in DHIS2. In addition, for each of them you can find a validator for the type of value and information about the type of value it is, whether it is a date, a string, a boolean or other type.
-The ValueTypes offered by the SDK are listed below:
-
-- `TEXT`
-- `LONG_TEXT`
-- `LETTER`
-- `BOOLEAN`
-- `TRUE_ONLY`
-- `DATE`
-- `DATETIME`
-- `TIME`
-- `NUMBER`
-- `UNIT_INTERVAL`
-- `PERCENTAGE`
-- `INTEGER`
-- `INTEGER_POSITIVE`
-- `INTEGER_NEGATIVE`
-- `INTEGER_ZERO_OR_POSITIVE`
-- `FILE_RESOURCE`
-- `COORDINATE`
-- `PHONE_NUMBER`
-- `EMAIL`
-- `USERNAME`
-- `ORGANISATION_UNIT`
-- `TRACKER_ASSOCIATE`
-- `AGE`
-- `URL`
-- `IMAGE(String::class.java, UidValidator)`
 
 To access the type of value you can simply access it through the methods of the valueType.
 
 ```java
-    valueType.isDate();
-    valueType.isCoordinate();
+    valueType.isInteger();
+    valueType.isDecimal();
     valueType.isNumeric();
-    valueType.isText();
     valueType.isBoolean();
+    valueType.isText();
     valueType.isDate();
     valueType.isFile();
-    valueType.isInteger();
+    valueType.isCoordinate();
+    valueType.isGeo();
+    valueType.isJson();
 ```
 
 To validate a value starting from its valueType it can be done in the following way:

docs/content/developer/getting-started.md

@@ -6,7 +6,7 @@ Include dependency in build.gradle.
 
 ```gradle
 dependencies {
-    implementation "org.hisp.dhis:android-core:1.8.2"
+    implementation "org.hisp.dhis:android-core:1.9.0"
     ...
 }
 ```

docs/content/developer/overview.md

@@ -14,4 +14,4 @@ The SDK is mainly written in Java 8 using the reduced subset of features allowed
 
 It uses [RxJava](https://github.com/ReactiveX/RxJava) to facilitate the asynchronous treatment of some methods. Although it is optional, we recommend this approach to ensure non-blocking calls.
 
-Other libraries internally used by the SDK are: [Dagger](https://github.com/google/dagger) for dependency injection, [Jackson](https://github.com/FasterXML/jackson) for JSON parsing, [Retrofit](https://square.github.io/retrofit/) and [OkHttpClient](https://square.github.io/okhttp/) for API communication or [SQLBrite](https://github.com/square/sqlbrite) for DB migrations.
+Other libraries internally used by the SDK are: [Koin](https://insert-koin.io/) for dependency injection, [Jackson](https://github.com/FasterXML/jackson) for JSON parsing, [Retrofit](https://square.github.io/retrofit/) and [OkHttpClient](https://square.github.io/okhttp/) for API communication or [SQLCipher](https://www.zetetic.net/sqlcipher/) for DB encryption.

docs/content/developer/settings.md

@@ -32,6 +32,7 @@ It gives additional information about app settings:
 - Matomo configuration: if you have your own Matomo instance, you can expose this information to the app in order to configure its Matomo client.
 - AllowScreenCapture: parameter to determine if the application should allow screen capture or not.
 - MessageOfTheDay: a message to show to the users.
+- ExperimentalFeatures: list of experimental features enabled.
 
 ### Synchronization settings { #android_sdk_synchronization_settings }
 
@@ -58,8 +59,11 @@ These settings give control over the appearance of the data entry form.
 - ProgramConfiguration: it defines two properties for programs.
     - CompletionSpinner: show/hide the completion spinner.
     - OptionalSearch: it defines if searching is mandatory or not before creating data.
+    - DisableReferrals: whether referrals must be enabled or not for this program.
+    - DisableCollapsibleSections: whether the sections must be collapsible or not for this program.
+    - ItemHeader: it defines the element (programIndicator) to be used to generate a header for the TEI. This property is automatically consumed by the SDK when using the `TrackedEntitySearchCollectionRepository`.
 
-These settings refer to visual components so they must be consumed by the app.
+Most of the settings refer to visual components so they are usually consumed by the app.
 
 ### Analytic settings { #android_sdk_analytic_settings }
 

docs/content/developer/use-case-configuration.md

@@ -0,0 +1,6 @@
+# Use case configuration { #android_sdk_use_cases }
+The web app [Use Case Configuratin](https://apps.dhis2.org/app/7df6f344-0487-469c-abe6-53c6e729abcf) is used to assign use cases to programs/dataSets. This information can be used by the app in order to display the information using a different layout or to apply different business logic.
+
+The SDK downloads the information generated by this app and exposes it in the UseCaseModule. The particular use case logic or UI must be implemented at application level.
+
+Check more information about the app in the [docs](https://docs.dhis2.org/en/use/android-app/use-case-configuration.html).

docs/content/developer/workflow.md

@@ -276,16 +276,16 @@ Additionally, if you want the images associated to `Image` data values available
 
 DHIS2 has a functionality to filter TrackedEntityInstances by related
 properties, like attributes, organisation units, programs or enrollment
-dates. The Sdk provides the `TrackedEntityInstanceQueryCollectionRepository` 
+dates. The Sdk provides the `TrackedEntitySearchCollectionRepository` 
 with methods that allow the download of tracked entity
 instances within the search scope. It can be found inside the tracked entity instance module.
 
-The tracked entity instance query is a powerful tool that follows a
+The tracked entity instance search is a powerful tool that follows a
 builder pattern and allows the download of tracked entity instances
 filtering by **different parameters**.
 
 ```java
-d2.trackedEntityModule().trackedEntityInstanceQuery()
+d2.trackedEntityModule().trackedEntitySearch()
     .[repository mode]
     .[filters]
     .get()
@@ -316,7 +316,7 @@ Additionally, the repository offers different strategies to fetch data:
   connector. For example:
 
   ```java
-  d2.trackedEntityModule().trackedEntityInstanceQuery()
+  d2.trackedEntityModule().trackedEntitySearch()
       .byAttribute("uid1").eq("value1")
       .byAttribute("uid2").eq("value2")
       .get()
@@ -330,7 +330,7 @@ Additionally, the repository offers different strategies to fetch data:
   connector. For example:
 
   ```java
-  d2.trackedEntityModule().trackedEntityInstanceQuery()
+  d2.trackedEntityModule().trackedEntitySearch()
       .byFilter("uid1").eq("value1")
       .byFilter("uid2").eq("value2")
       .get()
@@ -372,7 +372,7 @@ Additionally, the repository offers different strategies to fetch data:
 Example:
 
 ```java
-d2.trackedEntityModule().trackedEntityInstanceQuery()
+d2.trackedEntityModule().trackedEntitySearch()
                 .byOrgUnits().eq("orgunitUid")
                 .byOrgUnitMode().eq(OrganisationUnitMode.DESCENDANTS)
                 .byProgram().eq("programUid")
@@ -388,12 +388,12 @@ to fully download them using the `byUid()` filter of the `TrackedEntityInstanceD
 It could happen that you add filters to the query repository in different parts of the application and you don't have a clear picture about the filters applied, specially when using working lists because they add a set of parameters. In order to solve this, you can access the filter scope at any moment in the repository:
 
 ```java
-d2.trackedEntityModule().trackedEntityInstanceQuery()
+d2.trackedEntityModule().trackedEntitySearch()
     .[ filters ]
     .getScope();
 ```
 
-In addition to the standard `getPaged(int)` and `getDataSource()` methods that are available in all the repositories, the TrackedEntityInstanceQuery repository exposes a method to wrap the response in a `Result` object: the `getResultDataSource()`. This method is kind of a workaround to deal with the lack of error management in the Version 2 of the Android Paging Library (it is hardly improved in version 3). Using this dataSource you can catch search errors, such as "Min attributes required" or "Max tei count reached". 
+In addition to the standard `getPaged(int)` and `getDataSource()` methods that are available in all the repositories, the TrackedEntitySearch repository exposes a method to wrap the response in a `Result` object: the `getResultDataSource()`. This method is kind of a workaround to deal with the lack of error management in the Version 2 of the Android Paging Library (it is hardly improved in version 3). Using this dataSource you can catch search errors, such as "Min attributes required" or "Max tei count reached". 
 
 
  ### Working lists / Tracker filters
@@ -404,7 +404,7 @@ There are three concepts related to building a predifined filter for tracker obj
 - **EventFilters**: they define filters to be used against Event objects.
 - **ProgramStageWorkingList**: they define filters to be used against TrackedEntity objects and they add support to filter by event-related data. It is mandatory to specify a particular ProgramStage.
 
-As usual, they have their own collection repository and can be applied in "query" repositories. For example:
+As usual, they have their own collection repository and can be applied in "search" repositories. For example:
 
 ```java
 // Get the filters
@@ -413,7 +413,7 @@ List<EventFilter> filters = d2.eventModule().eventFilters().blockingGet();
 List<ProgramStageWorkingList> workingLists = d2.programModule().programStageWorkingLists().blockingGet();
 
 // Apply the filters
-d2.trackedEntityModule().trackedEntityInstanceQuery()
+d2.trackedEntityModule().trackedEntitySearch()
     .byTrackedEntityInstanceFilter().eq("filterUid")
     .byProgramStageWorkingList().eq("workingListUid")
     .get()

docs/dhis2_android_sdk_dev_guide_INDEX.md

@@ -1,5 +1,5 @@
 <!--DHIS2-SECTION-ID:index-->
 
-!INCLUDE "content/dev/developement.md"
+!INCLUDE "content/dev/development.md"
 !INCLUDE "content/dev/architecture.md"
 !INCLUDE "content/dev/synchronization.md"

docs/dhis2_android_sdk_developer_guide_INDEX.yml

@@ -18,6 +18,8 @@
 - Program rule engine: "@github(dhis2/dhis2-android-sdk, docs/content/developer/program-rule-engine.md, master"
 - Program indicator engine: "@github(dhis2/dhis2-android-sdk, docs/content/developer/program-indicator-engine.md, master)"
 - Validation rule engine: "@github(dhis2/dhis2-android-sdk, docs/content/developer/validation-rule-engine.md, master)"
+- Use case configuration: "@github(dhis2/dhis2-android-sdk, docs/content/developer/use-case-configuration.md, master)"
+- APK distribution: "@github(dhis2/dhis2-android-sdk, docs/content/developer/apk-distribution.md, master)"
 - Debugging: "@github(dhis2/dhis2-android-sdk, docs/content/developer/debugging.md, master)"
 - Known issues: "@github(dhis2/dhis2-android-sdk, docs/content/developer/known-issues.md, master)"