resource
Required
Required
| id of the item in the resource | `string` | |
-| queryOptions | `react-query`'s `useQuery` options | ` UseQueryOptions<``{ data: TData; },`
`TError>` | | -| successNotification | Successful Query notification | [`SuccessErrorNotification`](../../interfaces.md#successerrornotification) | `false` | -| errorNotification | Unsuccessful Query notification | [`SuccessErrorNotification`](../../interfaces.md#successerrornotification) | "Error (status code: `statusCode`)" | -| metaData | Metadata query for `dataProvider` | [`MetaDataQuery`](/api-references/interfaces.md#metadataquery) | {} | +| Property | Description | Type | Default | +| --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------- | ----------------------------------- | +|
resource
Required
Required
| id of the item in the resource | `string` | |
+| queryOptions | `react-query`'s `useQuery` options | ` UseQueryOptions<``{ data: TData; },`
`TError>` | | +| successNotification | Successful Query notification | [`SuccessErrorNotification`](../../interfaces.md#successerrornotification) | `false` | +| errorNotification | Unsuccessful Query notification | [`SuccessErrorNotification`](../../interfaces.md#successerrornotification) | "Error (status code: `statusCode`)" | +| metaData | Metadata query for `dataProvider` | [`MetaDataQuery`](/api-references/interfaces.md#metadataquery) | {} | +| [liveMode](/api-references/providers/live-provider.md#usage-in-a-hook) | Whether to update data automatically (`"auto"`) or not (`"manual"`) if a related live event is received. The "off" value is used to avoid creating a subscription. | [``"auto"` \| `"manual"` \| `"off"``](/api-references/interfaces.md#livemodeprops) | `"off"` | +| liveParams | Params to pass to `liveProvider`'s `subscribe` method if `liveMode` is enabled. | [`{ ids?: string[]; [key: string]: any; }`](/api-references/interfaces.md#livemodeprops) | `undefined` | +| onLiveEvent | Callback to handle all related live events of this hook. | [`(event: LiveEvent) => void`](/api-references/interfaces.md#livemodeprops) | `undefined` | ### Type Parameters diff --git a/documentation/docs/api-references/hooks/field/useCheckboxGroup.md b/documentation/docs/api-references/hooks/field/useCheckboxGroup.md index 174358b1d908..8209c72b1525 100644 --- a/documentation/docs/api-references/hooks/field/useCheckboxGroup.md +++ b/documentation/docs/api-references/hooks/field/useCheckboxGroup.md @@ -165,6 +165,9 @@ const { checkboxGroupProps } = useCheckboxGroup({ | sort | Allows us to sort the options | [`CrudSorting`](../../interfaces.md#crudsorting) | | | queryOptions | react-query [useQuery](https://react-query.tanstack.com/reference/useQuery) options | ` UseQueryOptions
- ` component fro
| onSearch | When the search form is submitted, it creates the 'CrudFilters' object. See here to create a [search form][list search] | `Function` | |
| queryOptions | `react-query`'s `useQuery` options | ` UseQueryOptions<{ data: TData[] }, TError>` |
| metaData | Metadata query for `dataProvider` | [`MetaDataQuery`](/api-references/interfaces.md#metadataquery) | {} |
+| [liveMode](/api-references/providers/live-provider.md#usage-in-a-hook) | Whether to update data automatically (`"auto"`) or not (`"manual"`) if a related live event is received. The "off" value is used to avoid creating a subscription. | [``"auto"` \| `"manual"` \| `"off"``](/api-references/interfaces.md#livemodeprops) | `"off"` |
+| liveParams | Params to pass to `liveProvider`'s `subscribe` method if `liveMode` is enabled. | [`{ ids?: string[]; [key: string]: any; }`](/api-references/interfaces.md#livemodeprops) | `undefined` |
+| onLiveEvent | Callback to handle all related live events of this hook. | [`(event: LiveEvent) => void`](/api-references/interfaces.md#livemodeprops) | `undefined` |
### Type Parameters
diff --git a/documentation/docs/api-references/hooks/table/useEditableTable.md b/documentation/docs/api-references/hooks/table/useEditableTable.md
index 4a163a34e31d..b48758759b3d 100644
--- a/documentation/docs/api-references/hooks/table/useEditableTable.md
+++ b/documentation/docs/api-references/hooks/table/useEditableTable.md
@@ -310,17 +310,20 @@ export const PostList: React.FC = () => {
### Properties
-| Key | Description | Type |
-| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
-| permanentFilter | Default and unchangeable filter. | [`CrudFilters`][crudfilters] |
-| initialCurrent | Initial page index. | `number` |
-| initialPageSize | Number of records shown per initial number of pages. | `number` |
-| initialSorter | Initial sorting. | [`CrudSorting`][crudsorting] |
-| initialFilter | Initial filtering. | [`CrudFilters`][crudfilters] |
-| syncWithLocation | Sortings, filters, page index and records shown per page are tracked by browser history. | `boolean` |
-| onSearch | When the search form is submitted, it creates the 'CrudFilters' object. Refer to [search form][table search] to learn how to create a search form. | `Function` |
-| queryOptions | `react-query`'s `useQuery` options | ` UseQueryOptions<`
`{ data: TData[]; },`
`TError>` | -| metaData | Metadata query for `dataProvider` | [`MetaDataQuery`](/api-references/interfaces.md#metadataquery) | +| Key | Description | Type | +| --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------- | +| permanentFilter | Default and unchangeable filter. | [`CrudFilters`][crudfilters] | +| initialCurrent | Initial page index. | `number` | +| initialPageSize | Number of records shown per initial number of pages. | `number` | +| initialSorter | Initial sorting. | [`CrudSorting`][crudsorting] | +| initialFilter | Initial filtering. | [`CrudFilters`][crudfilters] | +| syncWithLocation | Sortings, filters, page index and records shown per page are tracked by browser history. | `boolean` | +| onSearch | When the search form is submitted, it creates the 'CrudFilters' object. Refer to [search form][table search] to learn how to create a search form. | `Function` | +| queryOptions | `react-query`'s `useQuery` options | ` UseQueryOptions<`
`{ data: TData[]; },`
`TError>` | +| metaData | Metadata query for `dataProvider` | [`MetaDataQuery`](/api-references/interfaces.md#metadataquery) | +| [liveMode](/api-references/providers/live-provider.md#usage-in-a-hook) | Whether to update data automatically (`"auto"`) or not (`"manual"`) if a related live event is received. The "off" value is used to avoid creating a subscription. | [``"auto"` \| `"manual"` \| `"off"``](/api-references/interfaces.md#livemodeprops) | +| liveParams | Params to pass to `liveProvider`'s `subscribe` method if `liveMode` is enabled. | [`{ ids?: string[]; [key: string]: any; }`](/api-references/interfaces.md#livemodeprops) | +| onLiveEvent | Callback to handle all related live events of this hook. | [`(event: LiveEvent) => void`](/api-references/interfaces.md#livemodeprops) | ### Type Parameters diff --git a/documentation/docs/api-references/hooks/table/useTable.md b/documentation/docs/api-references/hooks/table/useTable.md index 607851a5ee20..9cfd5f370f61 100644 --- a/documentation/docs/api-references/hooks/table/useTable.md +++ b/documentation/docs/api-references/hooks/table/useTable.md @@ -357,6 +357,9 @@ Filters we give to `initialFilter` are default filters. In order to prevent filt | onSearch | When the search form is submitted, it creates the 'CrudFilters' object. Refer to [search form][table search] to learn how to create a search form | `Function` | | queryOptions | `react-query`'s `useQuery` options | ` UseQueryOptions<`
`{ data: TData[]; },`
`TError>` | | metaData | Metadata query for `dataProvider` | [`MetaDataQuery`](/api-references/interfaces.md#metadataquery) | {} | +| [liveMode](/api-references/providers/live-provider.md#usage-in-a-hook) | Whether to update data automatically (`"auto"`) or not (`"manual"`) if a related live event is received. The "off" value is used to avoid creating a subscription. | [``"auto"` \| `"manual"` \| `"off"``](/api-references/interfaces.md#livemodeprops) | `"off"` | +| liveParams | Params to pass to `liveProvider`'s `subscribe` method if `liveMode` is enabled. | [`{ ids?: string[]; [key: string]: any; }`](/api-references/interfaces.md#livemodeprops) | `undefined` | +| onLiveEvent | Callback to handle all related live events of this hook. | [`(event: LiveEvent) => void`](/api-references/interfaces.md#livemodeprops) | `undefined` | ### Type Parameters diff --git a/documentation/docs/api-references/interfaces.md b/documentation/docs/api-references/interfaces.md index ea17a76a6bc8..629c1aec31e2 100644 --- a/documentation/docs/api-references/interfaces.md +++ b/documentation/docs/api-references/interfaces.md @@ -181,3 +181,20 @@ ButtonProps | ------- | --------- | | can | `boolean` | | reason? | `string` | + +## LiveEvent + +| Key | Type | +| ------- | -------------------------------------------------------------- | +| channel | `string` | +| type | `"deleted"` \| `"updated"` \| `"created"` \| "`*`" \| `string` | +| payload | `{ids?: string[]; [x: string]: any; }` | +| date | `Date` | + +## LiveModeProps + +| Key | Type | +| ------------ | -------------------------------------- | +| liveMode? | `"auto"` \| `"manual"` \| `"off"` | +| liveParams? | `{ids?: string[]; [x: string]: any; }` | +| onLiveEvent? | `(event: LiveEvent) => void` | diff --git a/documentation/docs/api-references/providers/live-provider.md b/documentation/docs/api-references/providers/live-provider.md new file mode 100644 index 000000000000..c64e83eb8424 --- /dev/null +++ b/documentation/docs/api-references/providers/live-provider.md @@ -0,0 +1,570 @@ +--- +id: live-provider +title: Live Provider +--- + +## Overview + +**refine** lets you add Realtime support to your app via `liveProvider` prop for [`
+ +**refine** will use this subscribe method in the [`useSubscription`](/api-references/hooks/live/useSubscription.md) hook. + +```ts +import { useSubscription } from "@pankod/refine"; + +useSubscription({ + channel: "channel-name", + onLiveEvent: (event) => {}, +}); +``` + +> [Refer to the useSubscription documentation for more information. →](/api-references/hooks/live/useSubscription.md) + +
+ +### `unsubscribe` + +This method is used to unsubscribe from a channel. The values returned from the `subscribe` method are passed to the `unsubscribe` method. + +```ts title="liveProvider.ts" +const liveProvider = (client: Ably.Realtime): LiveProvider => { + return { + // highlight-start + unsubscribe: (payload: { + channelInstance: Types.RealtimeChannelPromise; + listener: () => void; + }) => { + const { channelInstance, listener } = payload; + channelInstance.unsubscribe(listener); + }, + // highlight-end + }; +}; +``` + +:::caution +If you don't handle unsubscription it could lead to memory leaks. +::: + +#### Parameter Types + +| Name | Type | Description | +| ------------ | ----- | ---------------------------------------- | +| subscription | `any` | The values returned from the `subscribe` | + +#### Return Type + +| Type | +| ------ | +| `void` | + +
+ +### `publish` + +This method is used to publish an event on client side. Beware that publishing events on client side is not recommended and best practice is to publish events from server side. You can refer [Publish Events from API](#publish-events-from-api) to see which events must be published from the server. + +This `publish` is used in [realated hooks](#publish-events-from-hooks). When `publish` is used, subscribers to these events are notifyed. You can also publish your custom events using [`usePublish`](/api-references/hooks/live/usePublish.md). + +```ts title="liveProvider.ts" +const liveProvider = (client: Ably.Realtime): LiveProvider => { + return { + // highlight-start + publish: (event: LiveEvent) => { + const channelInstance = client.channels.get(event.channel); + + channelInstance.publish(event.type, event); + }, + // highlight-end + }; +}; +``` + +:::caution +If `publish` is used on client side you must handle the security of it by yourself. +::: + +#### Parameter Types + +| Name | Type | +| ----- | ----------- | +| event | `LiveEvent` | + +> [`LiveEvent`](api-references/interfaces.md#liveevent) + +#### Return Type + +| Type | +| ------ | +| `void` | + +
+ +**refine** will provide this publish method via the [`usePublish`](/api-references/hooks/live/usePublish.md) hook. + +```ts +import { usePublish } from "@pankod/refine"; + +const publish = usePublish(); +``` + +> [Refer to the usePublish documentation for more information. →](/api-references/hooks/live/usePublish.md) + +## `liveMode` + +`liveMode` must be passed to either `
+
+ 
+
+
+## Configuring `liveMode`
+
+We may not want to make Realtime changes instantly in some cases. In these cases we can use `manual` mode to prevent the data changing instantly. Then we can handle the event manually.
+
+For example in an edit page for a record, It would be better to handle Realtime data manually to prevent synchronization problems caused by multiple editing sources. We would not want the data changing while we are trying to edit a record.
+
+We will be alerting about changes in an alert box on top of the form instead of changing the data instantly.
+
+```tsx title="src/pages/posts/edit.tsx"
+// ...
+
+export const PostEdit: React.FC = () => {
+ //highlight-start
+ const [deprecated, setDeprecated] =
+ useState<"deleted" | "updated" | undefined>();
+ //highlight-end
+
+ const { formProps, saveButtonProps, queryResult } = useForm
+
+
+
+
+ +
+ 
+
+
+## Custom Subscriptions
+
+You can subscribe to events emitted within **refine** in any place in your app with `useSubscription`.
+
+For example, we can subscribe to **_create_** event for **_posts_** resource and we can show a badge for number of events in the sider menu.
+
+Firstly, let's implement a custom sider like in [this example](/examples/customization/customSider.md).
+
+
+
+
+
+
+
+(false);
+ const Title = useTitle();
+ const { menuItems, selectedKey } = useMenu();
+ const breakpoint = Grid.useBreakpoint();
+ const { push } = useNavigation();
+
+ const isMobile = !breakpoint.lg;
+
+ return (
+ setCollapsed(collapsed)}
+ style={isMobile ? antLayoutSiderMobile : antLayoutSider}
+ >
+
+ );
+};
+```
+
+
+
+Now, let's add a badge for number of create and update events for **_posts_** menu item.
+
+```tsx
+import React, { useState } from "react";
+import {
+ AntdLayout,
+ Menu,
+ useMenu,
+ useTitle,
+ useNavigation,
+ Grid,
+ Icons,
+ //highlight-start
+ Badge,
+ useSubscription,
+ //highlight-end
+} from "@pankod/refine";
+import { antLayoutSider, antLayoutSiderMobile } from "./styles";
+
+export const CustomSider: React.FC = () => {
+ const [subscriptionCount, setSubscriptionCount] = useState(0);
+ const [collapsed, setCollapsed] = useStateCustom Sider Menu
+ +```tsx title="src/components/sider.tsx" +import React, { useState } from "react"; +import { + AntdLayout, + Menu, + useMenu, + useTitle, + useNavigation, + Grid, + Icons, +} from "@pankod/refine"; +import { antLayoutSider, antLayoutSiderMobile } from "./styles"; + +export const CustomSider: React.FC = () => { + const [collapsed, setCollapsed] = useState+
+ 
+
+
+## Live Condesandbox Example
+
+
diff --git a/documentation/sidebars.js b/documentation/sidebars.js
index 52183e8d4909..6331a1c08b5b 100644
--- a/documentation/sidebars.js
+++ b/documentation/sidebars.js
@@ -19,6 +19,7 @@ module.exports = {
items: [
"api-references/providers/auth-provider",
"api-references/providers/data-provider",
+ "api-references/providers/live-provider",
"api-references/providers/accessControl-provider",
"api-references/providers/i18n-provider",
"api-references/providers/router-provider",
@@ -64,6 +65,14 @@ module.exports = {
"api-references/hooks/accessControl/useCan",
],
},
+ {
+ type: "category",
+ label: "Live",
+ items: [
+ "api-references/hooks/live/useSubscription",
+ "api-references/hooks/live/usePublish",
+ ],
+ },
{
type: "category",
label: "Form",
@@ -233,6 +242,7 @@ module.exports = {
},
"guides-and-concepts/ssr-nextjs",
"guides-and-concepts/access-control",
+ "guides-and-concepts/real-time",
{
type: "category",
label: "Upload",
diff --git a/documentation/static/img/guides-and-concepts/real-time/custom-sider.gif b/documentation/static/img/guides-and-concepts/real-time/custom-sider.gif
new file mode 100644
index 000000000000..e00dc9e9a2ae
Binary files /dev/null and b/documentation/static/img/guides-and-concepts/real-time/custom-sider.gif differ
diff --git a/documentation/static/img/guides-and-concepts/real-time/manual-mode.gif b/documentation/static/img/guides-and-concepts/real-time/manual-mode.gif
new file mode 100644
index 000000000000..fa812d8cc896
Binary files /dev/null and b/documentation/static/img/guides-and-concepts/real-time/manual-mode.gif differ
diff --git a/documentation/static/img/guides-and-concepts/real-time/real-time.gif b/documentation/static/img/guides-and-concepts/real-time/real-time.gif
new file mode 100644
index 000000000000..b30b1681ac19
Binary files /dev/null and b/documentation/static/img/guides-and-concepts/real-time/real-time.gif differ
diff --git a/examples/ably/.gitignore b/examples/ably/.gitignore
new file mode 100644
index 000000000000..4d29575de804
--- /dev/null
+++ b/examples/ably/.gitignore
@@ -0,0 +1,23 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+/.pnp
+.pnp.js
+
+# testing
+/coverage
+
+# production
+/build
+
+# misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
diff --git a/examples/ably/package.json b/examples/ably/package.json
new file mode 100644
index 000000000000..be2234ae8fee
--- /dev/null
+++ b/examples/ably/package.json
@@ -0,0 +1,38 @@
+{
+ "name": "refine-ably-example",
+ "version": "0.1.0",
+ "private": true,
+ "dependencies": {
+ "@pankod/refine": "^2.0.7",
+ "@pankod/refine-ably": "^2.0.7",
+ "@pankod/refine-react-router": "^2.0.7",
+ "@pankod/refine-simple-rest": "^2.0.7",
+ "@types/node": "^12.20.11",
+ "@types/react": "^17.0.4",
+ "@types/react-dom": "^17.0.4",
+ "react": "^17.0.2",
+ "react-dom": "^17.0.2",
+ "react-markdown": "^6.0.1",
+ "react-mde": "^11.1.0",
+ "react-scripts": "4.0.3",
+ "typescript": "^4.4.3",
+ "web-vitals": "^1.1.1"
+ },
+ "scripts": {
+ "start": "react-scripts start",
+ "build": "react-scripts build",
+ "eject": "react-scripts eject"
+ },
+ "browserslist": {
+ "production": [
+ ">0.2%",
+ "not dead",
+ "not op_mini all"
+ ],
+ "development": [
+ "last 1 chrome version",
+ "last 1 firefox version",
+ "last 1 safari version"
+ ]
+ }
+}
\ No newline at end of file
diff --git a/examples/ably/public/favicon.ico b/examples/ably/public/favicon.ico
new file mode 100644
index 000000000000..2f05c5f484fb
Binary files /dev/null and b/examples/ably/public/favicon.ico differ
diff --git a/examples/ably/public/index.html b/examples/ably/public/index.html
new file mode 100644
index 000000000000..bae69a2d3b94
--- /dev/null
+++ b/examples/ably/public/index.html
@@ -0,0 +1,43 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ -
+
-
+