diff --git a/.github/workflows/rebuild-docs.yml b/.github/workflows/rebuild-docs.yml new file mode 100644 index 000000000..a9fe4dcd8 --- /dev/null +++ b/.github/workflows/rebuild-docs.yml @@ -0,0 +1,19 @@ +name: 'dhis2: rebuild developer docs' + +on: + push: + branches: + - master + paths: + - 'docs/**' + - 'CHANGELOG.md' + +concurrency: + group: ${{ github.workflow}}-${{ github.ref }} + cancel-in-progress: true + +jobs: + rebuild-docs: + runs-on: ubuntu-latest + steps: + - run: curl -X POST -d {} https://api.netlify.com/build_hooks/${{ secrets.NETLIFY_DEVELOPER_DOCS_TOKEN }} diff --git a/CHANGELOG.md b/CHANGELOG.md index 1890fccbc..97094a03a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,10 @@ +## [3.9.4](https://github.com/dhis2/app-runtime/compare/v3.9.3...v3.9.4) (2023-06-19) + + +### Bug Fixes + +* **types:** add generic result type to oncomplete param ([#1350](https://github.com/dhis2/app-runtime/issues/1350)) ([a069603](https://github.com/dhis2/app-runtime/commit/a069603b4f3b2c9caa2158d7b4087e432cf90668)) + ## [3.9.3](https://github.com/dhis2/app-runtime/compare/v3.9.2...v3.9.3) (2023-05-16) diff --git a/README.md b/README.md index 4fc98a0dd..4f640356a 100644 --- a/README.md +++ b/README.md @@ -21,7 +21,7 @@ A query REPL platform application is also available at `./examples/query-playgro Running `yarn build` at root will automatically update the example app's copy, and running `yarn start` will build the runtime and then start the example. -A [`DHIS2 App Platform`](https://platform.dhis2.nu) example is available at [./examples/query-playground](./examples/query-playground). This is a full, deployable DHIS2 application and a live standalone version is available at [runtime.dhis2.nu/playground](https://runtime.dhis2.nu/playground) +A [`DHIS2 App Platform`](https://platform.dhis2.nu) example is available at [./examples/query-playground](./examples/query-playground). This is a full, deployable DHIS2 application and a live standalone version is available at [every play instance](https://play.dhis2.org), such as the `dev` instance [play.dhis2.org/dev](https://play.dhis2.org/dev/api/apps/query-playground/index.html). ## Release diff --git a/docs/advanced/offline/README.md b/docs/advanced/offline/README.md index 15afd54c4..847bffd80 100644 --- a/docs/advanced/offline/README.md +++ b/docs/advanced/offline/README.md @@ -1,10 +1,12 @@ # Offline tools -!> **WARNING** These features are considered **experimental** and are **subject to breaking changes outside of the normal release cycle.** +:::warning Experimental +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. +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"](./CacheableSections.md), which are sections of an app that can be individually cached on-demand. The [`useCacheableSection` hook](./CacheableSections.md#usecacheablesection-api) and the [`CacheableSection` component](./CacheableSections.md#cacheablesection-api) provide the controls for the section and the wrapper for the section, respectively. The [`useCachedSections` hook](./CacheableSections.md#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. +An important tool for offline-capable apps is the [`useDhis2ConnectionStatus` hook](./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](./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 diff --git a/docs/advanced/offline/useOnlineStatus.md b/docs/advanced/offline/useOnlineStatus.md index 366a797fc..5ee5a2606 100644 --- a/docs/advanced/offline/useOnlineStatus.md +++ b/docs/advanced/offline/useOnlineStatus.md @@ -1,6 +1,8 @@ # 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. +:::info Internet Only +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](./useDhis2ConnectionStatus.md) 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. diff --git a/docs/advanced/services.md b/docs/advanced/services.md index 7462f7832..7e9646591 100644 --- a/docs/advanced/services.md +++ b/docs/advanced/services.md @@ -1,6 +1,8 @@ # Services -!> **NOTE**
Services are purely a concept **internal** to `@dhis2/app-runtime` - you don't need to care about them to use it. +:::caution Note +Services are purely a concept **internal** to `@dhis2/app-runtime` - you don't need to care about them to use it. +::: Internally, `@dhis2/app-runtime` is composed of several functionally-isolated **services**. Each of these services is a private (unpublished) npm package which is bundled into the final `@dhis2/app-runtime` library at build-time. Each services exposes a relevant Context provider as well as various Hook and Component interfaces which are re-exported by the `@dhis2/app-runtime` public package. There are currently only 2 services, but more will be added soon. diff --git a/docs/components/DataMutation.md b/docs/components/DataMutation.md index fa8dc8f2c..914f02c0c 100644 --- a/docs/components/DataMutation.md +++ b/docs/components/DataMutation.md @@ -1,6 +1,6 @@ # DataMutation Component -A thin wrapper around the [useDataMutation](hooks/useDataMutation.md) hook +A thin wrapper around the [useDataMutation](../hooks/useDataMutation.md) hook ## Basic Usage @@ -19,13 +19,13 @@ return ( ## Input Props -| Name | Type | Required | Description | -| :------------: | :-----------------------------: | :----------: | ----------------------------------------------------------------------------------------------------------------------------- | -| **mutation** | [_Mutation_](types/Mutation.md) | **required** | The Mutation definition describing the requested operation | -| **variables** | _Object_ | | Variables to be passed to the dynamic portions of the mutation | -| **onComplete** | _Function_ | | Callback function to be called on successfull completion of the mutation. Called with the response data as the only argument. | -| **onError** | _Function_ | | Callback function to be called on failure of the mutation. Called with the error instance as the only argument. | -| **lazy** | _boolean_ | | If false, run the mutation immediately after the component mounts.
_**Default**: `true`_ | +| Name | Type | Required | Description | +| :------------: | :--------------------------------: | :----------: | ----------------------------------------------------------------------------------------------------------------------------- | +| **mutation** | [_Mutation_](../types/Mutation.md) | **required** | The Mutation definition describing the requested operation | +| **variables** | _Object_ | | Variables to be passed to the dynamic portions of the mutation | +| **onComplete** | _Function_ | | Callback function to be called on successfull completion of the mutation. Called with the response data as the only argument. | +| **onError** | _Function_ | | Callback function to be called on failure of the mutation. Called with the error instance as the only argument. | +| **lazy** | _boolean_ | | If false, run the mutation immediately after the component mounts.
_**Default**: `true`_ | ## Render Function Props @@ -34,13 +34,13 @@ The render function is called whenever the state of the mutation changes. It is 1. `mutate` - a function which can be called to trigger the mutation (for instance in an onClick callback) 2. `state` - an object containing the following properties: -| Name | Type | Description | -| :---------: | :-------------------------------------: | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| **called** | _boolean_ | **true** if the mutation has been triggered through a call to the `mutate` function or on component mount with `lazy: false` | -| **loading** | _boolean_ | **true** if the data is not yet available and no error has yet been encountered | -| **error** | _Error_
or
_undefined_ | **undefined** if no error has occurred, otherwise the Error which was thrown | -| **data** | _MutationResult_
or
_undefined_ | **undefined** if the data is loading or an error has occurred, otherwise a map from the name of each **QueryDefinition** defined in the **Query** to the resulting data for that query | -| **engine** | [_Data Engine_](advanced/DataEngine) | A reference to the DataEngine instance | +| Name | Type | Description | +| :---------: | :----------------------------------------: | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **called** | _boolean_ | **true** if the mutation has been triggered through a call to the `mutate` function or on component mount with `lazy: false` | +| **loading** | _boolean_ | **true** if the data is not yet available and no error has yet been encountered | +| **error** | _Error_
or
_undefined_ | **undefined** if no error has occurred, otherwise the Error which was thrown | +| **data** | _MutationResult_
or
_undefined_ | **undefined** if the data is loading or an error has occurred, otherwise a map from the name of each **QueryDefinition** defined in the **Query** to the resulting data for that query | +| **engine** | [_Data Engine_](../advanced/DataEngine.md) | A reference to the DataEngine instance | ## Example diff --git a/docs/components/DataQuery.md b/docs/components/DataQuery.md index 5f1b49a14..a5a741d25 100644 --- a/docs/components/DataQuery.md +++ b/docs/components/DataQuery.md @@ -1,6 +1,6 @@ # DataQuery Component -A thin wrapper around the [useDataQuery](hooks/useDataQuery.md) hook +A thin wrapper around the [useDataQuery](../hooks/useDataQuery.md) hook ## Basic Usage @@ -19,24 +19,24 @@ return ( ## Input Props -| Name | Type | Required | Description | -| :------------: | :-----------------------: | :----------: | -------------------------------------------------------------------------------------------------------------------------- | -| **query** | [_Query_](types/Query.md) | **required** | The Query definition describing the requested data | -| **variables** | _Object_ | | Variables to be passed to the dynamic portions of the query | -| **onComplete** | _Function_ | | Callback function to be called on successfull completion of the query. Called with the response data as the only argument. | -| **onError** | _Function_ | | Callback function to be called on failure of the query. Called with the error instance as the only argument. | -| **lazy** | _boolean_ | | If true, wait until `refetch` is called before fetching data.
_**Default**: `false`_ | +| Name | Type | Required | Description | +| :------------: | :--------------------------: | :----------: | -------------------------------------------------------------------------------------------------------------------------- | +| **query** | [_Query_](../types/Query.md) | **required** | The Query definition describing the requested data | +| **variables** | _Object_ | | Variables to be passed to the dynamic portions of the query | +| **onComplete** | _Function_ | | Callback function to be called on successfull completion of the query. Called with the response data as the only argument. | +| **onError** | _Function_ | | Callback function to be called on failure of the query. Called with the error instance as the only argument. | +| **lazy** | _boolean_ | | If true, wait until `refetch` is called before fetching data.
_**Default**: `false`_ | ## Render Function Props -| Name | Type | Description | -| :---------: | :----------------------------------: | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| **called** | _boolean_ | **true** if the data request has been initiated with either `lazy: false` or `refetch()` at least once | -| **loading** | _boolean_ | **true** if the data is not yet available and no error has yet been encountered | -| **error** | _Error_
or
_undefined_ | **undefined** if no error has occurred, otherwise the Error which was thrown | -| **data** | _QueryResult_
or
_undefined_ | **undefined** if the data is loading or an error has occurred, otherwise a map from the name of each **QueryDefinition** defined in the **Query** to the resulting data for that query | -| **refetch** | _Function_ | This function can be called to refetch the data. Any in-flight HTTP requests will automatically be aborted. | -| **engine** | [_Data Engine_](advanced/DataEngine) | A reference to the DataEngine instance | +| Name | Type | Description | +| :---------: | :----------------------------------------: | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **called** | _boolean_ | **true** if the data request has been initiated with either `lazy: false` or `refetch()` at least once | +| **loading** | _boolean_ | **true** if the data is not yet available and no error has yet been encountered | +| **error** | _Error_
or
_undefined_ | **undefined** if no error has occurred, otherwise the Error which was thrown | +| **data** | _QueryResult_
or
_undefined_ | **undefined** if the data is loading or an error has occurred, otherwise a map from the name of each **QueryDefinition** defined in the **Query** to the resulting data for that query | +| **refetch** | _Function_ | This function can be called to refetch the data. Any in-flight HTTP requests will automatically be aborted. | +| **engine** | [_Data Engine_](../advanced/DataEngine.md) | A reference to the DataEngine instance | ## Example diff --git a/docs/components/README.md b/docs/components/README.md index 3deab07b0..f790d06a4 100644 --- a/docs/components/README.md +++ b/docs/components/README.md @@ -1,6 +1,6 @@ # React Components -As an alternative to [React Hooks](hooks/), the DHIS2 Application Runtime support render-prop React components. The following Components are supported: +As an alternative to [React Hooks](../hooks/README.md), the DHIS2 Application Runtime support render-prop React components. The following Components are supported: -- [**DataQuery**](components/DataQuery) - a data fetching Component wrapper around the [useDataQuery](hooks/useDataQuery) hook. -- [**DataMutation**](components/DataMutation) - a Component wrapper around the [useDataMutation](hooks/useDataMutation) hook. +- [**DataQuery**](./DataQuery.md) - a data fetching Component wrapper around the [useDataQuery](../hooks/useDataQuery.md) hook. +- [**DataMutation**](./DataMutation.md) - a Component wrapper around the [useDataMutation](../hooks/useDataMutation.md) hook. diff --git a/docs/hooks/README.md b/docs/hooks/README.md index d27c5d037..bde9780a2 100644 --- a/docs/hooks/README.md +++ b/docs/hooks/README.md @@ -2,11 +2,11 @@ The DHIS2 Application Runtime supports [React Hooks](https://reactjs.org/docs/hooks-intro.html) (introduced in React 16.8). The following hooks are supported: -- [**useConfig**](hooks/useConfig) - Access the raw application configuration object -- [**useDataQuery**](hooks/useDataQuery) - Fetch data from the DHIS2 Core server API without worrying about HTTP requests! -- [**useDataMutation**](hooks/useDataMutation) - Mutate resources in the DHIS2 Core server API without worrying about HTTP requests! -- [**useDataEngine**](hooks/useDataEngine) _(Advanced)_ - Access the underlying [Data Engine](advanced/DataEngine) instance -- [**useAlert**](hooks/useAlert) - Add an alert to the central alerts-context -- [**useAlerts**](hooks/useAlert) - Read the alerts from the alerts-context +- [**useConfig**](./useConfig.md) - Access the raw application configuration object +- [**useDataQuery**](./useDataQuery.md) - Fetch data from the DHIS2 Core server API without worrying about HTTP requests! +- [**useDataMutation**](./useDataMutation.md) - Mutate resources in the DHIS2 Core server API without worrying about HTTP requests! +- [**useDataEngine**](./useDataEngine.md) _(Advanced)_ - Access the underlying [Data Engine](../advanced/DataEngine.md) instance +- [**useAlert**](./useAlert.md) - Add an alert to the central alerts-context +- [**useAlerts**](./useAlerts.md) - Read the alerts from the alerts-context -While these Hooks are incredibly powerful and usually preferable, some [Components](components/) are also provided which conveniently wrap their corresponding Hooks. +While these Hooks are incredibly powerful and usually preferable, some [Components](../components/README.md) are also provided which conveniently wrap their corresponding Hooks. diff --git a/docs/hooks/useConfig.md b/docs/hooks/useConfig.md index 93e39d61b..0c8aefc62 100644 --- a/docs/hooks/useConfig.md +++ b/docs/hooks/useConfig.md @@ -1,6 +1,6 @@ # useConfig Hook -Access the application configuration passed to the top-level [Provider](provider.md) +Access the application configuration passed to the top-level [Provider](../provider.md) ## Basic Usage: @@ -17,7 +17,7 @@ _None_ ## Output -This hook returns an object of type [Config](types/Config.md). +This hook returns an object of type [Config](../types/Config.md). ## Example diff --git a/docs/hooks/useDataEngine.md b/docs/hooks/useDataEngine.md index bbd2c1fc5..d22582392 100644 --- a/docs/hooks/useDataEngine.md +++ b/docs/hooks/useDataEngine.md @@ -1,6 +1,6 @@ # useDataEngine hook -Get access to the [Data Engine](advanced/DataEngine) instance for non-React contexts. +Get access to the [Data Engine](../advanced/DataEngine.md) instance for non-React contexts. ## Basic Usage: @@ -19,4 +19,4 @@ engine.mutate(mutation, { }) ``` -> See [Using with Redux](advanced/redux) for an advanced example +> See [Using with Redux](../advanced/redux.md) for an advanced example diff --git a/docs/hooks/useDataMutation.md b/docs/hooks/useDataMutation.md index 69b322626..0cc049419 100644 --- a/docs/hooks/useDataMutation.md +++ b/docs/hooks/useDataMutation.md @@ -16,25 +16,25 @@ const [mutate, { called, loading, error, data }] = useDataMutation( ## Input -| Name | Type | Required | Description | -| :--------------------: | :-----------------------------: | :----------: | ----------------------------------------------------------------------------------------------------------------------------- | -| **mutation** | [_Mutation_](types/Mutation.md) | **required** | The Mutation definition describing the requested action | -| **options** | _Object_ | | An optional set of query options | -| **options.variables** | _Object_ | | Variables to be passed to the dynamic portions of the mutation | -| **options.onComplete** | _Function_ | | Callback function to be called on successfull completion of the mutation. Called with the response data as the only argument. | -| **options.onError** | _Function_ | | Callback function to be called on failure of the mutation. Called with the error instance as the only argument. | -| **options.lazy** | _boolean_ | | If false, run the mutation immediately after the component mounts.
_**Default**: `true`_ | +| Name | Type | Required | Description | +| :--------------------: | :--------------------------------: | :----------: | ----------------------------------------------------------------------------------------------------------------------------- | +| **mutation** | [_Mutation_](../types/Mutation.md) | **required** | The Mutation definition describing the requested action | +| **options** | _Object_ | | An optional set of query options | +| **options.variables** | _Object_ | | Variables to be passed to the dynamic portions of the mutation | +| **options.onComplete** | _Function_ | | Callback function to be called on successfull completion of the mutation. Called with the response data as the only argument. | +| **options.onError** | _Function_ | | Callback function to be called on failure of the mutation. Called with the error instance as the only argument. | +| **options.lazy** | _boolean_ | | If false, run the mutation immediately after the component mounts.
_**Default**: `true`_ | ## Output -| Name | Type | Description | -| :---------: | :----------------------------------: | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| **mutate** | _Function_ | This function can be called to execute the mutation. Any in-flight HTTP requests will automatically be aborted. | -| **called** | _boolean_ | **true** if the mutation has been triggered by a call to the `mutate` function or on component mount with `lazy: false` | -| **loading** | _boolean_ | **true** if the data is not yet available and no error has yet been encountered | -| **error** | _Error_
or
_undefined_ | **undefined** if no error has occurred, otherwise the Error which was thrown | -| **data** | _QueryResult_
or
_undefined_ | **undefined** if the data is loading or an error has occurred, otherwise a map from the name of each **QueryDefinition** defined in the **Query** to the resulting data for that query | -| **engine** | [_Data Engine_](advanced/DataEngine) | A reference to the DataEngine instance | +| Name | Type | Description | +| :---------: | :----------------------------------------: | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **mutate** | _Function_ | This function can be called to execute the mutation. Any in-flight HTTP requests will automatically be aborted. | +| **called** | _boolean_ | **true** if the mutation has been triggered by a call to the `mutate` function or on component mount with `lazy: false` | +| **loading** | _boolean_ | **true** if the data is not yet available and no error has yet been encountered | +| **error** | _Error_
or
_undefined_ | **undefined** if no error has occurred, otherwise the Error which was thrown | +| **data** | _QueryResult_
or
_undefined_ | **undefined** if the data is loading or an error has occurred, otherwise a map from the name of each **QueryDefinition** defined in the **Query** to the resulting data for that query | +| **engine** | [_Data Engine_](../advanced/DataEngine.md) | A reference to the DataEngine instance | ## Example diff --git a/docs/hooks/useDataQuery.md b/docs/hooks/useDataQuery.md index dd6b4a161..b5478d546 100644 --- a/docs/hooks/useDataQuery.md +++ b/docs/hooks/useDataQuery.md @@ -13,25 +13,25 @@ const { loading, error, data, refetch } = useDataQuery(query, options) ## Input -| Name | Type | Required | Description | -| :--------------------: | :--------------------: | :----------: | --------------------------------------------------------------------------------------------------------------------------- | -| **query** | [_Query_](types/Query) | **required** | The Query definition describing the requested data | -| **options** | _Object_ | | An optional set of query options | -| **options.variables** | _Object_ | | Variables to be passed to the dynamic portions of the query (can also be passed via the refetch function, see Output below) | -| **options.onComplete** | _Function_ | | Callback function to be called on successfull completion of the query. Called with the response data as the only argument. | -| **options.onError** | _Function_ | | Callback function to be called on failure of the query. Called with the error instance as the only argument. | -| **options.lazy** | _boolean_ | | If true, wait until `refetch` is called before fetching data.
_**Default**: `false`_ | +| Name | Type | Required | Description | +| :--------------------: | :--------------------------: | :----------: | --------------------------------------------------------------------------------------------------------------------------- | +| **query** | [_Query_](../types/Query.md) | **required** | The Query definition describing the requested data | +| **options** | _Object_ | | An optional set of query options | +| **options.variables** | _Object_ | | Variables to be passed to the dynamic portions of the query (can also be passed via the refetch function, see Output below) | +| **options.onComplete** | _Function_ | | Callback function to be called on successfull completion of the query. Called with the response data as the only argument. | +| **options.onError** | _Function_ | | Callback function to be called on failure of the query. Called with the error instance as the only argument. | +| **options.lazy** | _boolean_ | | If true, wait until `refetch` is called before fetching data.
_**Default**: `false`_ | ## Output -| Name | Type | Description | -| :---------: | :----------------------------------: | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| **called** | _boolean_ | **true** if the data request has been initiated with either `lazy: false` or `refetch()` at least once | -| **loading** | _boolean_ | **true** if the data is not yet available and no error has yet been encountered | -| **error** | _Error_
or
_undefined_ | **undefined** if no error has occurred, otherwise the Error which was thrown | -| **data** | _QueryResult_
or
_undefined_ | **undefined** if the data is loading or an error has occurred, otherwise a map from the name of each **QueryDefinition** defined in the **Query** to the resulting data for that query | -| **refetch** | _Function_ | This function can be called to refetch the data and can accept variables (see Examples below). Any in-flight HTTP requests will automatically be aborted. | -| **engine** | [_Data Engine_](advanced/DataEngine) | A reference to the DataEngine instance | +| Name | Type | Description | +| :---------: | :----------------------------------------: | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **called** | _boolean_ | **true** if the data request has been initiated with either `lazy: false` or `refetch()` at least once | +| **loading** | _boolean_ | **true** if the data is not yet available and no error has yet been encountered | +| **error** | _Error_
or
_undefined_ | **undefined** if no error has occurred, otherwise the Error which was thrown | +| **data** | _QueryResult_
or
_undefined_ | **undefined** if the data is loading or an error has occurred, otherwise a map from the name of each **QueryDefinition** defined in the **Query** to the resulting data for that query | +| **refetch** | _Function_ | This function can be called to refetch the data and can accept variables (see Examples below). Any in-flight HTTP requests will automatically be aborted. | +| **engine** | [_Data Engine_](../advanced/DataEngine.md) | A reference to the DataEngine instance | ## Examples diff --git a/docs/index.html b/docs/index.html new file mode 100644 index 000000000..4fb409912 --- /dev/null +++ b/docs/index.html @@ -0,0 +1,18 @@ + + + + + Redirecting to Developer Portal + + +

