Skip to content

Commit 7acee5f

Browse files
rvsiarvsia
committed
Update PF4 dual list documentation
1 parent 99a6e3d commit 7acee5f

File tree

2 files changed

+136
-60
lines changed

2 files changed

+136
-60
lines changed

‎packages/pf4-component-mapper/src/files/dual-list-context.js

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
import { createContext } from 'react';
22

3-
const DualListSelectContext = createContext({});
3+
const DualListContext = createContext({});
44

5-
export default DualListSelectContext;
5+
export default DualListContext;

‎packages/react-renderer-demo/src/doc-components/examples-texts/pf4/dual-list-select.md

Lines changed: 134 additions & 58 deletions
Original file line numberDiff line numberDiff line change
@@ -1,61 +1,137 @@
1-
This a custom component with a custom design. Things can be changed, after official PF4 release.
2-
31
## Props
42

5-
Dual list select is wrapped in a form group, so it accepts all [form group props](/mappers/component-api#formgroupwrappedcomponents).
6-
7-
|Props|Type|Default|Description|
8-
|-----|----|-------|-----------|
9-
|options|array|[]|`[{label, value}]`|
10-
|label|node||FormLabel primary text|
11-
|leftTitle|String|'Options'|Title for options|
12-
|rightTitle|String|'Selected'|Title for selected items|
13-
|moveLeftTitle|String|'Move selected to left'|Tooltip for move to left button|
14-
|moveRightTitle|String|'Move selected to right'|Tooltip for move to right button|
15-
|moveAllLeftTitle|String|'Move all to left'|Tooltip for move all to left button|
16-
|moveAllRightTitle|String|'Move all to right'|Tooltip for move all to right button|
17-
|allToLeft|Boolean|true|Hides all to left button|
18-
|allToRight|Boolean|true|Hides all to right button|
19-
|noValueTitle|String|'No selected'|Placeholder for empty value|
20-
|noOptionsTitle|String|'No available options'|Placeholder for empty options|
21-
|filterOptionsTitle|String|'Filter options'|Placeholder for options filter input|
22-
|filterValueTitle|String|'Filter selected value'|Placeholder for value filter input|
23-
|filterValueText|String|'Remove your filter to see all selected'|Placeholder for value when there is no filtered value|
24-
|filterOptionsText|String|'Remove your filter to see all options'|Placeholder for options when there is no filtered option|
25-
|renderStatus|function|'null'|A function that renders status text below the toolbar filter. For example, display how many items were selected: `({selected, options}) => "selected " + selected + " out of " + options`|
26-
27-
### Customization
28-
29-
MUI DualListSelect provides fully customization. When the props offers Right/Left variant, you can pass props to `RightXXX` or to `LeftXXX` props. Example: `ListGridProps` is Right/Left, so there are two more props: `RightListGridProps` and `LeftListGridProps`. These props overrides the standard props, except `className`, that are being combined. All these props are objects.
30-
31-
|Props|Right/Left variant|
3+
Dual list select is wrapped in a form group, so it accepts all [form group props](/mappers/component-api#formgroupwrappedcomponents). It also accepts the same props as the [original component](https://www.patternfly.org/v4/components/dual-list-selector).
4+
5+
The component implements three following custom props:
6+
7+
|Props|Type|Description|
8+
|-----|----|-----------|
9+
|[options](/mappers/dual-list-select?mapper=pf4#options)|array|Array of options.|
10+
|[getValueFromNode](/mappers/dual-list-select?mapper=pf4#getvaluefromnode)|func|Use when a node is used to set value/label.|
11+
|[isSortable](/mappers/dual-list-select?mapper=pf4#issortable)|boolean|Allows to sort the list.|
12+
13+
<br />
14+
15+
---
16+
17+
<br />
18+
19+
### options
20+
21+
*Array<string | node | dualListSelectOption>*
22+
23+
You have multiple ways how to set up your options:
24+
25+
<br />
26+
27+
**A. Simple array**
28+
29+
You can just provide an array of values:
30+
31+
```jsx
32+
const options = ['value1', 'value2', ... ]
33+
```
34+
35+
Or you can use node for additional customization (i.e. i11n):
36+
37+
```jsx
38+
const options = [<span>value1</span>, <span>value2</span>, ... ]
39+
```
40+
41+
In this case, you have to provide **getValueFromNode** to get a value from the nodes.
42+
43+
<br />
44+
45+
**B. Compley array** (of `dualListSelectOption`s)
46+
47+
You can also use the custom options format of
48+
49+
```jsx
50+
{
51+
label: string | node;
52+
value: string;
53+
}
54+
```
55+
56+
```jsx
57+
const options = [{value: 'first-value', label: 'First value'}, {value: 'second-value', label: <span>Second value</span>}, ... ]
58+
```
59+
60+
<br />
61+
62+
---
63+
64+
<br />
65+
66+
### getValueFromNode
67+
68+
*(node) => string*
69+
70+
A simple function that receives a react node as an argument and returns its value. **Always provide this function, when you are using nodes in options!**
71+
72+
|Node|getValueFromNode|
3273
|-----|----|
33-
|FormGroupProps||
34-
|ListProps|yes|
35-
|ListItemProps|yes|
36-
|ToolbarProps|yes|
37-
|FilterFieldProps|yes|
38-
|SearchIconProps|yes|
39-
|SearchIconButtonProps|yes|
40-
|SortIconButtonProps|yes|
41-
|SortIconProps|yes|
42-
|InternalGridProps|yes|
43-
|ListGridProps|yes|
44-
|TitleProps|yes|
45-
|ButtonsGridProps||
46-
|ButtonsInternalFlexProps||
47-
|ButtonFlexProps||
48-
|ToRightFlexProps||
49-
|IconButtonProps||
50-
|ToRightIconButtonProps||
51-
|IconProps||
52-
|AllToRightFlexProps||
53-
|AllToRightIconButtonProps||
54-
|AllToLeftFlexProps||
55-
|AllToLeftIconButtonProps||
56-
|ToLeftFlexProps||
57-
|ToLeftIconButtonProps||
58-
|ToRightIconProps||
59-
|AllToRightIconProps||
60-
|AllToLeftIconProps||
61-
|ToLeftIconProps||
74+
|`<span>value1</span>`|`(option) => option.props.children`|
75+
76+
<br />
77+
78+
---
79+
80+
<br />
81+
82+
### isSortable
83+
84+
*boolean*
85+
86+
This flag allows to sort options in both of options and selected options. However, you have to insert a sort button manually into [chosenOptionsActions](https://www.patternfly.org/v4/components/dual-list-selector#props) or [availableOptionsActions](https://www.patternfly.org/v4/components/dual-list-selector#props) arrays.
87+
#### SortButton
88+
89+
You can use the provided button or implement your own button.
90+
91+
**A. Provided button**
92+
93+
This component requires a prop `position`: `left` (availableOption) | `right` (chosenOptions)
94+
95+
```jsx
96+
import { DualListSortButton } from '@data-driven-forms/pf4-component-mapper';
97+
98+
const dualListField = {
99+
component: componentTypes.DUAL_LIST_SELECT,
100+
name: 'sortable-dual-list',
101+
options: ['z', 'a', 'b'],
102+
isSortable: true,
103+
availableOptionsActions: [<DualListSortButton position="left" key="sort" />],
104+
chosenOptionsActions: [<DualListSortButton position="right" key="sort" />]
105+
}
106+
```
107+
108+
**A. Custom implementation**
109+
110+
Data Driven Forms provides an access to sort functionality via `DualListContext`.
111+
112+
```jsx
113+
{
114+
sortConfig: { left: 'asc' | 'desc', right: 'asc' | 'desc' },
115+
setSortConfig: (newSortConfig) => void
116+
}
117+
```
118+
119+
```jsx
120+
import { DualListContext } from '@data-driven-forms/pf4-component-mapper';
121+
122+
const CustomRightSortButton = () => {
123+
const { sortConfig, setSortConfig } = useContext(DualListContext);
124+
125+
return (
126+
<button
127+
onClick={
128+
sortConfig.right === 'asc'
129+
? () => setSortConfig({ ...sortConfig, right: 'desc' })
130+
: () => setSortConfig({ ...sortConfig, right: 'asc' })
131+
}
132+
>
133+
Sort right values
134+
</button>
135+
);
136+
};
137+
```

0 commit comments

Comments
 (0)