Skip to content

Commit

Permalink
Added a new WebChatProvider component to simplify the use of withWebC… (
Browse files Browse the repository at this point in the history 
#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.
  • Loading branch information
@TazmanianDI
TazmanianDI committed Aug 5, 2022
1 parent 418d2c6 commit f4383c0
Show file tree
Hide file tree
Showing 22 changed files with 11,003 additions and 10,103 deletions.
7 changes: 6 additions & 1 deletion .eslintrc.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -38,8 +38,13 @@ module.exports = {
],
plugins: ['jsdoc', 'simple-import-sort'],
rules: {
'no-use-before-define': 'off',
'@typescript-eslint/explicit-module-boundary-types': 'off',
'@typescript-eslint/no-explicit-any': 'off',
camelcase: 'off',
'import/extensions': 'off',
'import/prefer-default-export': 'off',
'react/jsx-filename-extension': [1, { extensions: ['.tsx', '.jsx'] }],
'react/require-default-props': 'off',
'no-use-before-define': 'off',
},
};
6 changes: 5 additions & 1 deletion .gitignore
View file
Original file line number Diff line number Diff line change
Expand Up @@ -47,5 +47,9 @@ typings/
# Yarn Integrity file
.yarn-integrity

# generate output
# Generated output
dist

# IntelliJ/WebStorm Files
.idea
*.iml
247 changes: 40 additions & 207 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,22 +5,17 @@

`@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.

There are two utility functions provided by this library:

1. The `WebChatContainer` function is a functional component that makes use of `withWebChat` to load web chat when the component is mounted.
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).

<details>
<summary>Table of contents</summary>

- [Installation](#installation)
- [How this works](#how-this-works)
- [Usage](#usage)
- [With a functional component](#with-a-functional-component)
- [With a class component](#with-a-class-component)
- [Render user_defined responses](#render-user_defined-responses)
- [Render customElements](#render-custom-elements)
- [Using with Carbon](#using-with-carbon)
- [Using with TypeScript](#using-with-typescript)
- [Writing tests](#writing-tests)
- [Using WebChatContainer](#webchatcontainer)
- [API](#api)
- [withWebChat](#withwebchat)
- [createWebChatInstance](#createwebchatinstance)
- [Additional resources](#additional-resources)
- [License](#license)

Expand All @@ -40,231 +35,69 @@ Or using `yarn`:
yarn add @ibm-watson/assistant-web-chat-react
```

## How this works

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.

## Usage

### With a functional component

With a functional component, you can use the `useEffect` React hook to call the `createWebChatInstance` method provided as a prop.

```javascript
import React, { useEffect } from 'react';
import { withWebChat } from '@ibm-watson/assistant-web-chat-react';

const MyLocation = ({ location, createWebChatInstance }) => {

useEffect(() => {
function onWebChatLoad(instance) {
instance.render();
}

// A web chat configuration options object as documented at https://web-chat.global.assistant.watson.cloud.ibm.com/docs.html?to=api-configuration#configurationobject
const webChatOptions = {
integrationID: 'XXXX',
region: 'XXXX',
serviceInstanceID: 'XXXX',
onLoad: onWebChatLoad
};

createWebChatInstance(webChatOptions);
}, []);

return <div>I am here in {location}!</div>;
};

// Wrap the component with the method returned by `withWebChat`.
export default withWebChat()(MyLocation);
```

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.

```javascript
import React from 'react';
import MyLocation from './MyLocation';

// Notice we only pass in the "location" prop to the MyLocation component... "createWebChatInstance" is automatically added!
const App = () => {
return (
<div>
<div>Where are you located?</div>
<MyLocation location="Boston" />
</div>
);
}
```
### With a class component
## Using WebChatContainer

With a class-based component, you can use `componentDidMount` to call the `createWebChatInstance` method provided as a prop.
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.

```javascript
import React, { Component } from 'react';

class MyLocation extends Component {

// A web chat configuration options object as documented at https://web-chat.global.assistant.watson.cloud.ibm.com/docs.html?to=api-configuration#configurationobject
webChatOptions = {
function App() {
const webChatOptions = {
integrationID: 'XXXX',
region: 'XXXX',
serviceInstanceID: 'XXXX',
onLoad: this.onWebChatLoad
// subscriptionID: 'only on enterprise plans',
// Note that there is no onLoad property here. The WebChatContainer component will override it with its own.
};

componentDidMount() {
const { createWebChatInstance } = this.props;
createWebChatInstance(this.webChatOptions).then(instance => { this.onWebChatLoad(instance); });
}

onWebChatLoad = (instance) => {
instance.render();
};

render() {
const { location } = this.props;
return <div>I am here in {location}!</div>;
}
return <WebChatContainer config={webChatOptions} />;
}

export default withWebChat()(MyLocation);
```

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.
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.

