Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[Doc] Improve ImageField, NumberField and SelectField docs #8045

Merged
merged 1 commit into from
Aug 10, 2022
Merged

[Doc] Improve ImageField, NumberField and SelectField docs #8045

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
74 changes: 54 additions & 20 deletions docs/ImageField.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,9 @@ title: "The ImageField Component"

# `<ImageField>`

If you need to display an image based on a path contained in a record field, you can use the `<ImageField />` component:
When you need to display an image based on a path contained in a record field, use the `<ImageField />` component.

## Usage

```jsx
import { ImageField } from 'react-admin';
Expand All @@ -18,9 +20,28 @@ import { ImageField } from 'react-admin';
</div>
```

You can also use `<ImageField>` on fields that contain an array of image objects:

```js
<ImageField source="pictures" src="url" title="desc" />

// Renders the record
// {
// id: 123,
// pictures: [
// { url: 'image1.jpg', desc: 'First image' },
// { url: 'image2.jpg', desc: 'Second image' },
// ]
// } as
<ul>
<li><img src="image1.jpg" title="First image" /></li>
<li><img src="image2.jpg" title="Second image" /></li>
</ul>
```

This field is also often used within the [`<ImageInput />`](./ImageInput.md) component to display a preview.

## Properties
## Props

| Prop | Required | Type | Default | Description |
| ------- | -------- | ------ | ------------ | ---------------------------------------------------------------------------------------- |
Expand All @@ -29,18 +50,23 @@ This field is also often used within the [`<ImageInput />`](./ImageInput.md) com

