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

Jump to bottom

[Doc] Added Inputs and Fields CSS Api documentation #5346

Merged
merged 19 commits into from
Oct 8, 2020
Merged

[Doc] Added Inputs and Fields CSS Api documentation #5346

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
19 commits
Select commit Hold shift + click to select a range
60f1270
Add components CSS api documentation
Oct 2, 2020
8e69374
Add descriptions for AutocompleteInput and AutocompleteArrayInput CSS…
Oct 2, 2020
031420d
Add descriptions for more ra inputs CSS api
Oct 2, 2020
5d9dafb
Add and improve descriptions of inputs css api
Oct 3, 2020
a5c93d1
Fix filds properties tables
Oct 3, 2020
0cdedef
Fix AutocompleteArrayInput CSS api descriptions
Oct 3, 2020
b9243ad
Add descriptions of Fields components Css api
Oct 3, 2020
f8ee12e
Improve descriptions of Inputs and Fields components Css api
Oct 3, 2020
2fb6103
FIx grammar
Oct 4, 2020
cad7024
Improve React imports in examples
Oct 4, 2020
2ee0d46
Improved CheckboxGroupInput Css apis
Oct 5, 2020
a88508e
Update docs/Fields.md
WiXSL Oct 5, 2020
4104690
Change suggested wording for all fields and inputs
Oct 5, 2020
4cb33d0
Change type case
Oct 5, 2020
e74985a
Change type case
Oct 5, 2020
2a31b60
Change type case
Oct 5, 2020
f680d08
Revert props tables formatting
Oct 7, 2020
2e074f6
Added Create and Edit components CSS Api documentation
Oct 7, 2020
2bb21f8
Added Show component CSS Api documentation
Oct 7, 2020
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
17 changes: 15 additions & 2 deletions docs/CreateEdit.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -106,6 +106,19 @@ You can customize the `<Create>` and `<Edit>` components using the following pro

`<Create>` also accepts a `record` prop, to initialize the form based on a value object.

### CSS API