Redirecting to Developer Portal...

+ + + + diff --git a/docs/provider.md b/docs/provider.md index 706abebc9..516167da2 100644 --- a/docs/provider.md +++ b/docs/provider.md @@ -2,9 +2,9 @@ ## Input Props -| Name | Type | Description | -| :--------: | :-------------------------: | ----------------------------- | -| **config** | [_Config_](types/Config.md) | The application configuration | +| Name | Type | Description | +| :--------: | :---------------------------: | ----------------------------- | +| **config** | [_Config_](./types/Config.md) | The application configuration | ## Example diff --git a/docs/types/Config.md b/docs/types/Config.md index 8d0c221ac..85c0b42ec 100644 --- a/docs/types/Config.md +++ b/docs/types/Config.md @@ -1,8 +1,8 @@ # Config Type The Application Config type is a required input to the top-level -[Provider](provider), and can be accessed from within an application -with the [useConfig](hooks/useConfig) hook. +[Provider](../provider.md), and can be accessed from within an application +with the [useConfig](../hooks/useConfig.md) hook. | Property | Type | Description | | :------------: | :------: | --------------------------------------------------------------------------------------------------------------- | diff --git a/docs/types/Mutation.md b/docs/types/Mutation.md index 4067e997d..78b057ad0 100644 --- a/docs/types/Mutation.md +++ b/docs/types/Mutation.md @@ -1,6 +1,6 @@ # Mutation -The Mutation type is used to define declarative data mutations. It is required input for the [useDataMutation](hooks/useDataMutation.md) hook, [DataMutation](components/DataMutation.md) component, and [DataEngine.mutate](advanced/DataEngine) method. +The Mutation type is used to define declarative data mutations. It is required input for the [useDataMutation](../hooks/useDataMutation.md) hook, [DataMutation](../components/DataMutation.md) component, and [DataEngine.mutate](../advanced/DataEngine.md) method. A mutation defines a destructive operation performed on a collection or instance of a particular resource. diff --git a/docs/types/Query.md b/docs/types/Query.md index 4698021db..4952c33b2 100644 --- a/docs/types/Query.md +++ b/docs/types/Query.md @@ -1,6 +1,6 @@ # Data Queries -The Query type is used to define declarative data requests. It is required input for the [useDataQuery](hooks/useDataQuery.md) hook and [DataQuery](components/DataQuery.md) component. +The Query type is used to define declarative data requests. It is required input for the [useDataQuery](../hooks/useDataQuery.md) hook and [DataQuery](../components/DataQuery.md) component. ## Query diff --git a/package.json b/package.json index 20e0844c7..8093f3ff4 100644 --- a/package.json +++ b/package.json @@ -1,5 +1,5 @@ { - "version": "3.9.3", + "version": "3.9.4", "description": "A singular runtime dependency for applications on the DHIS2 platform", "repository": "https://github.com/dhis2/app-runtime.git", "author": "Austin McGee ", @@ -49,7 +49,7 @@ "test": "yarn test:services && yarn test:runtime", "format": "d2-style apply js --all --no-stage && d2-style apply text --all --no-stage", "start": "yarn build && cd examples/query-playground && yarn start", - "docs:build": "d2-utils-docsite build ./docs -o ./dist && yarn build:playground", + "docs:build": "mkdir -p dist && cp docs/index.html dist/ && yarn build:playground", "docs:serve": "d2-utils-docsite serve ./docs -o ./dist", "lint": "d2-style check js && d2-style check text" }, diff --git a/runtime/package.json b/runtime/package.json index eb7a1e324..6c32d836d 100644 --- a/runtime/package.json +++ b/runtime/package.json @@ -1,7 +1,7 @@ { "name": "@dhis2/app-runtime", "description": "A singular runtime dependency for applications on the DHIS2 platform", - "version": "3.9.3", + "version": "3.9.4", "main": "./build/cjs/index.js", "module": "./build/es/index.js", "types": "./build/types/index.d.ts", @@ -23,10 +23,10 @@ "build/**" ], "dependencies": { - "@dhis2/app-service-config": "3.9.3", - "@dhis2/app-service-data": "3.9.3", - "@dhis2/app-service-alerts": "3.9.3", - "@dhis2/app-service-offline": "3.9.3" + "@dhis2/app-service-config": "3.9.4", + "@dhis2/app-service-data": "3.9.4", + "@dhis2/app-service-alerts": "3.9.4", + "@dhis2/app-service-offline": "3.9.4" }, "peerDependencies": { "prop-types": "^15.7.2", diff --git a/services/alerts/package.json b/services/alerts/package.json index 43755ff0a..20486ee19 100644 --- a/services/alerts/package.json +++ b/services/alerts/package.json @@ -1,6 +1,6 @@ { "name": "@dhis2/app-service-alerts", - "version": "3.9.3", + "version": "3.9.4", "main": "./build/cjs/index.js", "module": "./build/es/index.js", "types": "./build/types/index.d.ts", diff --git a/services/config/package.json b/services/config/package.json index 60531f0f2..f5675e573 100644 --- a/services/config/package.json +++ b/services/config/package.json @@ -1,6 +1,6 @@ { "name": "@dhis2/app-service-config", - "version": "3.9.3", + "version": "3.9.4", "main": "./build/cjs/index.js", "module": "./build/es/index.js", "types": "build/types/index.d.ts", diff --git a/services/data/package.json b/services/data/package.json index eb2b31505..bc783c446 100644 --- a/services/data/package.json +++ b/services/data/package.json @@ -1,6 +1,6 @@ { "name": "@dhis2/app-service-data", - "version": "3.9.3", + "version": "3.9.4", "main": "./build/cjs/index.js", "module": "./build/es/index.js", "types": "build/types/index.d.ts", @@ -22,7 +22,7 @@ "build/**" ], "peerDependencies": { - "@dhis2/app-service-config": "3.9.3", + "@dhis2/app-service-config": "3.9.4", "@dhis2/cli-app-scripts": "^7.1.1", "prop-types": "^15.7.2", "react": "^16.8", diff --git a/services/data/src/engine/types/Query.ts b/services/data/src/engine/types/Query.ts index 5a79c1c67..e058b53c6 100644 --- a/services/data/src/engine/types/Query.ts +++ b/services/data/src/engine/types/Query.ts @@ -21,9 +21,9 @@ export interface ResolvedResourceQuery extends ResourceQuery { export type Query = Record export type QueryResult = JsonMap -export interface QueryOptions { +export interface QueryOptions { variables?: QueryVariables - onComplete?: (data: QueryResult) => void + onComplete?: (data: TQueryResult) => void onError?: (error: FetchError) => void lazy?: boolean } diff --git a/services/data/src/react/hooks/useDataQuery.ts b/services/data/src/react/hooks/useDataQuery.ts index 9b81a145d..ea9cafe28 100644 --- a/services/data/src/react/hooks/useDataQuery.ts +++ b/services/data/src/react/hooks/useDataQuery.ts @@ -40,7 +40,7 @@ export const useDataQuery = ( onError: userOnError, variables: initialVariables = {}, lazy: initialLazy = false, - }: QueryOptions = {} + }: QueryOptions = {} ): QueryRenderInput => { const [staticQuery] = useStaticInput(query, { warn: true, diff --git a/services/offline/package.json b/services/offline/package.json index a4831ee5b..dc86f3008 100644 --- a/services/offline/package.json +++ b/services/offline/package.json @@ -1,7 +1,7 @@ { "name": "@dhis2/app-service-offline", "description": "A runtime service for online/offline detection and offline caching", - "version": "3.9.3", + "version": "3.9.4", "main": "./build/cjs/index.js", "module": "./build/es/index.js", "types": "build/types/index.d.ts", @@ -33,7 +33,7 @@ "coverage": "yarn test --coverage" }, "peerDependencies": { - "@dhis2/app-service-config": "3.9.3", + "@dhis2/app-service-config": "3.9.4", "prop-types": "^15.7.2", "react": "^16.8.6", "react-dom": "^16.8.6"