-
Notifications
You must be signed in to change notification settings - Fork 13
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge branch 'alpha' into LIBS-397/plugin-wrappers-sender
- Loading branch information
Showing
43 changed files
with
7,997 additions
and
5,948 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,40 @@ | ||
| Implements [LIBS-XXXX](https://dhis2.atlassian.net/browse/LIBS-XXXX) | ||
|
|
||
| --- | ||
|
|
||
| ### Key features | ||
|
|
||
| <!-- Remove if not applicable --> | ||
|
|
||
| 1. _feature_ | ||
|
|
||
| --- | ||
|
|
||
| ### Description | ||
|
|
||
| _text_ | ||
|
|
||
| --- | ||
|
|
||
| ### Checklist | ||
|
|
||
| - [ ] Have written Documentation | ||
| - _If not needed, explain why, otherwise remove this bullet point_ | ||
| - [ ] Has tests coverage | ||
| - _If not needed, explain why, otherwise remove this bullet point_ | ||
|
|
||
| --- | ||
|
|
||
| ### Known issues | ||
|
|
||
| <!-- Remove if not applicable --> | ||
|
|
||
| - _issue_ | ||
|
|
||
| --- | ||
|
|
||
| ### Screenshots | ||
|
|
||
| <!-- Remove if not applicable --> | ||
|
|
||
| _supporting text_ |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,11 @@ | ||
| # Offline tools | ||
|
|
||
| !> **WARNING** These features are considered **experimental** and are **subject to breaking changes outside of the normal release cycle.** | ||
|
|
||
| The app platform provides some support for PWA features, including a `manifest.json` file for installability and service worker which can provide offline caching. In addition to those features, the app runtime provides support for ["cacheable sections"](advanced/offline/CacheableSections), which are sections of an app that can be individually cached on-demand. The [`useCacheableSection` hook](advanced/offline/CacheableSections#usecacheablesection-api) and the [`CacheableSection` component](advanced/offline/CacheableSections#cacheablesection-api) provide the controls for the section and the wrapper for the section, respectively. The [`useCachedSections` hook](advanced/offline/CacheableSections#usecachedsections-api) returns a list of sections that are stored in the cache and a function that can delete them. | ||
|
|
||
| An important tool for offline-capable apps is the [`useDhis2ConnectionStatus` hook](advanced/offline/useDhis2ConnectionStatus.md), which can be used to determine whether or not the app can connect to the DHIS2 server. There is also a [`useOnlineStatus` hook](advanced/offline/useOnlineStatus.md) which returns whether or not the client is connected to the internet, but `useDhis2ConnectionStatus` is probably the one you want to use. On instances where DHIS2 is deployed locally in an environment without internet, `useOnlineStatus` can cause problems, because it will always return `false` even though the app can communicate with the DHIS2 server and therefore function just fine. `useDhis2ConnectionStatus` was created to address this problem. | ||
|
|
||
| ## Examples | ||
|
|
||
| To see some examples of the APIs in use, see the [PWA example app](https://github.com/dhis2/app-platform/tree/master/examples/pwa-app/src/components/) in the platform repository. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,48 @@ | ||
| # useDhis2ConnectionStatus | ||
|
|
||
| > This feature can only be used when PWA is enabled in `d2.config.js`. See the [App Platform docs](https://platform.dhis2.nu/#/pwa/pwa) for more information. | ||
| This hook is used to detect whether or not the app can connect to the DHIS2 server. This can be useful, for example, to make changes in the UI to prevent the user from taking actions that would cause errors while unable to reach the server. | ||
|
|
||
| It's designed to detect server connection because checking just the internet connection can lead to problems on DHIS2 instances that are implemented offline, where features or actions might be blocked because the device is offline, even though the app can connect to the DHIS2 server just fine. In these cases, what matters is whether or not the app can connect to the DHIS2 server. | ||
|
|
||
| ```ts | ||
| import { useDhis2ConnectionStatus } from '@dhis2/app-runtime' | ||
|
|
||
| const { isConnected, isDisconnected, lastConnected } = | ||
| useDhis2ConnectionStatus() | ||
| ``` | ||
|
|
||
| ## API | ||
|
|
||
| | Property | Type | Description | | ||
| | ---------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | ||
| | `isConnected` | `boolean` | Represents whether the app can connect to the DHIS2 server | | ||
| | `isDisconnected` | `boolean` | The opposite of `isConnected`. Provided as a convenience value | | ||
| | `lastConnected` | `Date` | The last time the app was able to connect to the server, or `null` when `isConnected` is true. See more [below](#lastconnected-details) about details of this value | | ||
|
|
||
| ### `lastConnected` details | ||
|
|
||
| The value will be persisted locally so it will be consistent across sessions while disconnected. | ||
|
|
||
| Since we can’t actually detect the ‘lastConnected’ value between sessions, the `lastConnected` value is set to “now” if the app starts up while disconnected from the server and can’t find an existing value stored from previous sessions. | ||
|
|
||
| **Tip!** Given the above caveat, this value is most accurately thought of as “Time since starting to work offline”. | ||
|
|
||
| This value can be specific to each app — make sure the ‘appName’ is set in d2.config.js to enable this. Otherwise it will use a value that’s shared between apps. | ||
|
|
||
| ## Design | ||
|
|
||
| This hook is a refinement to `useNetworkStatus`, since it will work for implementations where the server is used locally without internet. | ||
|
|
||
| The `isConnected` value is primarily detected by the service worker, which listens to the incidental network traffic of the app and interprets the value from successes and failures of requests. | ||
|
|
||
| During periods when there’s no network traffic from the app, “pings” will be used **conservatively** to see if the server is reachable. There are several measures taken to limit the usage of these pings: | ||
|
|
||
| - While the connection status is stable, the intervals between pings will increase exponentially up to a long interval. | ||
| - Any new network traffic from the app will postpone future pings. | ||
| - If the app is not focused, no pings will be sent. | ||
|
|
||
| ### Supported versions | ||
|
|
||
| The pings are only sent for server versions that support them, meaning patch versions 2.40.0, 2.39.2, 2.38.3, and 2.37.10. and after. For unsupported versions, the hook will still use the incidental network traffic to determind a connections status value. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,21 @@ | ||
| # useOnlineStatus | ||
|
|
||
| !> This hook only detects whether or not you're connected to the internet, which could be problematic for DHIS2 instances that are hosted locally or offline, where what really matters is whether or not you can communicate with the DHIS2 server. The [`useDhis2ConnectionStatus` hook](advanced/offline/useDhis2ConnectionStatus) is usually better for that reason, and is therefore recommended. | ||
|
|
||
| The `useOnlineStatus` returns whether the client is online or offline. It debounces the returned values by default to prevent rapid changes of any UI elements that depend on the online status. | ||
|
|
||
| ```jsx | ||
| import { useOnlineStatus } from '@dhis2/app-runtime' | ||
|
|
||
| const { online, offline } = useOnlineStatus(options) | ||
| ``` | ||
|
|
||
| The `online` and `offline` return values are booleans, and both are provided for convenience. | ||
|
|
||
| The `options` param is an optional object with the following optional properties: | ||
|
|
||
| | Property | Type | Default | Description | | ||
| | --------------- | ------ | ------- | ---------------------------------------------------------------------------------------- | | ||
| | `debounceDelay` | Number | `1000` | Duration in ms to debounce changing `online` values. Set it to `0` to remove debouncing. | | ||
|
|
||
| Under the hood, the `online` value is initialized to `navigator.onLine`, then the value changes in response to browser `online` and `offline` events. |
Oops, something went wrong.