Skip to content

Commit 98afaa4

Browse files
slax57slax57
committed
add TextArrayField doc
1 parent 5bcfbf8 commit 98afaa4

File tree

7 files changed

+165
-1
lines changed

7 files changed

+165
-1
lines changed

‎docs/ArrayField.md‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -260,7 +260,13 @@ Check [the `useListContext` documentation](./useListContext.md) for more informa
260260

261261
## Rendering An Array Of Strings
262262

263-
If you need to render a custom collection (e.g. an array of tags `['dolor', 'sit', 'amet']`), it's often simpler to write your own component:
263+
If you need to render a custom collection (e.g. an array of tags `['dolor', 'sit', 'amet']`), you can use the [`<TextArrayField>`](./TextArrayField.md) component.
264+
265+
```jsx
266+
<TextArrayField source="tags" />
267+
```
268+
269+
You can also create your own field component, using the `useRecordContext` hook:
264270

265271
```jsx
266272
import { useRecordContext } from 'react-admin';

‎docs/ChipField.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -41,3 +41,13 @@ The `<ChipField>` component accepts the usual `className` prop. You can also ove
4141
| `&.RaChipField-chip` | Applied to the underlying Material UI's `Chip` component |
4242

4343
To override the style of all instances of `<ChipField>` using the [application-wide style overrides](./AppTheme.md#theming-individual-components), use the `RaChipField` key.
44+
45+
## Rendering A Scalar Value
46+
47+
If you need to render a custom collection (e.g. an array of tags `['dolor', 'sit', 'amet']`), you may be tempted to use `<ChipField source="." />`, but that won't work.
48+
49+
What you probably need in that case instead is the [`<TextArrayField>`](./TextArrayField.md) component, which will render each item of a scalar array in its own Chip.
50+
51+
```jsx
52+
<TextArrayField source="tags" />
53+
```

‎docs/Reference.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -211,6 +211,7 @@ title: "Index"
211211
* [`<TabbedForm>`](./TabbedForm.md)
212212
* [`<TabbedFormWithRevision>`](./TabbedForm.md#versioning)<img class="icon" src="./img/premium.svg" alt="React Admin Enterprise Edition icon" />
213213
* [`<TabbedShowLayout>`](./TabbedShowLayout.md)
214+
* [`<TextArrayField>`](./TextArrayField.md)
214215
* [`<TextArrayInput>`](./TextArrayInput.md)
215216
* [`<TextField>`](./TextField.md)
216217
* [`<TextInput>`](./TextInput.md)

‎docs/SingleFieldList.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -143,3 +143,11 @@ The `<SingleFieldList>` component accepts the usual `className` prop. You can al
143143
| `& .RaSingleFieldList-link` | Applied to each link |
144144

145145
**Tip**: You can override these classes for all `<SingleFieldList>` instances by overriding them in a Material UI theme, using the key "RaSingleFieldList".
146+
147+
## Rendering An Array Of Strings
148+
149+
If you need to render a custom collection (e.g. an array of tags `['dolor', 'sit', 'amet']`), you may want to use the [`<TextArrayField>`](./TextArrayField.md) component instead.
150+
151+
```jsx
152+
<TextArrayField source="tags" />
153+
```

‎docs/TextArrayField.md‎

Lines changed: 138 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,138 @@
1+
---
2+
layout: default
3+
title: "The TextArrayField Component"
4+
storybook_path: ra-ui-materialui-fields-textarrayfield--basic
5+
---
6+
7+
# `<TextArrayField>`
8+
9+
`<TextArrayField>` renders an array of scalar values using Material-UI's Stack and Chips.
10+
11+
![TextArrayField](./img/text-array-field.png)
12+
13+
`<TextArrayField>` is ideal for displaying lists of simple text values, such as genres or tags, in a visually appealing way.
14+
15+
## Usage
16+
17+
`<TextArrayField>` can be used in a Show view to display an array of values from a record. For example:
18+
19+
```js
20+
const book = {
21+
id: 1,
22+
title: 'War and Peace',
23+
genres: [
24+
'Fiction',
25+
'Historical Fiction',
26+
'Classic Literature',
27+
'Russian Literature',
28+
],
29+
};
30+
```
31+
32+
You can render the `TextArrayField` like this:
33+
34+
```jsx
35+
import { Show, SimpleShowLayout, TextArrayField } from 'react-admin';
36+
37+
const BookShow = () => (
38+
<Show>
39+
<SimpleShowLayout>
40+
<TextField source="title" />
41+
<TextArrayField source="genres" />
42+
</SimpleShowLayout>
43+
</Show>
44+
);
45+
```
46+
47+
## Props
48+
49+
The following props are available for `<TextArrayField>`:
50+
51+
| Prop | Type | Required | Description |
52+
| ----------- | ------------ | -------- | ------------------------------------------------------------- |
53+
| `source` | `string` | Yes | The name of the record field containing the array to display. |
54+
| `color` | `string` | - | The color of the Chip components. |
55+
| `emptyText` | `ReactNode` | - | Text to display when the array is empty. |
56+
| `record` | `RecordType` | - | The record containing the data to display. |
57+
| `size` | `string` | - | The size of the Chip components. |
58+
| `variant` | `string` | - | The variant of the Chip components. |
59+
60+
Additional props are passed to the underlying [Material-UI `Stack` component](https://mui.com/material-ui/react-stack/).
61+
62+
## `color`
63+
64+
The color of the Chip components. Accepts any value supported by MUI's Chip (`primary`, `secondary`, etc).
65+
66+
```jsx
67+
<TextArrayField source="genres" color="secondary" />
68+
```
69+
70+
## `direction`
71+
72+
The direction of the Stack layout. Accepts `row` or `column`. The default is `row`.
73+
74+
```jsx
75+
<TextArrayField source="genres" direction="column" />
76+
```
77+
78+
## `emptyText`
79+
80+
Text to display when the array is empty.
81+
82+
```jsx
83+
<TextArrayField source="genres" emptyText="No genres available" />
84+
```
85+
86+
## `record`
87+
88+
The record containing the data to display. Usually provided by react-admin automatically.
89+
90+
```jsx
91+
const book = {
92+
id: 1,
93+
title: 'War and Peace',
94+
genres: [
95+
'Fiction',
96+
'Historical Fiction',
97+
'Classic Literature',
98+
'Russian Literature',
99+
],
100+
};
101+
102+
<TextArrayField source="genres" record={book} />
103+
```
104+
105+
## `size`
106+
107+
The size of the Chip components. Accepts any value supported by MUI's Chip (`small`, `medium`). The default is `small`.
108+
109+
```jsx
110+
<TextArrayField source="genres" size="medium" />
111+
```
112+
113+
## `source`
114+
115+
The name of the record field containing the array to display.
116+
117+
```jsx
118+
<TextArrayField source="genres" />
119+
```
120+
121+
## `sx`
122+
123+
Custom styles for the Stack, using MUI's `sx` prop.
124+
125+
{% raw %}
126+
```jsx
127+
<TextArrayField source="genres" sx={{ gap: 2 }} />
128+
```
129+
{% endraw %}
130+
131+
## `variant`
132+
133+
The variant of the Chip components. Accepts any value supported by MUI's Chip (`filled`, `outlined`). The default is `filled`.
134+
135+
```jsx
136+
<TextArrayField source="genres" variant="outlined" />
137+
```
138+

‎docs/img/text-array-field.png‎

15.2 KB
Loading

‎docs/navigation.html‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -194,6 +194,7 @@
194194
<li {% if page.path == 'ReferenceOneField.md' %} class="active" {% endif %}><a class="nav-link" href="./ReferenceOneField.html"><code>&lt;ReferenceOneField&gt;</code></a></li>
195195
<li {% if page.path == 'RichTextField.md' %} class="active beginner" {% else %} class="beginner" {% endif %}><a class="nav-link" href="./RichTextField.html"><code>&lt;RichTextField&gt;</code></a></li>
196196
<li {% if page.path == 'SelectField.md' %} class="active beginner" {% else %} class="beginner" {% endif %}><a class="nav-link" href="./SelectField.html"><code>&lt;SelectField&gt;</code></a></li>
197+
<li {% if page.path == 'TextArrayField.md' %} class="active beginner" {% else %} class="beginner" {% endif %}><a class="nav-link" href="./TextArrayField.html"><code>&lt;TextArrayField&gt;</code></a></li>
197198
<li {% if page.path == 'TextField.md' %} class="active beginner" {% else %} class="beginner" {% endif %}><a class="nav-link" href="./TextField.html"><code>&lt;TextField&gt;</code></a></li>
198199
<li {% if page.path == 'TranslatableFields.md' %} class="active" {% endif %}><a class="nav-link" href="./TranslatableFields.html"><code>&lt;TranslatableFields&gt;</code></a></li>
199200
<li {% if page.path == 'UrlField.md' %} class="active" {% endif %}><a class="nav-link" href="./UrlField.html"><code>&lt;UrlField&gt;</code></a></li>

0 commit comments

Comments
 (0)