You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Added a new WebChatProvider component to simplify the use of withWebC… (#9)
* feat: added WebChatProvider and CustomResponsePortalsContainer [skip ci]
- Added a new WebChatProvider component to simplify the use of withWebChat and to add support for
rendering custom responses.
- Added a CustomResponsePortalsContainer component that can be used as a container to handle custom
responses.
- Also filled out more details in the types.
`@ibm-watson/assistant-web-chat-react` is a React library to extend the [web chat](https://cloud.ibm.com/docs/watson-assistant?topic=watson-assistant-deploy-web-chat) feature of [IBM Watson Assistant](https://www.ibm.com/cloud/watson-assistant) within your React application. This makes it easier to provide user-defined response types written in React, add content to custom elements with React, have the web chat and your site communicate more easily, and more.
7
7
8
+
There are two utility functions provided by this library:
9
+
10
+
1. The `WebChatContainer` function is a functional component that makes use of `withWebChat` to load web chat when the component is mounted.
11
+
2. The `withWebChat` function creates a high-order-component (HOC) that you can wrap around an existing component to inject `createWebChatInstance` into it so your component can create a new instance of web chat when appropriate. You can find more information in the [withWebChat documentation](./WITH_WEB_CHAT.md).
12
+
8
13
<details>
9
14
<summary>Table of contents</summary>
10
15
11
16
-[Installation](#installation)
12
-
-[How this works](#how-this-works)
13
-
-[Usage](#usage)
14
-
-[With a functional component](#with-a-functional-component)
15
-
-[With a class component](#with-a-class-component)
This package allows you to inject a property called `createWebChatInstance` as a prop to a given React component. The `createWebChatInstance` method takes a [web chat configuration options object](https://web-chat.global.assistant.watson.cloud.ibm.com/docs.html?to=api-configuration#configurationobject) as an argument and returns an [instance](https://web-chat.global.assistant.watson.cloud.ibm.com/docs.html?to=api-instance-methods) of the web chat that you can now access inside your React application. Making the `instance` available for use inside your React component makes it easy for your React application and web chat to work in harmony, including allowing you to render React content inside web chat via [React portals](https://reactjs.org/docs/portals.html). Once you have an `instance` you can pass it into child components as a property or via context. You should not call `createWebChatInstance` again to access the `instance`, as it will create a *new* instance if you do so.
46
-
47
-
## Usage
48
-
49
-
### With a functional component
50
-
51
-
With a functional component, you can use the `useEffect` React hook to call the `createWebChatInstance` method provided as a prop.
// A web chat configuration options object as documented at https://web-chat.global.assistant.watson.cloud.ibm.com/docs.html?to=api-configuration#configurationobject
65
-
constwebChatOptions= {
66
-
integrationID:'XXXX',
67
-
region:'XXXX',
68
-
serviceInstanceID:'XXXX',
69
-
onLoad: onWebChatLoad
70
-
};
71
-
72
-
createWebChatInstance(webChatOptions);
73
-
}, []);
74
-
75
-
return<div>I am here in {location}!</div>;
76
-
};
77
-
78
-
// Wrap the component with the method returned by `withWebChat`.
79
-
exportdefaultwithWebChat()(MyLocation);
80
-
```
81
-
82
-
You can now use the `MyLocation` component like you would any other. You can pass through any props you want, and `withWebChat` adds `createWebChatInstance` to the props.
83
-
84
-
```javascript
85
-
importReactfrom'react';
86
-
importMyLocationfrom'./MyLocation';
87
-
88
-
// Notice we only pass in the "location" prop to the MyLocation component... "createWebChatInstance" is automatically added!
89
-
constApp= () => {
90
-
return (
91
-
<div>
92
-
<div>Where are you located?</div>
93
-
<MyLocation location="Boston"/>
94
-
</div>
95
-
);
96
-
}
97
-
```
98
-
99
-
### With a class component
38
+
## Using WebChatContainer
100
39
101
-
With a class-based component, you can use`componentDidMount`to call the `createWebChatInstance` method provided as a prop.
40
+
The `WebChatContainer` function component is intended to make it as easy as possible to include web chat in your React application. To use, you simply need to render this component anywhere in your application and provide the [web chat configuration options object](https://web-chat.global.assistant.watson.cloud.ibm.com/docs.html?to=api-configuration#configurationobject) as a prop.
102
41
103
42
```javascript
104
-
importReact, { Component } from'react';
105
-
106
-
classMyLocationextendsComponent {
107
-
108
-
// A web chat configuration options object as documented at https://web-chat.global.assistant.watson.cloud.ibm.com/docs.html?to=api-configuration#configurationobject
109
-
webChatOptions = {
43
+
functionApp() {
44
+
constwebChatOptions= {
110
45
integrationID:'XXXX',
111
46
region:'XXXX',
112
47
serviceInstanceID:'XXXX',
113
-
onLoad:this.onWebChatLoad
48
+
// subscriptionID: 'only on enterprise plans',
49
+
// Note that there is no onLoad property here. The WebChatContainer component will override it with its own.
You can now use the `MyLocation`component like you would any other. You can pass through any props you want, and `withWebChat` will add `createWebChatInstance` to the props.
55
+
This component is also capable of managing custom responses. To do so, you need to pass a `renderCustomResponse` function as a prop. This function should return a React component that will render the content for the specific message for that response. You should make sure that the `WebChatContainer` component does not get unmounted in the middle of the life of your application because it will lose all custom responses that were previously received by web chat.
135
56
136
57
```javascript
137
-
importReact, { Component } from'react';
138
-
importMyLocationfrom'./MyLocation';
139
-
140
-
// Notice we only pass in the "location" prop to the MyLocation component... "createWebChatInstance" is automatically added!
141
-
classAppextendsComponent {
142
-
render() {
143
-
return (
144
-
<div>
145
-
<div>Where are you located?</div>
146
-
<MyLocation location="Boston"/>
147
-
</div>
148
-
);
149
-
}
58
+
functionApp() {
59
+
constwebChatOptions= {
60
+
integrationID:'XXXX',
61
+
region:'XXXX',
62
+
serviceInstanceID:'XXXX',
63
+
// subscriptionID: 'only on enterprise plans',
64
+
// Note that there is no onLoad property here. The WebChatContainer component will override it with its own.
// A web chat configuration options object as documented at https://web-chat.global.assistant.watson.cloud.ibm.com/docs.html?to=api-configuration#configurationobject
192
-
const webChatOptions:WebChatConfig= {
193
-
integrationID:'XXXX',
194
-
region:'XXXX',
195
-
serviceInstanceID:'XXXX',
196
-
onLoad: onWebChatLoad
197
-
};
198
-
199
-
createWebChatInstance(webChatOptions);
200
-
}, []);
201
-
202
-
return<div>I am here in {location}!</div>;
203
-
};
204
-
205
-
// Wrap the component with the method returned by `withWebChat`.
It is recommended that you mock `createWebChatInstance` in your unit tests and not test the higher-order component. If you must include the higher-order component in your unit test, you might have to add some extra configuration to your unit test framework to account for the fact that web chat appends additional scripts to your web site.
213
-
214
-
For example, when using the [Jest testing framework](https://jestjs.io), you must add the following configuration to your `jest.config.js` file.
215
-
216
-
```javascript
217
-
module.exports= {
218
-
testEnvironmentOptions: {
219
-
resources:'usable',
220
-
runScripts:'dangerously',
221
-
},
222
-
};
223
72
```
224
73
225
74
## API
226
75
227
-
### withWebChat
76
+
### WebChatContainer API
228
77
229
-
The `withWebChat` method is a higher-order function that returns a higher-order component. It takes an optional configuration argument and returns a function that takes a component as an argument. This component will have `createWebChatInstance` injected as a prop.
78
+
The `WebChatContainer` function is a functional component that makes use of `withWebChat` to load web chat when the component is mounted. It can also manage React portals for custom responses.
230
79
231
-
```javascript
232
-
// enchance is the higher order component.
233
-
constenhance=withWebChat(options);
80
+
#### Props
234
81
235
-
// enhance takes the component as an argument and adds createWebChatInstance as a prop.
236
-
exportdefaultenhance(Component)
237
-
```
238
-
239
-
or in short form:
240
-
241
-
```javascript
242
-
exportdefaultwithWebChat(options)(Component)
243
-
```
82
+
`WebChatContainer` has the following props.
244
83
245
-
This syntax enables you to chain multiple higher-order components together. [See the higher-order components documentation](https://reactjs.org/docs/higher-order-components.html) from the React team for more information about how higher-order components work and how they can be composed together.
84
+
| Attribute | Required | Type | Description |
85
+
|-----------|----------|---------|-------------|
86
+
| config | Yes | object | The [web chat configuration options object](https://web-chat.global.assistant.watson.cloud.ibm.com/docs.html?to=api-configuration#configurationobject). Note that any `onLoad` property will be ignored. |
87
+
|
88
+
| instanceRef | No | MutableRefObject | A convenience prop that is a reference to the web chat instance. This component will set the value of this ref using the `current` property when the instance has been created. |
89
+
|
90
+
| onBeforeRender | No | function | This is a callback function that is called after web chat has been loaded and before the `render` function is called. This function is passed a single argument which is the instance of web chat that was loaded. This function can be used to obtain a reference to the web chat instance if you want to make use of the instance functions that are available. |
91
+
|
92
+
| renderCustomResponse | No | function | This function is a callback function that will be called by this container to render custom responses. If this prop is provided, then the container will listen for custom response events from web chat and will generate a React portal for each event. This function will be called once during component render for each custom response event. This function takes two arguments. The first is the [custom response event](https://web-chat.global.assistant.watson.cloud.ibm.com/docs.html?to=api-events#customresponse) that triggered the custom response. The second is a convenience argument that is the instance of web chat. The function should return a `ReactNode` that renders the custom content for the response. |
93
+
|
246
94
247
-
#### withWebChat options object
248
-
249
-
The `withWebChat` method takes an optional object as an argument. Most uses will never use these.
| debug | No | false | boolean | If set to true, adds logging for setup and tear down process of web chat. Helpful for seeing if your application is aggressively mounting and remounting web chat. |
254
-
| baseUrl | No | https://web-chat.global.assistant.watson.appdomain.cloud | string | Where externally loaded script for web chat are hosted. Used for internal development purposes. |
255
-
256
-
### createWebChatInstance
257
-
258
-
The `createWebChatInstance` method takes a [web chat configuration options object](https://web-chat.global.assistant.watson.cloud.ibm.com/docs.html?to=api-configuration#configurationobject) as an argument and returns a promise. This promise either will successfully resolve with the instance of the web chat, or will throw a descriptive error.
0 commit comments