`<ImageField>` also accepts the [common field props](./Fields.md#common-field-props).

## `sx`: CSS API
## `src`

The `<ImageField>` component accepts the usual `className` prop. You can also override many styles of the inner components thanks to the `sx` property (as most MUI components, see their [documentation about it](https://mui.com/customization/how-to-customize/#overriding-nested-component-styles)). This property accepts the following subclasses:
If the record actually contains an array of images in the property defined by the `source` prop, the `src` prop will be needed to determine the `src` value of the images, for example:

| Rule name | Description |
|-------------------------|--------------------------------------------------------------------------------|
| `& .RaImageField-list` | Applied to the underlying `<ul>` component when `sourceValue` prop is an array |
| `& .RaImageField-image` | Applied to each underlying `<img>` component |
```js
// This is the record
{
pictures: [
{ url: 'image1.jpg', desc: 'First image' },
{ url: 'image2.jpg', desc: 'Second image' },
]
}

To override the style of all instances of `<ImageField>` using the [MUI style overrides](https://mui.com/customization/globals/#css), use the `RaImageField` key.
<ImageField source="pictures" src="url" title="desc" />
```

## Usage
## `title`

The optional `title` prop points to the picture title property, used for both `alt` and `title` attributes. It can either be a hard-written string, or a path within your JSON object:

Expand All @@ -54,16 +80,24 @@ The optional `title` prop points to the picture title property, used for both `a
// renders img title as "Picture", since "Picture" is not a path in previous given object
```

If the record actually contains an array of images in the property defined by the `source` prop, the `src` prop will be needed to determine the `src` value of the images, for example:
## `sx`: CSS API

```js
// This is the record
{
pictures: [
{ url: 'image1.jpg', desc: 'First image' },
{ url: 'image2.jpg', desc: 'Second image' },
]
}
The `<ImageField>` component accepts the usual `className` prop. You can also override many styles of the inner components thanks to the `sx` property (as most MUI components, see their [documentation about it](https://mui.com/customization/how-to-customize/#overriding-nested-component-styles)). This property accepts the following subclasses:

<ImageField source="pictures" src="url" title="desc" />
| Rule name | Description |
|-------------------------|--------------------------------------------------------------------------------|
| `& .RaImageField-list` | Applied to the underlying `<ul>` component when `sourceValue` prop is an array |
| `& .RaImageField-image` | Applied to each underlying `<img>` component |

For instance, to specify a size for the image:

{% raw %}
```jsx
<ImageField
source="thumbnail"
sx={{ '& img': { maxWidth: 50, maxHeight: 50, objectFit: 'contain' } }}
/>
```
{% endraw %}

To override the style of all instances of `<ImageField>` using the [MUI style overrides](https://mui.com/customization/globals/#css), use the `RaImageField` key.
58 changes: 41 additions & 17 deletions docs/NumberField.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,30 +5,52 @@ title: "The NumberField Component"

# `<NumberField>`

Displays a number formatted according to the browser locale, right aligned.
Displays a number formatted according to the browser locale, right aligned. Ideal for floats, currencies, percentages, units, etc.

![NumberField](./img/number-field.webp)

## Usage

```jsx
import { NumberField } from 'react-admin';

<NumberField source="score" />
// renders the record { id: 1234, score: 567 } as
<span>567</span>
<NumberField source="views" />
// renders the record { id: 1234, views: 2108 } as
<span>2 108</span>
```

## Properties
`<NumberField>` uses `Intl.NumberFormat()` if available, passing the `locales` and `options` props as arguments. This allows a perfect display of decimals, currencies, percentages, etc. See [Intl.NumberFormat documentation](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat) for the `options` prop syntax.

If Intl is not available, `<NumberField>` outputs numbers as is (and ignores the `locales` and `options` props).

## Props

| Prop | Required | Type | Default | Description |
| ----------- | -------- | ------------------ | ------- | -------------------------------------------------------------------------------- |
| `locales` | Optional | string | '' | Locale to use for formatting. Passed as first argument to `Intl.NumberFormat()`. |
| `options` | Optional | Object | - | Number formatting options. Passed as second argument to `Intl.NumberFormat()`. |
| `textAlign` | Optional | `'left' | 'right'` | `right` | Text alignment in a Datagrid |

| Prop | Required | Type | Default | Description |
| --------- | -------- | ------ | ------- | -------------------------------------------------------------------------------------------------------- |
| `locales` | Optional | string | '' | Override the browser locale in the date formatting. Passed as first argument to `Intl.NumberFormat()`. |
| `options` | Optional | Object | - | Number formatting options. Passed as second argument to `Intl.NumberFormat()`. |

`<NumberField>` also accepts the [common field props](./Fields.md#common-field-props).

## Usage
## `locales`

`<NumberField>` uses `Intl.NumberFormat()` if available, passing the `locales` and `options` props as arguments. This allows a perfect display of decimals, currencies, percentages, etc. See [Intl.NumberFormat documentation](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat) for the `options` prop syntax.
Override the browser locale in the number formatting. Passed as first argument to `Intl.NumberFormat()`.

If Intl is not available, `<NumberField>` outputs numbers as is (and ignores the `locales` and `options` props).
{% raw %}
```jsx
import { NumberField } from 'react-admin';

<NumberField source="price" locales="fr-FR" options={{ style: 'currency', currency: 'USD' }} />
// renders the record { id: 1234, price: 25.99 } as
<span>25,99 $US</span>
```
{% endraw %}

## `options`

Options passed to `Intl.NumberFormat()`. See [the Intl.NumberFormat documentation](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat) for the `options` prop syntax.

{% raw %}
```jsx
Expand All @@ -46,15 +68,17 @@ import { NumberField } from 'react-admin';
// renders the record { id: 1234, price: 25.99 } as
<span>$25.99</span>

<NumberField source="price" locales="fr-FR" options={{ style: 'currency', currency: 'USD' }} />
// renders the record { id: 1234, price: 25.99 } as
<span>25,99 $US</span>
<NumberField source="volume" options={{ style: 'unit', unit: 'liter' }} />
// renders the record { id: 1234, volume: 3500 } as
<span>3,500 L</span>
```
{% endraw %}

**Tip**: If you need more formatting options than what `Intl.NumberFormat` can provide, build your own field component leveraging a third-party library like [numeral.js](http://numeraljs.com/).
**Tip**: If you need more formatting options than what `Intl.NumberFormat()` can provide, build your own field component leveraging a third-party library like [numeral.js](http://numeraljs.com/).

## `textAlign`

**Tip**: When used in a `Show` view, the right alignment may look weird. Disable it by setting the `textAlign` attribute to "left":
By default, `<NumberField>` is right-aligned in a [`<Datagrid>`](./Datagrid.md). Change it by setting the `textAlign` prop to "left":

```jsx
import { NumberField } from 'react-admin';
Expand Down
104 changes: 89 additions & 15 deletions docs/SelectField.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,9 +5,10 @@ title: "The SelectField Component"

# `<SelectField>`


When you need to display an enumerated field, `<SelectField>` maps the value to a string.

## Usage

For instance, if the `gender` field can take values "M" and "F", here is how to display it as either "Male" or "Female":

```jsx
Expand All @@ -19,7 +20,7 @@ import { SelectField } from 'react-admin';
]} />
```

## Properties
## Props

| Prop | Required | Type | Default | Description |
| ----------------- | -------- | ----------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
Expand All @@ -30,45 +31,118 @@ import { SelectField } from 'react-admin';

`<SelectField>` also accepts the [common field props](./Fields.md#common-field-props).

## Usage
## `choices`

By default, the option is built by:
An array of objects with two keys:

- `id` to map the field value
- `name` for the string to display

```jsx
const languages = [
{ id: "ab", name: "Abkhaz" },
{ id: "aa", name: "Afar" },
{ id: "af", name: "Afrikaans" },
{ id: "ak", name: "Akan" },
{ id: "sq", name: "Albanian" },
{ id: "am", name: "Amharic" },
{ id: "ar", name: "Arabic" },
// ...
];

- finding a choice where the `id` property equals the field value
- using the `name` property as the option text
<SelectField source="language" choices={languages} />
```

You can also customize the properties to use for the lookup value and text, thanks to the `optionValue` and `optionText` attributes.
You can customize the properties to use for the lookup value and text, thanks to the [`optionValue`](#optionvalue) and [`optionText`](#optiontext) attributes.

```jsx
const choices = [
{ _id: 123, full_name: 'Leo Tolstoi', sex: 'M' },
{ _id: 456, full_name: 'Jane Austen', sex: 'F' },
const languages = [
{ id: "ab", name: "Abkhaz", nativeName:"аҧсуа" },
{ id: "aa", name: "Afar", nativeName:"Afaraf" },
{ id: "af", name: "Afrikaans", nativeName:"Afrikaans" },
{ id: "ak", name: "Akan", nativeName:"Akan" },
{ id: "sq", name: "Albanian", nativeName:"Shqip" },
{ id: "am", name: "Amharic", nativeName:"አማርኛ" },
{ id: "ar", name: "Arabic", nativeName:"العربية" },
// ...
];
<SelectField source="author_id" choices={choices} optionText="full_name" optionValue="_id" />

<SelectField source="language" choices={languages} optionText="nativeName" />
```

**Tip**: If you need to fetch the choices, you probably need a [`<ReferenceField>`](./ReferenceField.md) instead.

## `optionText`

You can customize the property to use for the lookup text instead of `name` using the `optionText` prop.

```jsx
const currencies = [
// ...
{
id: 'USD',
name: 'US Dollar',
namePlural: 'US dollars',
symbol: '$',
symbolNative: '$',
},
{
id: 'RUB',
name: 'Russian Ruble',
namePlural: 'Russian rubles',
symbol: 'RUB',
symbolNative: '₽.',
},
// ...
];
<SelectField source="currency" choices={choices} optionText="symbol" />
```

`optionText` also accepts a function, so you can shape the option text at will:

```jsx
const choices = [
const authors = [
{ id: 123, first_name: 'Leo', last_name: 'Tolstoi' },
{ id: 456, first_name: 'Jane', last_name: 'Austen' },
];
const optionRenderer = choice => `${choice.first_name} ${choice.last_name}`;
<SelectField source="author_id" choices={choices} optionText={optionRenderer} />
<SelectField source="author" choices={authors} optionText={optionRenderer} />
```

`optionText` also accepts a React Element, that will be cloned and receive the related choice as the `record` prop. You can use Field components there.
`optionText` also accepts a React Element. React-admin renders it once per choice, within a [`RecordContext`](./useRecordContext.md) containing the related choice. You can use Field components there.

```jsx
const choices = [
{ id: 123, first_name: 'Leo', last_name: 'Tolstoi' },
{ id: 456, first_name: 'Jane', last_name: 'Austen' },
];
const FullNameField = ({ record }) => <Chip>{record.first_name} {record.last_name}</Chip>;
const FullNameField = () => {
const record = useRecordContext();
return record ? (
<Chip>{record.first_name} {record.last_name}</Chip>
) : null;
};

<SelectField source="author_id" choices={choices} optionText={<FullNameField />}/>
```

## `optionValue`

You can customize the property to use for the lookup value instead of `id` using the `optionValue` prop.

```jsx
const countries = [
{ name: 'Afghanistan', code: 'AF'},
{ name: 'Åland Islands', code: 'AX'},
{ name: 'Albania', code: 'AL'},
{ name: 'Algeria', code: 'DZ'},
// ...
];
<SelectField source="country" choices={choices} optionValue="code" />
```

## `translateChoice`

The current choice is translated by default, so you can use translation identifiers as choices:

```js
Expand Down
Binary file added docs/img/number-field.webp
View file
Open in desktop
Binary file not shown.