diff --git a/docs/content/dev/architecture.md b/docs/content/dev/architecture.md index 94fac44d7b..c9414c0053 100644 --- a/docs/content/dev/architecture.md +++ b/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`. diff --git a/docs/content/developer/apk-distribution.md b/docs/content/developer/apk-distribution.md new file mode 100644 index 0000000000..a3d0fdfd7a --- /dev/null +++ b/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). \ No newline at end of file diff --git a/docs/content/developer/compatibility.md b/docs/content/developer/compatibility.md index 6ffd26c93b..45836f9456 100644 --- a/docs/content/developer/compatibility.md +++ b/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 | diff --git a/docs/content/developer/debugging.md b/docs/content/developer/debugging.md index 95a3701f3c..ead27759c8 100644 --- a/docs/content/developer/debugging.md +++ b/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. diff --git a/docs/content/developer/dhis2-services.md b/docs/content/developer/dhis2-services.md index fe5d6236af..7ab502e480 100644 --- a/docs/content/developer/dhis2-services.md +++ b/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: diff --git a/docs/content/developer/getting-started.md b/docs/content/developer/getting-started.md index 50d96b6bdf..921c3b1fa2 100644 --- a/docs/content/developer/getting-started.md +++ b/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" ... } ``` diff --git a/docs/content/developer/overview.md b/docs/content/developer/overview.md index e010594da4..b15ab5b605 100644 --- a/docs/content/developer/overview.md +++ b/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. diff --git a/docs/content/developer/settings.md b/docs/content/developer/settings.md index db61629099..15f1b57b02 100644 --- a/docs/content/developer/settings.md +++ b/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 } diff --git a/docs/content/developer/use-case-configuration.md b/docs/content/developer/use-case-configuration.md new file mode 100644 index 0000000000..c71b7bc59a --- /dev/null +++ b/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). \ No newline at end of file diff --git a/docs/content/developer/workflow.md b/docs/content/developer/workflow.md index a4ffcfb12a..1cc886ccb4 100644 --- a/docs/content/developer/workflow.md +++ b/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 filters = d2.eventModule().eventFilters().blockingGet(); List workingLists = d2.programModule().programStageWorkingLists().blockingGet(); // Apply the filters -d2.trackedEntityModule().trackedEntityInstanceQuery() +d2.trackedEntityModule().trackedEntitySearch() .byTrackedEntityInstanceFilter().eq("filterUid") .byProgramStageWorkingList().eq("workingListUid") .get() diff --git a/docs/dhis2_android_sdk_dev_guide_INDEX.md b/docs/dhis2_android_sdk_dev_guide_INDEX.md index f3a240f864..efdb673f49 100644 --- a/docs/dhis2_android_sdk_dev_guide_INDEX.md +++ b/docs/dhis2_android_sdk_dev_guide_INDEX.md @@ -1,5 +1,5 @@ -!INCLUDE "content/dev/developement.md" +!INCLUDE "content/dev/development.md" !INCLUDE "content/dev/architecture.md" !INCLUDE "content/dev/synchronization.md" \ No newline at end of file diff --git a/docs/dhis2_android_sdk_developer_guide_INDEX.yml b/docs/dhis2_android_sdk_developer_guide_INDEX.yml index 2f8a413e7d..d8973b5264 100644 --- a/docs/dhis2_android_sdk_developer_guide_INDEX.yml +++ b/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)"