diff --git a/docs/ImageField.md b/docs/ImageField.md index ada7254b909..9e37b9fb71a 100644 --- a/docs/ImageField.md +++ b/docs/ImageField.md @@ -5,7 +5,9 @@ title: "The ImageField Component" # `` -If you need to display an image based on a path contained in a record field, you can use the `` component: +When you need to display an image based on a path contained in a record field, use the `` component. + +## Usage ```jsx import { ImageField } from 'react-admin'; @@ -18,9 +20,28 @@ import { ImageField } from 'react-admin'; ``` +You can also use `` on fields that contain an array of image objects: + +```js + + +// Renders the record +// { +// id: 123, +// pictures: [ +// { url: 'image1.jpg', desc: 'First image' }, +// { url: 'image2.jpg', desc: 'Second image' }, +// ] +// } as +
    +
    • +
    • +
+``` + This field is also often used within the [``](./ImageInput.md) component to display a preview. -## Properties +## Props | Prop | Required | Type | Default | Description | | ------- | -------- | ------ | ------------ | ---------------------------------------------------------------------------------------- | @@ -29,18 +50,23 @@ This field is also often used within the [``](./ImageInput.md) com `` also accepts the [common field props](./Fields.md#common-field-props). -## `sx`: CSS API +## `src` -The `` 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 `
    ` component when `sourceValue` prop is an array | -| `& .RaImageField-image` | Applied to each underlying `` 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 `` using the [MUI style overrides](https://mui.com/customization/globals/#css), use the `RaImageField` key. + +``` -## 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: @@ -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 `` 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: - +| Rule name | Description | +|-------------------------|--------------------------------------------------------------------------------| +| `& .RaImageField-list` | Applied to the underlying `
      ` component when `sourceValue` prop is an array | +| `& .RaImageField-image` | Applied to each underlying `` component | + +For instance, to specify a size for the image: + +{% raw %} +```jsx + ``` +{% endraw %} + +To override the style of all instances of `` using the [MUI style overrides](https://mui.com/customization/globals/#css), use the `RaImageField` key. diff --git a/docs/NumberField.md b/docs/NumberField.md index 4d9c0e8db6d..3f589fbf06c 100644 --- a/docs/NumberField.md +++ b/docs/NumberField.md @@ -5,30 +5,52 @@ title: "The NumberField Component" # `` -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'; - -// renders the record { id: 1234, score: 567 } as -567 + +// renders the record { id: 1234, views: 2108 } as +2 108 ``` -## Properties +`` 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, `` 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()`. | `` also accepts the [common field props](./Fields.md#common-field-props). -## Usage +## `locales` -`` 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, `` outputs numbers as is (and ignores the `locales` and `options` props). +{% raw %} +```jsx +import { NumberField } from 'react-admin'; + + +// renders the record { id: 1234, price: 25.99 } as +25,99 $US +``` +{% 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 @@ -46,15 +68,17 @@ import { NumberField } from 'react-admin'; // renders the record { id: 1234, price: 25.99 } as $25.99 - -// renders the record { id: 1234, price: 25.99 } as -25,99 $US + +// renders the record { id: 1234, volume: 3500 } as +3,500 L ``` {% 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, `` is right-aligned in a [``](./Datagrid.md). Change it by setting the `textAlign` prop to "left": ```jsx import { NumberField } from 'react-admin'; diff --git a/docs/SelectField.md b/docs/SelectField.md index 85cb16b3787..ec0f7034f60 100644 --- a/docs/SelectField.md +++ b/docs/SelectField.md @@ -5,9 +5,10 @@ title: "The SelectField Component" # `` - When you need to display an enumerated field, `` 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 @@ -19,7 +20,7 @@ import { SelectField } from 'react-admin'; ]} /> ``` -## Properties +## Props | Prop | Required | Type | Default | Description | | ----------------- | -------- | ----------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------- | @@ -30,45 +31,118 @@ import { SelectField } from 'react-admin'; `` 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 + +``` -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:"العربية" }, + // ... ]; - + + +``` + +**Tip**: If you need to fetch the choices, you probably need a [``](./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: '₽.', + }, + // ... +]; + ``` `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}`; - + ``` -`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 }) => {record.first_name} {record.last_name}; +const FullNameField = () => { + const record = useRecordContext(); + return record ? ( + {record.first_name} {record.last_name} + ) : null; +}; + }/> ``` +## `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'}, + // ... +]; + +``` + +## `translateChoice` + The current choice is translated by default, so you can use translation identifiers as choices: ```js diff --git a/docs/img/number-field.webp b/docs/img/number-field.webp new file mode 100644 index 00000000000..bc8b78a776b Binary files /dev/null and b/docs/img/number-field.webp differ