diff --git a/docs/pages/components/data-grid/sorting.js b/docs/pages/components/data-grid/sorting.js new file mode 100644 index 0000000000000..a19f7b0da1f80 --- /dev/null +++ b/docs/pages/components/data-grid/sorting.js @@ -0,0 +1,28 @@ +import React from 'react'; +import MarkdownDocs from 'docs/src/modules/components/MarkdownDocs'; +import { prepareMarkdown } from 'docs/src/modules/utils/parseMarkdown'; + +const pageFilename = 'components/data-grid/sorting'; +const requireDemo = require.context( + 'docsx/src/pages/components/data-grid/sorting', + false, + /\.(js|tsx)$/, +); +const requireRaw = require.context( + '!raw-loader!../../../src/pages/components/data-grid/sorting', + false, + /\.(js|md|tsx)$/, +); + +// Run styled-components ref logic +// https://github.com/styled-components/styled-components/pull/2998 +requireDemo.keys().map(requireDemo); + +export default function Page({ demos, docs }) { + return ; +} + +Page.getInitialProps = () => { + const { demos, docs } = prepareMarkdown({ pageFilename, requireRaw }); + return { demos, docs }; +}; diff --git a/docs/src/pages.js b/docs/src/pages.js index 9cea732875ef7..a823c84b107aa 100644 --- a/docs/src/pages.js +++ b/docs/src/pages.js @@ -28,7 +28,8 @@ datagrid.children = { pathname: '/components/data-grid/getting-started' }, { pathname: '/components/data-grid/columns' }, { pathname: '/components/data-grid/rows' }, - { pathname: '/components/data-grid/filtering', title: 'Filtering' }, + { pathname: '/components/data-grid/sorting' }, + { pathname: '/components/data-grid/filtering' }, { pathname: '/components/data-grid/pagination' }, { pathname: '/components/data-grid/selection' }, { pathname: '/components/data-grid/editing', title: '🚧 Editing' }, @@ -46,7 +47,8 @@ datagrid.children = { pathname: '/components/data-grid/getting-started' }, { pathname: '/components/data-grid/columns' }, { pathname: '/components/data-grid/rows' }, - { pathname: '/components/data-grid/filtering', title: 'Filtering' }, + { pathname: '/components/data-grid/sorting' }, + { pathname: '/components/data-grid/filtering' }, { pathname: '/components/data-grid/pagination' }, { pathname: '/components/data-grid/selection' }, { pathname: '/components/data-grid/editing', title: '🚧 Editing' }, diff --git a/docs/src/pages/components/data-grid/rows/rows.md b/docs/src/pages/components/data-grid/rows/rows.md index 35df50db3c98b..3552ff2334053 100644 --- a/docs/src/pages/components/data-grid/rows/rows.md +++ b/docs/src/pages/components/data-grid/rows/rows.md @@ -37,85 +37,6 @@ The following demo updates the rows every 200ms. {{"demo": "pages/components/data-grid/rows/ApiRefRowsGrid.js", "bg": "inline"}} -## Row sorting - -### Basic sorting - -Single column sorting can be triggered with by clicking a column header. -Repeat this action to change the sorting direction. - -A sorted column can be can pre-configured using the `sortModel` prop of the `ColDef` interface: - -{{"demo": "pages/components/data-grid/rows/BasicSortingGrid.js", "bg": "inline"}} - -### Custom comparator - -The grid handles sorting and applies different comparators in columns according to their types. -The component handles sorting natively for the following types: - -- string -- number -- date -- dateTime - -To extend or modify this behavior in a specific column, you can pass in a custom comparator, and override the `sortComparator` prop of the `ColDef` interface. - -In the example below, the `username` column combines `name` and `age`, but it is sorted by `age` using a custom comparator: - -{{"demo": "pages/components/data-grid/rows/ComparatorSortingGrid.js", "bg": "inline"}} - -### Sort order - -By default, the sort order cycles between these three different modes: - -```jsx -const sortingOrder = ['asc', 'desc', null]; -``` - -In practice, when you click a column that is not sorted, it will sort ascending (`asc`). -The next click will make it sort descending (`desc`). Another click will remove the sort (`null`), reverting to the order that the data was provided in. -This behavior can be overwritten by setting the `sortingOrder` prop. - -In the example below columns are only sortable in descending or ascending order. - -{{"demo": "pages/components/data-grid/rows/OrderSortingGrid.js", "bg": "inline"}} - -### Disable sorting - -By default, all columns are sortable. -This can be revoked using the sortable prop of the `ColDef` interface: - -```tsx -const columns: ColDef = [{ field: 'name', sortable: false }]; -``` - -{{"demo": "pages/components/data-grid/rows/DisableSortingGrid.js", "bg": "inline"}} - -### Server-side sorting - -By default, sorting works client-side. -To switch it to server-side, set `sortingMode="server"`. -Then you need to handle the `onSortModelChange` callback, sort the rows on the server-side, and update the `rows` prop with the newly sorted rows. - -{{"demo": "pages/components/data-grid/rows/ServerSortingGrid.js", "bg": "inline"}} - -### Multi-column sorting [](https://material-ui.com/store/items/material-ui-x/) - -You can sort by multiple columns at the same time using `XGrid`. -Hold the CTRL key down while clicking the column header. - -{{"demo": "pages/components/data-grid/rows/MultiSortingGrid.js", "disableAd": true, "bg": "inline"}} - -### apiRef [](https://material-ui.com/store/items/material-ui-x/) - -The grid exposes a set of methods that enables all of these features using the imperative apiRef. - -> ⚠️ Only use this API when you have no alternative. Always start from the declarative API that the grid exposes. - -- `getSortModel`: Get the sort model currently applied to the grid. -- `setSortModel`: Set the sort model and trigger the sorting of rows. -- `onSortModelChange`: Callback fired when the column sorting changed before the grid has sorted its rows. - ## Row height By default, the rows have a height of 52 pixels. diff --git a/docs/src/pages/components/data-grid/rows/BasicSortingGrid.js b/docs/src/pages/components/data-grid/sorting/BasicSortingGrid.js similarity index 100% rename from docs/src/pages/components/data-grid/rows/BasicSortingGrid.js rename to docs/src/pages/components/data-grid/sorting/BasicSortingGrid.js diff --git a/docs/src/pages/components/data-grid/rows/BasicSortingGrid.tsx b/docs/src/pages/components/data-grid/sorting/BasicSortingGrid.tsx similarity index 100% rename from docs/src/pages/components/data-grid/rows/BasicSortingGrid.tsx rename to docs/src/pages/components/data-grid/sorting/BasicSortingGrid.tsx diff --git a/docs/src/pages/components/data-grid/rows/ComparatorSortingGrid.js b/docs/src/pages/components/data-grid/sorting/ComparatorSortingGrid.js similarity index 100% rename from docs/src/pages/components/data-grid/rows/ComparatorSortingGrid.js rename to docs/src/pages/components/data-grid/sorting/ComparatorSortingGrid.js diff --git a/docs/src/pages/components/data-grid/rows/ComparatorSortingGrid.tsx b/docs/src/pages/components/data-grid/sorting/ComparatorSortingGrid.tsx similarity index 100% rename from docs/src/pages/components/data-grid/rows/ComparatorSortingGrid.tsx rename to docs/src/pages/components/data-grid/sorting/ComparatorSortingGrid.tsx diff --git a/docs/src/pages/components/data-grid/rows/DisableSortingGrid.js b/docs/src/pages/components/data-grid/sorting/DisableSortingGrid.js similarity index 100% rename from docs/src/pages/components/data-grid/rows/DisableSortingGrid.js rename to docs/src/pages/components/data-grid/sorting/DisableSortingGrid.js diff --git a/docs/src/pages/components/data-grid/rows/DisableSortingGrid.tsx b/docs/src/pages/components/data-grid/sorting/DisableSortingGrid.tsx similarity index 100% rename from docs/src/pages/components/data-grid/rows/DisableSortingGrid.tsx rename to docs/src/pages/components/data-grid/sorting/DisableSortingGrid.tsx diff --git a/docs/src/pages/components/data-grid/rows/MultiSortingGrid.js b/docs/src/pages/components/data-grid/sorting/MultiSortingGrid.js similarity index 100% rename from docs/src/pages/components/data-grid/rows/MultiSortingGrid.js rename to docs/src/pages/components/data-grid/sorting/MultiSortingGrid.js diff --git a/docs/src/pages/components/data-grid/rows/MultiSortingGrid.tsx b/docs/src/pages/components/data-grid/sorting/MultiSortingGrid.tsx similarity index 100% rename from docs/src/pages/components/data-grid/rows/MultiSortingGrid.tsx rename to docs/src/pages/components/data-grid/sorting/MultiSortingGrid.tsx diff --git a/docs/src/pages/components/data-grid/rows/OrderSortingGrid.js b/docs/src/pages/components/data-grid/sorting/OrderSortingGrid.js similarity index 100% rename from docs/src/pages/components/data-grid/rows/OrderSortingGrid.js rename to docs/src/pages/components/data-grid/sorting/OrderSortingGrid.js diff --git a/docs/src/pages/components/data-grid/rows/OrderSortingGrid.tsx b/docs/src/pages/components/data-grid/sorting/OrderSortingGrid.tsx similarity index 100% rename from docs/src/pages/components/data-grid/rows/OrderSortingGrid.tsx rename to docs/src/pages/components/data-grid/sorting/OrderSortingGrid.tsx diff --git a/docs/src/pages/components/data-grid/rows/ServerSortingGrid.js b/docs/src/pages/components/data-grid/sorting/ServerSortingGrid.js similarity index 100% rename from docs/src/pages/components/data-grid/rows/ServerSortingGrid.js rename to docs/src/pages/components/data-grid/sorting/ServerSortingGrid.js diff --git a/docs/src/pages/components/data-grid/rows/ServerSortingGrid.tsx b/docs/src/pages/components/data-grid/sorting/ServerSortingGrid.tsx similarity index 100% rename from docs/src/pages/components/data-grid/rows/ServerSortingGrid.tsx rename to docs/src/pages/components/data-grid/sorting/ServerSortingGrid.tsx diff --git a/docs/src/pages/components/data-grid/sorting/sorting.md b/docs/src/pages/components/data-grid/sorting/sorting.md new file mode 100644 index 0000000000000..17c25c7f5fe36 --- /dev/null +++ b/docs/src/pages/components/data-grid/sorting/sorting.md @@ -0,0 +1,85 @@ +--- +title: Data Grid - Sorting +components: DataGrid, XGrid +--- + +# Data Grid - Sorting + +

