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

[docs] Implement Style Guide on "Advanced" Data Grid doc pages #6331

Merged
merged 3 commits into from
Oct 3, 2022
Merged

[docs] Implement Style Guide on "Advanced" Data Grid doc pages #6331

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
192997e
advanced doc revisions
samuelsycamore Sep 29, 2022
cb0ce83
remove warning
samuelsycamore Oct 1, 2022
67d70e7
merge next
samuelsycamore Oct 3, 2022
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
Next Next commit
advanced doc revisions
  • Loading branch information
@samuelsycamore
samuelsycamore committed Sep 29, 2022
commit 192997e44002ff1d94306556798012fbf45c99b7
35 changes: 16 additions & 19 deletions docs/data/data-grid/api-object/api-object.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,29 +1,26 @@
# Data Grid - API object

<p class="description">Interact with the grid using its API.</p>
<p class="description">Interact with the Data Grid using its API.</p>

## What is the API object

The API object is an interface containing the state and all the methods available to programmatically interact with the grid.
The API object is an interface containing the state and all the methods available to programmatically interact with the Data Grid.

You can find the list of all the API methods on the [GridApi page](/x/api/data-grid/grid-api/).

:::warning
All the methods prefixed by `unstable_` are private.
We don't recommend using them as they can be removed, renamed, or reworked at any time.
If you need to use a private method, please open a GitHub issue describing your use case.
We will help you to achieve the same goal with public methods, or we will discuss making this specific method public.
All methods prefixed by `unstable_` are private and should not be used.
They may be removed, renamed, or reworked at any time.
If you need to use a private method, please [open a GitHub issue](https://github.com/mui/mui-x/issues/new/choose) describing your use case.
Our team will help you to achieve the same goal with public methods, or else discuss making this specific method public.
:::

## How to use the API object

The API object is accessible through the `apiRef` variable.
Depending on where you are trying to access this variable, you will have to use either `useGridApiContext` or `useGridApiRef`.
To access this variable, use `useGridApiContext` (inside the Data Grid) or `useGridApiRef` (outside the Data Grid).

### Use it inside the grid
### Inside the Data Grid

If you need to access the API object inside component slots or inside renders (e.g: `renderCell`, `renderHeader`),
you can use the `useGridApiContext` hook.
To access the API object inside component slots or inside renders (for instance, `renderCell` or `renderHeader`), use the `useGridApiContext` hook:

```tsx
function CustomFooter() {
Expand All @@ -34,15 +31,15 @@ function CustomFooter() {
```

:::info
You don't need to initialize the API object using `useGridApiRef` to be able to use it inside the grid components.
You don't need to initialize the API object using `useGridApiRef` to be able to use it inside the Data Grid components.
:::

{{"demo": "UseGridApiContext.js", "bg": "inline", "defaultCodeOpen": false}}

### Use it outside the grid [<span class="plan-pro"></span>](/x/introduction/licensing/#pro-plan)
### Outside the Data Grid [<span class="plan-pro"></span>](/x/introduction/licensing/#pro-plan)

When using the API object outside the grid components, you need to initialize it using the `useGridApiRef` hook.
You can then pass it to the `apiRef` prop of the grid.
You can then pass it to the Data Grid's `apiRef` prop:

```tsx
function CustomDataGrid(props) {
Expand All @@ -58,8 +55,8 @@ function CustomDataGrid(props) {
```

:::warning
The API object is populated by the various plugins of the grid during the first render of the component.
If you try to use it in the first render of the component, it will crash since all methods are not registered yet.
The API object is populated by the Data Grid's various plugins during the first render of the component.
If you try to use it in the first render of the component, it will crash because not all methods are registered yet.
:::

{{"demo": "UseGridApiRef.js", "bg": "inline", "defaultCodeOpen": false}}
Expand All @@ -68,11 +65,11 @@ If you try to use it in the first render of the component, it will crash since a

### Retrieve data from the state

You can find a detailed example in the [State page](/x/react-data-grid/state/#access-the-state).
You can find a detailed example on the [State page](/x/react-data-grid/state/#access-the-state).

### Listen to grid events

You can find a detailed example in the [Events page](/x/react-data-grid/events/#subscribing-to-events).
You can find a detailed example on the [Events page](/x/react-data-grid/events/#subscribing-to-events).

## API

Expand Down
24 changes: 10 additions & 14 deletions docs/data/data-grid/events/events.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,20 +1,16 @@
---
title: Data Grid - Events
---
# Data Grid - Events

# Data grid - Events

<p class="description">You can subscribe to the events emitted by the data grid to trigger custom behavior.</p>
<p class="description">Subscribe to the events emitted by the Data Grid to trigger custom behavior.</p>

## Subscribing to events

You can subscribe to one of the [events emitted](/x/react-data-grid/events/#catalog-of-events) by providing an event handler to the grid.
You can subscribe to one of the [events emitted](/x/react-data-grid/events/#catalog-of-events) by providing an event handler to the Data Grid.

The handler is a method that will be called with three arguments:
The handler is a method that's called with three arguments:

1. the parameters containing the information related to the event
2. the `MuiEvent` containing the DOM event or the React synthetic event, when available
3. the `GridCallbackDetails` containing the `GridApi`, only if `DataGridPro` or `DataGridPremium` is being used
3. the `GridCallbackDetails` containing the `GridApi`—only if `DataGridPro` or `DataGridPremium` is being used

For example, here is an event handler for the `rowClick` event:

Expand All @@ -28,7 +24,7 @@ const handleEvent: GridEventListener<'rowClick'> = (
};
```

You can provide this event handler to the grid in several ways:
You can provide this event handler to the Data Grid in several ways:

### With the prop of the event

Expand All @@ -52,7 +48,7 @@ useGridApiEventHandler('rowClick', handleEvent);
```

:::warning
This hook can only be used inside the scope of the grid (i.e. inside component slots or cell renderers).
This hook can only be used inside the scope of the Data Grid (i.e. inside component slots or cell renderers).
:::

The following demo shows how to subscribe to the `rowClick` event using `useGridApiEventHandler`—try it out by clicking on any row:
Expand All @@ -70,7 +66,7 @@ The following demo shows how to subscribe to the `rowClick` event using `apiRef.
{{"demo": "SubscribeToEventsApiRef.js", "bg": "inline", "defaultCodeOpen": false}}

:::warning
The `apiRef.current.subscribeEvent` method returns a cleaning callback that **unsubscribes** the given handler when called.
The `apiRef.current.subscribeEvent` method returns a cleaning callback that unsubscribes the given handler when called.
For instance, when used inside a `useEffect` hook, you should always return the cleaning callback.
Otherwise, you will have multiple registrations of the same event handler.
:::
Expand All @@ -89,8 +85,8 @@ Set it to `true` to block the default handling of an event and implement your ow
/>
```

Usually, double clicking a cell will put it into [edit mode](/x/react-data-grid/editing/).
The following example changes this behavior by also requiring <kbd class="key">Ctrl</kbd> to be pressed.
Usually, double-clicking a cell will put it into [edit mode](/x/react-data-grid/editing/).
The following example changes this behavior by also requiring the end user to press the <kbd class="key">Ctrl</kbd> key:

{{"demo": "DoubleClickWithCtrlToEdit.js", "bg": "inline"}}

Expand Down
55 changes: 28 additions & 27 deletions docs/data/data-grid/state/state.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,20 +1,17 @@
---
title: Data Grid - State
---
# Data Grid - State

# Data grid - State

<p class="description">Initialize and read the state of the data grid.</p>
<p class="description">Initialize and read the state of the Data Grid.</p>

## Initialize the state

Some state keys can be initialized with the `initialState` prop.
This prop has the same format as the returned value of `apiRef.current.exportState()`.

:::warning
The `initialState` can only be used to set the initial value of the state, the grid will not react if you change the `initialState` value later on.
The `initialState` can only be used to set the initial value of the state.
The Data Grid will not react if you change the `initialState` value later on.

If you need to fully control specific models, use the control props instead (e.g. `prop.filterModel` or `prop.sortModel`).
If you need to fully control specific models, use the control props instead (e.g. [`prop.filterModel`](/x/react-data-grid/filtering/#controlled-filters) or [`prop.sortModel`](https://mui.com/x/react-data-grid/sorting/#controlled-sort-model)).
You can find more information on the corresponding feature documentation page.
:::

Expand All @@ -23,22 +20,26 @@ You can find more information on the corresponding feature documentation page.
## Access the state [<span class="plan-pro"></span>](/x/introduction/licensing/#pro-plan)

The state is exposed on the `apiRef` object.
It is strongly advised not to access the state values directly because the state itself is not considered a public API and its structure can change.

:::warning
Do not access state values directly.
The state itself is not considered a public API and its structure can change.
:::

The `@mui/x-data-grid-pro` package exposes a set of state selectors that take the `apiRef.current.state` as an argument and return a value.
You can use them to get data from the state without worrying about its internal structure.

### Direct selector access

The simplest way to use a selector is to call it as a function with `apiRef` as its first argument.
The simplest way to use a selector is to call it as a function with `apiRef` as its first argument:

```tsx
const pageSize = gridPageSizeSelector(apiRef);
```

:::info
Calling with `apiRef.current.state` also works but it may cause side effects when multiple grid instances are in the same page.
If you still need to call it with the state, do not forget to pass the instance ID as the example:
Calling with `apiRef.current.state` also works, but may cause side effects when multiple Data Grid instances are present on a single page.
If you still need to call it with the state, don't forget to pass the instance ID as the example:

```tsx
const pageSize = gridPageSizeSelector(
Expand All @@ -51,37 +52,37 @@ const pageSize = gridPageSizeSelector(

{{"demo": "DirectSelector.js", "bg": "inline"}}

### With `useGridSelector`
### With useGridSelector

If you want to access sole state value in the render of your components, you can use the `useGridSelector` hook.
If you only need to access the state value in the render of your components, use the `useGridSelector` hook:

```tsx
const pageSize = useGridSelector(apiRef, gridPageSizeSelector);
```

:::warning
This hook can only be used inside the context of the grid, such as custom components.
Otherwise, you will have an error saying that the state is not initialized during the first render.
:::warning
This hook can only be used inside the context of the Data Grid, such as within custom components.
Otherwise, you will get an error saying that the state is not initialized during the first render.
:::

{{"demo": "UseGridSelector.js", "bg": "inline"}}

### Catalog of selectors

Some selectors are yet to be documented.
Some selectors have not yet been documented.

{{"demo": "SelectorsNoSnap.js", "bg": "inline", "hideToolbar": true}}

## Save and restore the state

The current state of the grid can be exported using `apiRef.current.exportState()`.
The current state of the Data Grid can be exported using `apiRef.current.exportState()`.
It can then be restored by either passing the returned value to the `initialState` prop or to the `apiRef.current.restoreState()` method.

Watch out for controlled models and their callbacks (`onFilterModelChange` if you use `filterModel`, for instance), as the grid will call those callbacks when restoring the state.
Watch out for controlled models and their callbacks (`onFilterModelChange` if you use `filterModel`, for instance), as the Data Grid calls those callbacks when restoring the state.
But if the callback is not defined or if calling it does not update the prop value, then the restored value will not be applied.

:::warning
To avoid breaking changes, the grid only saves the column visibility if you are using the [new api](/x/react-data-grid/column-visibility/#initialize-the-visible-columns)
To avoid breaking changes, the Data Grid only saves the column visibility if you are using the [newer API](/x/react-data-grid/column-visibility/#initialize-the-visible-columns)
flaviendelangle marked this conversation as resolved.
Show resolved Hide resolved
Make sure to initialize `props.initialState.columns.columnVisibilityModel` or to control `props.columnVisibilityModel`.

The easier way is to initialize the model with an empty object:
Expand All @@ -96,22 +97,22 @@ The easier way is to initialize the model with an empty object:

:::

### Restore the state with `initialState`
### Restore the state with initialState

You can pass the state returned by `apiRef.current.exportState()` to the `initialState` prop.
In the demo below, clicking on **Recreate the 2nd grid** will re-mount the 2nd grid with the current state of the 1st grid.
In the demo below, clicking on **Recreate the 2nd grid** will re-mount the second Data Grid with the current state of the first Grid.

:::warning
If you restore the page using `initialState` before the data is fetched, the grid will automatically move to the 1st page.
If you restore the page using `initialState` before the data is fetched, the Data Grid will automatically move to the first page.
:::

{{"demo": "RestoreStateInitialState.js", "bg": "inline", "defaultCodeOpen": false}}

### Restore the state with `apiRef` [<span class="plan-pro"></span>](/x/introduction/licensing/#pro-plan)
### Restore the state with apiRef [<span class="plan-pro"></span>](/x/introduction/licensing/#pro-plan)

You can pass the state returned by `apiRef.current.exportState()` to the `apiRef.current.restoreState` method.
In the demo below, clicking on **Save current view** will create a snapshot of the changes made in the state, considering the initial state.
You can apply these changes on the grid later selecting a saved view in the **Custom view** menu.
You can apply these changes on the Data Grid later selecting a saved view in the **Custom view** menu.

{{"demo": "RestoreStateApiRef.js", "bg": "inline", "defaultCodeOpen": false}}

Expand All @@ -129,7 +130,7 @@ apiRef.current.restoreState({
:::warning
Most of the state keys are not fully independent.

Restoring the pagination without restoring the filters or the sorting will work, but the rows displayed after the re-import will not be the same as before the export.
Restoring pagination without restoring filters or sorting will work, but the rows displayed after the re-import will not be the same as before the export.
:::

## API
Expand Down