The `<Create>` and `<Edit>` components accepts the usual `className` prop but you can override many class names injected to the inner components by React-admin thanks to the `classes` property (as most Material UI components, see their [documentation about it](https://material-ui.com/customization/components/#overriding-styles-with-classes)). This property accepts the following keys:

| Rule name | Description |
| ----------- | ------------------------------------------------------------------------------------------ |
| `root` | Alternative to using `className`. Applied to the root element |
| `main` | Applied to the main container |
| `noActions` | Applied to the main container when `actions` prop is `false` |
| `card` | Applied to the child component inside the main container (Material UI's `Card` by default) |

To override the style of all instances of `<Create>` and `<Edit>` components using the [material-ui style overrides](https://material-ui.com/customization/globals/#css), use the `RaCreate` and `RaEdit` keys respectively.

### Page Title

By default, the title for the `Create` view is "Create [resource_name]", and the title for the `Edit` view is "Edit [resource_name] #[record_id]".
Expand Down Expand Up @@ -304,7 +317,7 @@ const PostEdit = props => (
By default, when the save action succeeds, react-admin shows a notification, and redirects to another page. You can override this behavior and pass custom side effects by providing a function as `onSuccess` prop:

```jsx
import React from 'react';
import * as React from 'react';
import { useNotify, useRefresh, useRedirect, Edit, SimpleForm } from 'react-admin';

const PostEdit = props => {
Expand Down Expand Up @@ -359,7 +372,7 @@ By default, when the save action fails at the dataProvider level, react-admin sh
You can override this behavior and pass custom side effects by providing a function as `onFailure` prop:

```jsx
import React from 'react';
import * as React from 'react';
import { useNotify, useRefresh, useRedirect, Edit, SimpleForm } from 'react-admin';

const PostEdit = props => {
Expand Down
81 changes: 66 additions & 15 deletions docs/Fields.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -221,6 +221,14 @@ import { BooleanField } from 'react-admin';

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

### CSS API

| Rule name | Description |
| ---------- | --------------------------- |
| `root` | Applied to the root element |

To override the style of all instances of `<BooleanField>` using the [material-ui style overrides](https://material-ui.com/customization/globals/#css), use the `RaBooleanField` key.

### Usage

The `<BooleanField>` includes a tooltip text for accessibility (or to query in "end to end" tests). By default, it is the translated value ('true' or 'false' in English).
Expand Down Expand Up @@ -248,6 +256,16 @@ import AlarmOffIcon from '@material-ui/icons/AlarmOff';

Displays a value inside a ["Chip"](https://material-ui.com/components/chips), which is Material UI's term for a label.

### CSS API

| Rule name | Description |
| ---------- | -------------------------------------------------------- |
| `chip` | Applied to the underlying Material UI's `Chip` component |

To override the style of all instances of `<ChipField>` using the [material-ui style overrides](https://material-ui.com/customization/globals/#css), use the `RaChipField` key.

### Usage

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

Expand Down Expand Up @@ -374,6 +392,15 @@ This field is also often used within the [<ImageInput />](./Inputs.md#imageinput

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

### CSS API

| Rule name | Description |
| ---------- | ------------------------------------------------------------------------------ |
| `list` | Applied to the underlying `<ul>` component when `sourceValue` prop is an array |
| `image` | Applied to each underlying `<img>` component |

To override the style of all instances of `<ImageField>` using the [material-ui style overrides](https://material-ui.com/customization/globals/#css), use the `RaImageField` key.

### Usage

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 Down Expand Up @@ -432,6 +459,14 @@ This field is also often used within an [<FileInput />](./Inputs.md#fileinput) c

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

### CSS API

| Rule name | Description |
| ---------- | --------------------------- |
| `root` | Applied to the root element |

To override the style of all instances of `<FileField>` using the [material-ui style overrides](https://material-ui.com/customization/globals/#css), use the `RaFileField` key.

### Usage

The optional `title` prop points to the file title property, used for `title` attributes. It can either be a hard-written string, or a path within your JSON object:
Expand Down Expand Up @@ -547,9 +582,9 @@ import { SelectField } from 'react-admin';

| Prop | Required | Type | Default | Description |
| ----------------- | -------- | ----------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `optionText` | Optional | `string | function | Element` | 'name' | Name of the field to use to display the matching choice, or function returning that field name, or a React element to render for that choice |
| `optionText` | Optional | `string | Function | Element` | 'name' | Name of the field to use to display the matching choice, or function returning that field name, or a React element to render for that choice |
| `optionValue` | Optional | `string` | 'id' | Name of the field to compare to the value to find the matching choice |
| `translateChoice` | Optional | `Boolean` | true | Whether or not the choice text should be translated |
| `translateChoice` | Optional | `boolean` | `true` | Whether or not the choice text should be translated |

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

Expand Down Expand Up @@ -644,10 +679,18 @@ With this configuration, `<ReferenceField>` wraps the user's name in a link to t
| `reference` | Required | `string` | - | The name of the resource for the referenced records, e.g. 'posts' |
| `children` | Required | `Element` | - | The Field element used to render the referenced record |
| `link` | Optional | `string` | 'edit' | Target of the link wrapping the rendered child |
| `sortBy` | Optional | `string | function` | `source` | Name of the field to use for sorting when the user clicks on the column header. Set to `false` to disable the link. |
| `sortBy` | Optional | `string | Function` | `source` | Name of the field to use for sorting when the user clicks on the column header. Set to `false` to disable the link. |

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

### CSS API

| Rule name | Description |
| ---------- | ----------------------------- |
| `link` | Applied to each child element |

To override the style of all instances of `<ReferenceField>` using the [material-ui style overrides](https://material-ui.com/customization/globals/#css), use the `RaReferenceField` key.

### Usage

`<ReferenceField>` accepts a `reference` attribute, which specifies the resource to fetch for the related record.
Expand Down Expand Up @@ -870,18 +913,26 @@ export const PostList = (props) => (

### Properties

| Prop | Required | Type | Default | Description |
| ------------ | -------- | ------------------- | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `reference` | Required | `string` | - | The name of the resource for the referenced records, e.g. 'tags' |
| `children` | Required | `Element` | - | The Field element used to render the referenced records |
| `sortBy` | Optional | `string | function` | `source` | When used in a List, name of the field to use for sorting when the user clicks on the column header. Set to `false` to disable the link. |
| `filter` | Optional | `Object` | - | Filters to use when fetching the related records (the filtering is done client-side) |
| `pagination` | Optional | `Element` | - | Pagination element to display pagination controls. empty by default (no pagination) |
| `perPage` | Optional | `number` | 1000 | Maximum number of results to display |
| `sort` | Optional | `{ field, order }` | `{ field: 'id', order: 'DESC' }` | Sort order to use when displaying the related records (the sort is done client-side) |
| Prop | Required | Type | Default | Description |
| ------------ | -------- | ------------------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `reference` | Required | `string` | - | The name of the resource for the referenced records, e.g. 'tags' |
| `children` | Required | `Element` | - | The Field element used to render the referenced records |
| `sortBy` | Optional | `string | Function` | `source` | When used in a `List`, name of the field to use for sorting when the user clicks on the column header. Set to `false` to disable the link. |
| `filter` | Optional | `Object` | - | Filters to use when fetching the related records (the filtering is done client-side) |
| `pagination` | Optional | `Element` | - | Pagination element to display pagination controls. empty by default (no pagination) |
| `perPage` | Optional | `number` | 1000 | Maximum number of results to display |
| `sort` | Optional | `{ field, order }` | `{ field: 'id', order: 'DESC' }` | Sort order to use when displaying the related records (the sort is done client-side) |

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

### CSS API

| Rule name | Description |
| ---------- | -------------------------------------------------------------------------------------- |
| `progress` | Applied to the Material UI's `LinearProgress` component while `loaded` prop is `false` |

To override the style of all instances of `<ReferenceArrayField>` using the [material-ui style overrides](https://material-ui.com/customization/globals/#css), use the `RaReferenceArrayField` key.

### Usage

`<ReferenceArrayField>` expects a `reference` attribute, which specifies the resource to fetch for the related records. It also expects a `source` attribute, which defines the field containing the list of ids to look for in the referenced resource.
Expand Down Expand Up @@ -935,9 +986,9 @@ import { RichTextField } from 'react-admin';

### Properties

| Prop | Required | Type | Default | Description |
| ----------- | -------- | --------- | ------- | -------------------------------------------------- |
| `stripTags` | Optional | `Boolean` | false | If true, remove all HTML tags and render text only |
| Prop | Required | Type | Default | Description |
| ----------- | -------- | --------- | -------- | ---------------------------------------------------- |
| `stripTags` | Optional | `boolean` | `false` | If `true`, remove all HTML tags and render text only |

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

Expand Down
Loading