Sorting allows ordering records in the data grid.

+ +## Basic sorting + +Single column sorting can be triggered with by clicking a column header. +Repeat this action to change the sorting direction. + +A sorted column can be can pre-configured using the `sortModel` prop of the `ColDef` interface: + +{{"demo": "pages/components/data-grid/sorting/BasicSortingGrid.js", "bg": "inline"}} + +## Custom comparator + +The grid handles sorting and applies different comparators in columns according to their types. +The component handles sorting natively for the following types: + +- string +- number +- date +- dateTime + +To extend or modify this behavior in a specific column, you can pass in a custom comparator, and override the `sortComparator` prop of the `ColDef` interface. + +In the example below, the `username` column combines `name` and `age`, but it is sorted by `age` using a custom comparator: + +{{"demo": "pages/components/data-grid/sorting/ComparatorSortingGrid.js", "bg": "inline"}} + +## Sort order + +By default, the sort order cycles between these three different modes: + +```jsx +const sortingOrder = ['asc', 'desc', null]; +``` + +In practice, when you click a column that is not sorted, it will sort ascending (`asc`). +The next click will make it sort descending (`desc`). Another click will remove the sort (`null`), reverting to the order that the data was provided in. +This behavior can be overwritten by setting the `sortingOrder` prop. + +In the example below columns are only sortable in descending or ascending order. + +{{"demo": "pages/components/data-grid/sorting/OrderSortingGrid.js", "bg": "inline"}} + +## Disable sorting + +By default, all columns are sortable. +This can be revoked using the sortable prop of the `ColDef` interface: + +```tsx +const columns: ColDef = [{ field: 'name', sortable: false }]; +``` + +{{"demo": "pages/components/data-grid/sorting/DisableSortingGrid.js", "bg": "inline"}} + +## Server-side sorting + +By default, sorting works client-side. +To switch it to server-side, set `sortingMode="server"`. +Then you need to handle the `onSortModelChange` callback, sort the rows on the server-side, and update the `rows` prop with the newly sorted rows. + +{{"demo": "pages/components/data-grid/sorting/ServerSortingGrid.js", "bg": "inline"}} + +## Multi-column sorting [](https://material-ui.com/store/items/material-ui-x/) + +You can sort by multiple columns at the same time using `XGrid`. +Hold the CTRL key down while clicking the column header. + +{{"demo": "pages/components/data-grid/sorting/MultiSortingGrid.js", "disableAd": true, "bg": "inline"}} + +## apiRef [](https://material-ui.com/store/items/material-ui-x/) + +The grid exposes a set of methods that enables all of these features using the imperative apiRef. + +> ⚠️ Only use this API when you have no alternative. Always start from the declarative API that the grid exposes. + +- `getSortModel`: Get the sort model currently applied to the grid. +- `setSortModel`: Set the sort model and trigger the sorting of rows. +- `onSortModelChange`: Callback fired when the column sorting changed before the grid has sorted its rows.