```javascript
import React, { Component } from 'react';
import MyLocation from './MyLocation';

// Notice we only pass in the "location" prop to the MyLocation component... "createWebChatInstance" is automatically added!
class App extends Component {
render() {
return (
<div>
<div>Where are you located?</div>
<MyLocation location="Boston" />
</div>
);
}
function App() {
const webChatOptions = {
integrationID: 'XXXX',
region: 'XXXX',
serviceInstanceID: 'XXXX',
// subscriptionID: 'only on enterprise plans',
// Note that there is no onLoad property here. The WebChatContainer component will override it with its own.
};
return <WebChatContainer renderCustomResponse={renderCustomResponse} config={webChatOptions} />;
}
```
### Using with TypeScript
The `withWebChat` package is written in TypeScript and includes types.
In addition to `withWebChat`, this package exports the following types:
| Type | Description |
|-----------------------|--------------------------------------------------------------------------------------|
| AddedWithWebChatProps | The props that the withWebChat component adds to the component that is passed to it. |
| WebChatConfig | The configuration options object to create a new web chat instance. |
| WebChatInstance | The created instance of web chat. |
| WithWebChatConfig | The optional configuration object for withWebChat |

```typescript
import React, { useEffect } from 'react';
import {
withWebChat,
AddedWithWebChatProps,
WebChatConfig,
WebChatInstance,
WithWebChatConfig
} from '@ibm-watson/assistant-web-chat-react';

interface MyLocationProps extends AddedWithWebChatProps {
location: string;
function renderCustomResponse(event) {
return <div>My custom content</div>;
}

const withWebChatConfig: WithWebChatConfig = {
debug: true
};

const MyLocation = ({ location, createWebChatInstance }: MyLocationProps) => {
useEffect(() => {

function onWebChatLoad(instance: WebChatInstance) {
instance.render();
}

// A web chat configuration options object as documented at https://web-chat.global.assistant.watson.cloud.ibm.com/docs.html?to=api-configuration#configurationobject
const webChatOptions: WebChatConfig = {
integrationID: 'XXXX',
region: 'XXXX',
serviceInstanceID: 'XXXX',
onLoad: onWebChatLoad
};

createWebChatInstance(webChatOptions);
}, []);

return <div>I am here in {location}!</div>;
};

// Wrap the component with the method returned by `withWebChat`.
export default withWebChat(withWebChatConfig)(MyLocation);

```
### Writing tests
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.
For example, when using the [Jest testing framework](https://jestjs.io), you must add the following configuration to your `jest.config.js` file.
```javascript
module.exports = {
testEnvironmentOptions: {
resources: 'usable',
runScripts: 'dangerously',
},
};
```

## API

### withWebChat
### WebChatContainer API

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.
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.

```javascript
// enchance is the higher order component.
const enhance = withWebChat(options);
#### Props

// enhance takes the component as an argument and adds createWebChatInstance as a prop.
export default enhance(Component)
```
or in short form:
```javascript
export default withWebChat(options)(Component)
```
`WebChatContainer` has the following props.

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.
| Attribute | Required | Type | Description |
|-----------|----------|---------|-------------|
| 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. |
|
| 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. |
|
| 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. |
|
| 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. |
|

#### withWebChat options object
The `withWebChat` method takes an optional object as an argument. Most uses will never use these.
| Attribute | Required | Default | Type | Description |
|-----------|----------|----------------------------------------------------------|---------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| 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. |
| 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. |
### createWebChatInstance
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.
```javascript
createWebChatInstance(config).then(instance => {}).catch(error => {});
```
## Additional resources
- [Watson Assistant](https://www.ibm.com/cloud/watson-assistant)
- [Watson Assistant web chat feature documentation](https://cloud.ibm.com/docs/watson-assistant?topic=watson-assistant-deploy-web-chat)
- [Watson Assistant web chat API documentation](https://web-chat.global.assistant.watson.cloud.ibm.com/docs.html?to=api-overview)
- [Higher order components](https://reactjs.org/docs/higher-order-components.html)

## License

This package is available under the [MIT License](./LICENSE).
Loading

0 comments on commit f4383c0

Please sign in to comment.