Skip to content

Commit 4411a30

Browse files
myandrienkomyandrienko
authored
docs: reorganize channel list articles (#2351)
1. Merged "ChannelPreview" and "Preview (ChannelPreview)" into a single, less confusing article. 2. Removed repeating "channel this" and "channel that" prefix from Channel List subarticles. 3. Moved the section describing `searchForChannels` prop from Cookbook to UI Components. 4. Moved AppMenu to its own Cookbook page. 5. Reduced nesting in Cookbook sidebar.
1 parent e059af8 commit 4411a30

File tree

7 files changed

+161
-154
lines changed

7 files changed

+161
-154
lines changed

‎docusaurus/docs/React/components/utility-components/channel-preview-ui.mdx

+6-2
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,18 @@
11
---
22
id: channel_preview_ui
3-
title: Preview (ChannelPreview)
3+
title: Channel Preview
44
---
55

66
import GHComponentLink from '../../_docusaurus-components/GHComponentLink';
77

8-
The [`ChannelList`](../core-components/channel-list.mdx) property `Preview` is a UI placeholder (think of it as a UI of a `ChannelList` item) which receives props through the `ChannelList` and the [`ChannelPreview`](./channel-preview.mdx) wrapper which extends these props with additional UI-specific items and renders it. Apart from the UI the `Preview` component is also responsible for channel selection (click handler).
8+
The [`ChannelList`](../core-components/channel-list.mdx) prop `Preview` allows you to override the preview component which is rendered for each channel in the list (think of it as the UI of a `ChannelList` item). The component passed as the `Preview` will receive props from the `ChannelList` and the `ChannelPreview` wrapper (which extends these props with additional UI-specific items and renders it). Apart from the UI the `Preview` component is also responsible for channel selection (click handler).
99

1010
The `Preview` property defaults to [`ChannelPreviewMessenger`](https://github.com/GetStream/stream-chat-react/blob/master/src/components/ChannelPreview/ChannelPreviewMessenger.tsx) component if no custom component is provided.
1111

12+
:::note
13+
For even deeper customization of the channel list and channel previews, use the [`renderChannels`](../core-components/channel-list.mdx#renderchannels) prop of the `ChannelList` component. Note, however, that using a custom channel list renderer requires more work than overriding the preview UI.
14+
:::
15+
1216
## Basic Usage
1317

1418
To customize the `ChannelList` item UI simply pass your custom `Preview` component to the `ChannelList`. See [The Preview Prop Component](../../guides/customization/channel-list-preview.mdx#the-preview-prop-component) for the extended guide.

‎docusaurus/docs/React/components/utility-components/channel-search.mdx

+45-1
Original file line numberDiff line numberDiff line change
@@ -199,6 +199,48 @@ The search results can be rendered in place of the channel list or above the cha
199199

200200
The `ChannelSearch` offers possibility to keep the search results open meanwhile the user clicks between the search results. This behavior is controlled by [`clearSearchOnClickOutside`](./#clearsearchonclickoutside) flag. The selected channel is added to the channel list if it was not present there before the search.
201201

202+
## Customizing the search method
203+
204+
By default, the `ChannelSearch` component searches just for users. Use the `searchForChannels` prop to also search for channels.
205+
206+
To override the search method completely, use the `searchFunction` prop. This prop is useful, say, when you want to search only for channels
207+
that the current logged in user is a member of. See the example below for this.
208+
209+
```jsx
210+
const customSearchFunction = async (
211+
props: ChannelSearchFunctionParams,
212+
event: { target: { value: SetStateAction<string> } },
213+
client: StreamChat,
214+
) => {
215+
const { setResults, setSearching, setQuery } = props;
216+
const value = event.target.value;
217+
218+
const filters = {
219+
name: { $autocomplete: value },
220+
members: { $in: client.userID },
221+
};
222+
223+
setSearching(true);
224+
setQuery(value);
225+
const channels = await client.queryChannels(filters);
226+
setResults(channels);
227+
setSearching(false);
228+
};
229+
```
230+
231+
```jsx
232+
const { client } = useChatContext();
233+
234+
<ChannelList
235+
additionalChannelSearchProps={{
236+
searchFunction: (params, event) => {
237+
return customSearchFunction(params, event, client);
238+
},
239+
}}
240+
showChannelSearch
241+
/>;
242+
```
243+
202244
## Props
203245

204246
### AppMenu
@@ -337,12 +379,14 @@ Custom search function to override default. The first argument should expect an
337379
| --------------------------------------------------------------------------------------------------- |
338380
| (`params: ChannelSearchFunctionParams, event: React.BaseSyntheticEvent` ) => Promise<void\> \| void |
339381

382+
See also [Customizing the search method](#customizing-the-search-method).
383+
340384
### searchDebounceIntervalMs
341385

342386
The number of milliseconds to debounce the search query.
343387

344388
| Type | Default |
345-
|----------|---------|
389+
| -------- | ------- |
346390
| `number` | 300 |
347391

348392
### SearchInput

‎docusaurus/docs/React/guides/channel-list-infinite-scroll.mdx

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
id: channel-list-infinite-scroll
3-
title: Channel List Infinite Scroll
3+
title: Infinite Scroll
44
keywords: [channel list, infinite scroll]
55
---
66

‎docusaurus/docs/React/guides/customization/app-menu.mdx

+98
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,98 @@
1+
---
2+
id: app_menu
3+
title: App Menu
4+
---
5+
6+
# Adding an App Menu
7+
8+
As of the version 10.0.0, users can add app menu into the `SearchBar`. In case you would like to display menu button next to the search input, you can do that by adding [`AppMenu` component](../../components/utility-components/channel-search.mdx/#appmenu) to the `ChannelSearch` props. The display of `AppMenu` is then toggled by clicking on the menu button. `AppMenu` can be rendered as a drop-down or even a modal. In our example we will render a drop-down menu.
9+
10+
:::caution
11+
The SDK does not provide any default `AppMenu` component and so you will have to write your CSS for it to be styled correctly.
12+
:::
13+
14+
```tsx
15+
import React, { useCallback } from 'react';
16+
import type { AppMenuProps } from 'stream-chat-react';
17+
18+
import './AppMenu.scss';
19+
20+
export const AppMenu = ({ close }: AppMenuProps) => {
21+
const handleSelect = useCallback(() => {
22+
// custom logic...
23+
close?.();
24+
}, [close]);
25+
26+
return (
27+
<div className='app-menu__container'>
28+
<ul className='app-menu__item-list'>
29+
<li className='app-menu__item' onClick={handleSelect}>
30+
Profile
31+
</li>
32+
<li className='app-menu__item' onClick={handleSelect}>
33+
New Group
34+
</li>
35+
<li className='app-menu__item' onClick={handleSelect}>
36+
Sign Out
37+
</li>
38+
</ul>
39+
</div>
40+
);
41+
};
42+
```
43+
44+
```scss
45+
.str-chat__channel-search-bar-button.str-chat__channel-search-bar-button--menu {
46+
position: relative;
47+
}
48+
49+
.app-menu {
50+
&__container {
51+
position: absolute;
52+
top: 50px;
53+
left: 10px;
54+
background-color: white;
55+
border-radius: 5px;
56+
box-shadow: 0 0 8px var(--str-chat__box-shadow-color);
57+
}
58+
59+
&__item-list {
60+
list-style: none;
61+
margin: 0;
62+
padding: 0;
63+
}
64+
65+
&__item {
66+
list-style: none;
67+
margin: 0;
68+
padding: 0.5rem 1rem;
69+
70+
&:hover {
71+
background-color: lightgrey;
72+
cursor: pointer;
73+
}
74+
}
75+
}
76+
```
77+
78+
```jsx
79+
import { AppMenu } from './components/AppMenu';
80+
81+
const App = () => (
82+
<Chat client={chatClient}>
83+
<ChannelList
84+
// highlight-next-line
85+
additionalChannelSearchProps={{ AppMenu }}
86+
showChannelSearch
87+
/>
88+
<Channel>
89+
<Window>
90+
<ChannelHeader />
91+
<MessageList />
92+
<MessageInput />
93+
</Window>
94+
<Thread />
95+
</Channel>
96+
</Chat>
97+
);
98+
```

‎docusaurus/docs/React/guides/customization/channel-search.mdx

-136
Original file line numberDiff line numberDiff line change
@@ -307,139 +307,3 @@ const additionalProps = {
307307
### Result:
308308
309309
<img src={CustomChannelSearch} alt='Custom Channel Search UI Component for Chat' width='700' />
310-
311-
### The searchFunction Prop:
312-
313-
By default, the `ChannelSearch` component searches just for users. Use the `searchForChannels` prop to also search for channels.
314-
315-
To override the search method, completely use the `searchFunction` prop. This prop is useful, say, when you want to search just for channels
316-
and for only channels that the current logged in user is a member of. See the example below for this.
317-
318-
```jsx
319-
const customSearchFunction = async (
320-
props: ChannelSearchFunctionParams,
321-
event: { target: { value: SetStateAction<string> } },
322-
client: StreamChat,
323-
) => {
324-
const { setResults, setSearching, setQuery } = props;
325-
const value = event.target.value;
326-
327-
const filters = {
328-
name: { $autocomplete: value },
329-
members: { $in: client.userID },
330-
};
331-
332-
setSearching(true);
333-
setQuery(value);
334-
const channels = await client.queryChannels(filters);
335-
setResults(channels);
336-
setSearching(false);
337-
};
338-
```
339-
340-
```jsx
341-
const { client } = useChatContext();
342-
343-
<ChannelList
344-
additionalChannelSearchProps={{
345-
searchFunction: (params, event) => {
346-
return customSearchFunction(params, event, client);
347-
},
348-
}}
349-
showChannelSearch
350-
/>;
351-
```
352-
353-
### Adding menu
354-
355-
As of the version 10.0.0, users can add app menu into the `SearchBar`. In case you would like to display menu button next to the search input, you can do that by adding [`AppMenu` component](../../components/utility-components/channel-search.mdx/#appmenu) to the `ChannelSearch` props. The display of `AppMenu` is then toggled by clicking on the menu button. `AppMenu` can be rendered as a drop-down or even a modal. In our example we will render a drop-down menu.
356-
357-
:::caution
358-
The SDK does not provide any default `AppMenu` component and so you will have to write your CSS for it to be styled correctly.
359-
:::
360-
361-
```tsx
362-
import React, { useCallback } from 'react';
363-
import type { AppMenuProps } from 'stream-chat-react';
364-
365-
import './AppMenu.scss';
366-
367-
export const AppMenu = ({ close }: AppMenuProps) => {
368-
const handleSelect = useCallback(() => {
369-
// custom logic...
370-
close?.();
371-
}, [close]);
372-
373-
return (
374-
<div className='app-menu__container'>
375-
<ul className='app-menu__item-list'>
376-
<li className='app-menu__item' onClick={handleSelect}>
377-
Profile
378-
</li>
379-
<li className='app-menu__item' onClick={handleSelect}>
380-
New Group
381-
</li>
382-
<li className='app-menu__item' onClick={handleSelect}>
383-
Sign Out
384-
</li>
385-
</ul>
386-
</div>
387-
);
388-
};
389-
```
390-
391-
```scss
392-
.str-chat__channel-search-bar-button.str-chat__channel-search-bar-button--menu {
393-
position: relative;
394-
}
395-
396-
.app-menu {
397-
&__container {
398-
position: absolute;
399-
top: 50px;
400-
left: 10px;
401-
background-color: white;
402-
border-radius: 5px;
403-
box-shadow: 0 0 8px var(--str-chat__box-shadow-color);
404-
}
405-
406-
&__item-list {
407-
list-style: none;
408-
margin: 0;
409-
padding: 0;
410-
}
411-
412-
&__item {
413-
list-style: none;
414-
margin: 0;
415-
padding: 0.5rem 1rem;
416-
417-
&:hover {
418-
background-color: lightgrey;
419-
cursor: pointer;
420-
}
421-
}
422-
}
423-
```
424-
425-
```jsx
426-
import { AppMenu } from './components/AppMenu';
427-
428-
const App = () => (
429-
<Chat client={chatClient}>
430-
<ChannelList
431-
// highlight-next-line
432-
additionalChannelSearchProps={{ AppMenu }}
433-
showChannelSearch
434-
/>
435-
<Channel>
436-
<Window>
437-
<ChannelHeader />
438-
<MessageList />
439-
<MessageInput />
440-
</Window>
441-
<Thread />
442-
</Channel>
443-
</Chat>
444-
);
445-
```

‎docusaurus/docs/React/guides/multiple-channel-lists.mdx

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
id: multiple_channel_lists
3-
title: Multiple Channel Lists
3+
title: Multiple Lists
44
---
55

66
This example will focus on the specific use case where there are two `ChannelList` components in the same application.

‎docusaurus/sidebars-react.json

+10-13
Original file line numberDiff line numberDiff line change
@@ -28,9 +28,10 @@
2828
"components/core-components/channel_list",
2929
"components/contexts/channel_list_context",
3030
"hooks/channel_list_hooks",
31-
"components/utility-components/channel_preview",
3231
"components/utility-components/channel_preview_ui",
33-
"components/utility-components/channel_search"
32+
"components/utility-components/channel_search",
33+
"guides/channel-list-infinite-scroll",
34+
"guides/multiple_channel_lists"
3435
]
3536
},
3637
{
@@ -54,8 +55,8 @@
5455
"components/utility-components/base-image",
5556
{
5657
"Attachment": [
57-
"components/message-components/attachment",
58-
"components/message-components/attachment/voice-recording"
58+
"components/message-components/attachment",
59+
"components/message-components/attachment/voice-recording"
5960
]
6061
},
6162
"components/message-components/reactions",
@@ -82,11 +83,9 @@
8283
"guides/customization/customization-overview",
8384
{
8485
"Channel List": [
85-
"guides/channel-list-infinite-scroll",
8686
"guides/customization/channel_list_preview",
8787
"guides/customization/channel_search",
88-
"guides/channel-user-lists",
89-
"guides/multiple_channel_lists"
88+
"guides/channel-user-lists"
9089
]
9190
},
9291
{
@@ -123,12 +122,10 @@
123122
"guides/customization/giphy_preview"
124123
]
125124
},
126-
{
127-
"Emojis": ["guides/customization/emoji_picker"]
128-
},
129-
{
130-
"Misc": ["guides/customization/channel_header", "guides/customization/thread_header"]
131-
}
125+
"guides/customization/emoji_picker",
126+
"guides/customization/app_menu",
127+
"guides/customization/channel_header",
128+
"guides/customization/thread_header"
132129
]
133130
},
134131
{

0 commit comments

Comments
 (0)