Skip to content

Commit

Permalink
Do not use non-recommended styleSet in samples (#5023)
Browse files Browse the repository at this point in the history
Co-authored-by: William Wong <[email protected]>
  • Loading branch information
OEvgeny and compulim authored Apr 19, 2024
1 parent bc1c6b4 commit 025b213
Show file tree
Hide file tree
Showing 3 changed files with 27 additions and 38 deletions.
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

## Description

This sample introduces `styleSetOptions` and branding your bot through Web Chat via styling.
This sample introduces `styleOptions` and branding your bot through Web Chat via styling.

# Test out the hosted sample

Expand All @@ -23,23 +23,23 @@ This sample introduces `styleSetOptions` and branding your bot through Web Chat

> Jump to [completed code](#completed-code) to see the end-result `index.html`.
## Why `styleSetOptions`?
## Why `styleOptions`?

You may have noticed that Web Chat provides two different ways to change the appearance of your bot:

1. 'Branding' your bot via `styleSetOptions` (recommended)
1. 'Branding' your bot via `styleOptions` (recommended)
1. Idiosyncratic styling via overriding `createStyleSet` (not recommended)

`styleSetOptions` is the Web Chat supported method of changing existing DOM elements in the application, and the currently available options are listed on the [`defaultStyleOptions.ts` file](https://github.com/microsoft/BotFramework-WebChat/blob/master/packages/api/src/defaultStyleOptions.ts) and [`adaptiveCards/defaultStyleOptions.ts` file](https://github.com/microsoft/BotFramework-WebChat/blob/master/packages/bundle/src/adaptiveCards/defaultStyleOptions.ts) when Adaptive Cards is enabled. These options will continue to be updated as we make further as the project grows.
`styleOptions` is the Web Chat supported method of changing existing DOM elements in the application, and the currently available options are listed on the [`defaultStyleOptions.ts` file](https://github.com/microsoft/BotFramework-WebChat/blob/master/packages/api/src/defaultStyleOptions.ts) and [`adaptiveCards/defaultStyleOptions.ts` file](https://github.com/microsoft/BotFramework-WebChat/blob/master/packages/bundle/src/adaptiveCards/defaultStyleOptions.ts) when Adaptive Cards is enabled. These options will continue to be updated as we make further as the project grows.

We provide these options to override for several reasons:

- These are commonly re-styled DOM elements that bot creators want modify in order to provide a specific brand experience
- Although we support the modification of styling, we want it to be obvious to the user that **we do not guarantee our DOM will always stay the same**, which is why Web Chat uses CSS-in-JS (`emotion`), which generates the class names for Web Chat
- We encourage our users to use CSS selectors, such as `& > button > div > ul > li:nth-child`, as opposed to accessing the element by it's class name (e.g. `& > .css-1a2b3c4`) because of the high likelihood that the project will have future class and DOM changes. CSS selectors provide high specificity without the need of using `!important`, and provides implicit information of what element is being styled
- `styleSetOptions` is our way of preserving your modifications (without breaking changes!) but allowing the repo to continue to facilitate natural DOM changes that come with an actively updated project
- `styleOptions` is our way of preserving your modifications (without breaking changes!) but allowing the repo to continue to facilitate natural DOM changes that come with an actively updated project

### My required changes are not all specified in `defaultStyleOptions.js`, what do I do now?
### My required changes are not all specified in `defaultStyleOptions.ts`, what do I do now?

- Please feel free to [file a PR](https://github.com/microsoft/BotFramework-WebChat/issues/new) requesting the feature you want to be able to brand! We welcome your input and are constantly updating `defaultStyleOptions` with commonly modified aspects of Web Chat.
- As a last resort, idiosyncratic styling is available, but not supported by our team. You may use this method by following the [02.branding-styling-and-customization/b.idiosyncratic-manual-styles sample](../b.idiosyncratic-manual-styles/README.md). Please note that using this method creates a **high likelihood** of breaking changes when Web Chat releases new code.
Expand Down Expand Up @@ -134,7 +134,7 @@ Here is the finished `index.html`:

# Other modifications

Feel free to add your own `styleSetOptions` object to override as many of these styles as you like!
Feel free to add your own `styleOptions` object to override as many of these styles as you like!

# Further reading

Expand Down
32 changes: 12 additions & 20 deletions samples/06.recomposing-ui/a.minimizable-web-chat/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -76,12 +76,12 @@ Open the project in your preferred IDE.

First we will render Web Chat. To test, you can temporarily add `<WebChat>` to your `App.js`

In the `WebChat.js` file, import `React`, `{ useEffect, useMemo }` `ReactWebChat`, `createDirectLine`, and `createStyleSet` from our packages.
In the `WebChat.js` file, import `React`, `{ useEffect, useMemo }` `ReactWebChat`, and `createDirectLine`, from our packages.

<!-- prettier-ignore-start -->
```js
import React from 'react';
import ReactWebChat, { createDirectLine, createStyleSet } from 'botframework-webchat';
import ReactWebChat, { createDirectLine } from 'botframework-webchat';
```
<!-- prettier-ignore-end -->

Expand All @@ -92,15 +92,15 @@ Set up the functional component the same way you would set up a regular `React.C

<!-- prettier-ignore-start -->
```js
const WebChat = ({ className, onFetchToken, store, token }) => {
const WebChat = ({ className, onFetchToken, store, styleOptions, token }) => {
const directLine = useMemo(() => createDirectLine({ token }), [token]);

useEffect(() => {
onFetchToken();
}, [onFetchToken]);

return token ? (
<ReactWebChat className={`${className || ''} web-chat`} directLine={directLine} store={store} styleSet={styleSet} />
<ReactWebChat className={`${className || ''} web-chat`} directLine={directLine} store={store} styleOptions={styleOptions} />
) : (
<div className={`${className || ''} connect-spinner`}>
<div className="content">
Expand Down Expand Up @@ -130,12 +130,12 @@ In the `useEffect` hook, invoke `onFetchToken` from props if the `token` has not
Let's move on to building the `<MinimizableWebChat>` component.

Import `React`, `{ useCallback, useMemo, useState }` `createStore`, and `createStyleSet`. Then import your newly made component, `WebChat`.
Import `React`, `{ useCallback, useMemo, useState }` and `createStore`. Then import your newly made component, `WebChat`.

<!-- prettier-ignore-start -->
```js
import React from 'react', { useCallback, useMemo, useState };
import { createStore, createStyleSet } from 'botframework-webchat';
import { createStore } from 'botframework-webchat';

import WebChat from './WebChat';
```
Expand Down Expand Up @@ -212,14 +212,6 @@ import WebChat from './WebChat';
[]
);

const styleSet = useMemo(
() =>
createStyleSet({
backgroundColor: 'Transparent'
}),
[]
);

const [loaded, setLoaded] = useState(false);
const [minimized, setMinimized] = useState(true);
const [newMessage, setNewMessage] = useState(false);
Expand Down Expand Up @@ -298,7 +290,7 @@ Then implement these methods into the component:
className="react-web-chat"
+ onFetchToken={handleFetchToken}
+ store={store}
styleSet={styleSet}
styleOptions={styleOptions}
+ token={token}
/>
</div>
Expand Down Expand Up @@ -345,7 +337,7 @@ Completed `MinimizableWebChat.js`
```js
import classNames from 'classnames';
import React, { useCallback, useMemo, useState } from 'react';
import { createStore, createStyleSet } from 'botframework-webchat';
import { createStore } from 'botframework-webchat';

import WebChat from './WebChat';

Expand Down Expand Up @@ -377,10 +369,10 @@ const MinimizableWebChat = () => {
[]
);

const styleSet = useMemo(
const styleOptions = useMemo(
() =>
createStyleSet({
backgroundColor: 'Transparent'
({
backgroundColor: 'transparent'
}),
[]
);
Expand Down Expand Up @@ -440,7 +432,7 @@ const MinimizableWebChat = () => {
className="react-web-chat"
onFetchToken={handleFetchToken}
store={store}
styleSet={styleSet}
styleOptions={styleOptions}
token={token}
/>
</div>
Expand Down
19 changes: 8 additions & 11 deletions samples/06.recomposing-ui/a.minimizable-web-chat/src/WebChat.js
Original file line number Diff line number Diff line change
@@ -1,25 +1,22 @@
import React, { useEffect, useMemo } from 'react';
import ReactWebChat, { createDirectLine, createStyleSet } from 'botframework-webchat';
import ReactWebChat, { createDirectLine } from 'botframework-webchat';

import './WebChat.css';

const WebChat = ({ className, onFetchToken, store, token }) => {
const WebChat = ({ className, onFetchToken, store, styleOptions, token }) => {
const directLine = useMemo(() => createDirectLine({ token }), [token]);

const styleSet = useMemo(
() =>
createStyleSet({
backgroundColor: 'Transparent'
}),
[]
);

useEffect(() => {
onFetchToken();
}, [onFetchToken]);

return token ? (
<ReactWebChat className={`${className || ''} web-chat`} directLine={directLine} store={store} styleSet={styleSet} />
<ReactWebChat
className={`${className || ''} web-chat`}
directLine={directLine}
store={store}
styleOptions={styleOptions}
/>
) : (
<div className={`${className || ''} connect-spinner`}>
<div className="content">
Expand Down

0 comments on commit 025b213

Please sign in to comment.