Skip to content

Commit

Permalink
Documentation and upgrade guide
Browse files Browse the repository at this point in the history
  • Loading branch information
djhi committed Sep 13, 2019
1 parent 8cd777b commit c9637dd
Show file tree
Hide file tree
Showing 2 changed files with 34 additions and 9 deletions.
25 changes: 24 additions & 1 deletion UPGRADE.md
Original file line number Diff line number Diff line change
Expand Up @@ -893,7 +893,7 @@ const PostFilter = props =>

We rewrote the `<AutocompleteInput>` and `<AutocompleteArrayInput>` components from scratch using [`downshift`](https://github.com/downshift-js/downshift), while the previous version was based on [react-autosuggest](http://react-autosuggest.js.org/). The new components are more robust and more future-proof, and their API didn't change.

There are two breaking changes in the new `<AutocompleteInput>` and `<AutocompleteArrayInput>` components:
There are three breaking changes in the new `<AutocompleteInput>` and `<AutocompleteArrayInput>` components:

- The `inputValueMatcher` prop is gone. We removed a feature many found confusing: the auto-selection of an item when it was matched exactly. So react-admin no longer selects anything automatically, therefore the `inputValueMatcher` prop is obsolete

Expand Down Expand Up @@ -921,6 +921,29 @@ There are two breaking changes in the new `<AutocompleteInput>` and `<Autocomple
/>
```

- The `suggestionComponent` prop is gone.

Instead, the new `<AutocompleteInput>` and `<AutocompleteArrayInput>` components use the `optionText` like all other inputs accepting choices.
However, if you pass a React element as the `optionText`, you must now also specify the new `matchSuggestion` prop.
This is required because the inputs use the `optionText` by default to filter suggestions.
This function receives the current filter and a choice, and should return a boolean indicating whether this choice matches the filter.

```diff
<AutocompleteInput
source="role"
- suggestionComponent={MyComponent}
+ optionText={<MyComponent />}
+ matchSuggestion={matchSuggestion}
/>

<AutocompleteArrayInput
source="role"
- suggestionComponent={MyComponent}
+ optionText={<MyComponent />}
+ matchSuggestion={matchSuggestion}
/>
```

Besides, some props which were applicable to both components did not make sense for the `<AutocompleteArrayInput>` component:

- `allowEmpty`: As the `<AutocompleteArrayInput>` deals with arrays, it does not make sense to add an empty choice. This prop is no longer accepted and will be ignored.
Expand Down
18 changes: 10 additions & 8 deletions docs/Inputs.md
Original file line number Diff line number Diff line change
Expand Up @@ -207,14 +207,16 @@ Lastly, would you need to override the props of the suggestions container (a `Po
| Prop | Required | Type | Default | Description |
| ---|---|---|---|--- |
| `choices` | Required | `Object[]` | - | List of items to autosuggest |
| `resource` | Required | `string` | - | The resource working on. This field is passed down by wrapped components like `Create` and `Edit`. |
| `source` | Required | `string` | - | Name of field to edit, its type should match the type retrieved from `optionValue` |
| `allowEmpty` | Optional | `boolean` | `false` | If `false` and the searchText typed did not match any suggestion, the searchText will revert to the current value when the field is blurred. If `true` and the `searchText` is set to `''` then the field will set the input value to `null`. |
| `choices` | Required | `Object[]` | - | List of items to autosuggest |
| `emptyValue` | Optional | anything | `null` | The value to use for the empty element |
| `emptyText` | Optional | `string` | '' | The text to use for the empty element |
| `matchSuggestion` | Optional | `Function` | - | Required if `optionText` is a React element. Function returning a boolean indicating whether a choice matches the filter. `(filter, choice) => boolean`
| `optionValue` | Optional | `string` | `id` | Fieldname of record containing the value to use as input value |
| `optionText` | Optional | <code>string &#124; Function</code> | `name` | Fieldname of record to display in the suggestion item or function which accepts the correct record as argument (`(record)=> {string}`) |
| `resource` | Required | `string` | - | The resource working on. This field is passed down by wrapped components like `Create` and `Edit`. |
| `setFilter` | Optional | `Function` | null | A callback to inform the `searchText` has changed and new `choices` can be retrieved based on this `searchText`. Signature `searchText => void`. This function is automatically setup when using `ReferenceInput`. |
| `suggestionComponent` | Optional | Function | `({ suggestion, query, isHighlighted, props }) => <div {...props} />` | Allows to override how the item is rendered. |
| `source` | Required | `string` | - | Name of field to edit, its type should match the type retrieved from `optionValue` |
| `shouldRenderSuggestions` | Optional | Function | `() => true` | A function that returns a `boolean` to determine whether or not suggestions are rendered. Use this when working with large collections of data to improve performance and user experience. This function is passed into the underlying react-autosuggest component. Ex.`(value) => value.trim() > 2` |
## `<AutocompleteArrayInput>`
Expand Down Expand Up @@ -313,15 +315,15 @@ If you need to override the props of the suggestions container (a `Popper` eleme
| Prop | Required | Type | Default | Description |
| ---|---|---|---|--- |
| `choices` | Required | `Object[]` | - | List of items to autosuggest |
| `resource` | Required | `string` | - | The resource working on. This field is passed down by wrapped components like `Create` and `Edit`. |
| `source` | Required | `string` | - | Name of field to edit, its type should match the type retrieved from `optionValue` |
| `fullWith` | Optional | Boolean | If `true`, the input will take all the form width
| `matchSuggestion` | Optional | `Function` | - | Required if `optionText` is a React element. Function returning a boolean indicating whether a choice matches the filter. `(filter, choice) => boolean`
| `optionValue` | Optional | `string` | `id` | Fieldname of record containing the value to use as input value |
| `optionText` | Optional | <code>string &#124; Function</code> | `name` | Fieldname of record to display in the suggestion item or function which accepts the current record as argument (`(record)=> {string}`) |
| `resource` | Required | `string` | - | The resource working on. This field is passed down by wrapped components like `Create` and `Edit`. |
| `setFilter` | Optional | `Function` | null | A callback to inform the `searchText` has changed and new `choices` can be retrieved based on this `searchText`. Signature `searchText => void`. This function is automatically setup when using `ReferenceInput`. |
| `suggestionComponent` | Optional | Function | `({ suggestion, query, isHighlighted, props }) => <div {...props} />` | Allows to override how the item is rendered. |
| `source` | Required | `string` | - | Name of field to edit, its type should match the type retrieved from `optionValue` |
| `suggestionLimit` | Optional | Number | null | Limits the numbers of suggestions that are shown in the dropdown list |
| `shouldRenderSuggestions` | Optional | Function | `() => true` | A function that returns a `boolean` to determine whether or not suggestions are rendered. Use this when working with large collections of data to improve performance and user experience. This function is passed into the underlying react-autosuggest component. Ex.`(value) => value.trim() > 2` |
| `fullWith` | Optional | Boolean | If `true`, the input will take all the form width
## `<BooleanInput>` and `<NullableBooleanInput>`
Expand Down

0 comments on commit c9637dd

Please sign in to comment.