Skip to content

Commit

Permalink
Merge pull request #5346 from WiXSL/docs-css-api
Browse files Browse the repository at this point in the history 
[Doc] Added Inputs and Fields CSS Api documentation
  • Loading branch information
@fzaninotto
fzaninotto committed Oct 8, 2020
2 parents a8e38be + 2bb21f8 commit 703be28
Show file tree
Hide file tree
Showing 5 changed files with 210 additions and 40 deletions.
17 changes: 15 additions & 2 deletions docs/CreateEdit.md
View file
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
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 @@ -567,9 +602,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 @@ -664,10 +699,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 @@ -943,18 +986,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 @@ -1008,9 +1059,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

0 comments on commit 703be28

Please sign in to comment.