diff --git a/docs/Reference.md b/docs/Reference.md index 257c9460c1f..59d181b9cd4 100644 --- a/docs/Reference.md +++ b/docs/Reference.md @@ -174,6 +174,7 @@ title: "Index" * [``](./SaveButton.md) * [``](./SavedQueriesList.md) +* [``](./Scheduler.md)React Admin Enterprise Edition icon * [``](./Search.md)React Admin Enterprise Edition icon * [``](./SearchInput.md) * [``](./SearchWithResult.md)React Admin Enterprise Edition icon diff --git a/docs/Scheduler.md b/docs/Scheduler.md new file mode 100644 index 00000000000..63f96a2eda9 --- /dev/null +++ b/docs/Scheduler.md @@ -0,0 +1,531 @@ +--- +layout: default +title: "The Scheduler Component" +--- + +# `` + +This [Enterprise Edition](https://react-admin-ee.marmelab.com)React Admin Enterprise Edition icon component, part of [`ra-scheduler`](https://react-admin-ee.marmelab.com/documentation/ra-search), is a full-featured scheduler for managing tasks, assignments, events, scheduling constraints and dependencies, completion, recurring events, property booking, skill matrix, nested events, etc. + + + +It supports drag and drop, infinite scroll, zoom, custom layout and styling, collapsible columns, localization, grouping and filtering and export to pdf. + +This packages integrates react-admin with [Bryntum Scheduler](https://bryntum.com/products/scheduler/), a modern and high-performance scheduling UI component. As it leverages react-admin's data provider, it is backend agnostic. + +Test it live in the [Enterprise Edition Storybook](https://react-admin.github.io/ra-enterprise/?path=/story/ra-scheduler). + +## Usage + +`` is an all-in one component. Use it as the `list` prop of a react-admin [``](https://marmelab.com/react-admin/Resource.html): + +{% raw %} +```tsx +// in ./src/App.tsx +import { Admin, Resource } from 'react-admin'; +import { dataProvider } from './dataProvider'; +import { EventList } from './events/EventList'; + +export const MyAdmin = () => ( + + + +); + +// in ./src/events/EventList.tsx +import { Scheduler } from '@react-admin/ra-scheduler'; +import '@bryntum/core-thin/core.material.css'; +import '@bryntum/grid-thin/grid.material.css'; +import '@bryntum/scheduler-thin/scheduler.material.css'; +import { endOfDay, startOfDay } from 'date-fns'; + +export const EventList = () => ( + +); +``` +{% endraw %} + +`` renders a [Bryntum Scheduler](https://bryntum.com/products/scheduler/) and integrates it with the `dataProvider` and [`@react-admin/ra-form-layout` dialogs](https://react-admin-ee.marmelab.com/documentation/ra-form-layout#createdialog-editdialog--showdialog). + +It uses all the available horizontal and vertical space in the layout's content section. + +## Props + +In addition to the props accepted by [Bryntum Scheduler](https://www.bryntum.com/products/scheduler/docs/guide/Scheduler/quick-start/react/), `` accepts the following props: + +| Prop | Required | Type | Default | Description | +| ------------------- | -------- | --------- | ----------- | ----------------------------------------------------------------------------------------------------------------------- | +| `actions` | Optional | ReactNode | | A component displayed on top of the scheduler, usually to display a toolbar with action buttons | +| `converters` | Optional | object | | An object containing converters from dataProvider records to Bryntum models and vice-versa | +| `CreateDialogProps` | Optional | object | | Props to pass to the `` used to create new events | +| `EditDialogProps` | Optional | object | | Props to pass to the `` used to edit existing events | +| `eventCreate` | Optional | ReactNode | | The form used to create new events | +| `eventEdit` | Optional | ReactNode | | The form used to edit existing events | +| `eventName` | Optional | string | | The name of the resource for _Events_ | +| `mutationOptions` | Optional | object | | The mutation options sent when updating _Events_ via drag/drop or resize and _Resources_ via the inline editor | +| `resourcesName` | Optional | string | 'resources' | The name of the resource for _Resources_ | +| `queryOptions` | Optional | object | | The query options sent when fetching _Events_ and _Resources_ | +| `sx` | Optional | object | | The sx prop passed down to the wrapping `
` element | +| `title` | Optional | object | | The title to display in the `` | + +## `actions` + +A component displayed on top of the scheduler, usually to display a toolbar with action buttons. By default, it renders a toolbar with navigation buttons to go to the previous or next day. +You can provide your own actions by passing a component to the `actions` prop, for instance to use the provided navigation buttons for week or month navigation: + +{% raw %} +```tsx +// in ./src/events/EventList.tsx +import { Scheduler, SchedulerWeeksNavigationButtons } from '@react-admin/ra-scheduler'; +import '@bryntum/core-thin/core.material.css'; +import '@bryntum/grid-thin/grid.material.css'; +import '@bryntum/scheduler-thin/scheduler.material.css'; +import { startOfWeek } from 'date-fns'; + +const EventListActions = () => ( + + + +); + +export const EventList = () => ( + } + /> +); +``` +{% endraw %} + +## `converters` + +An object that contains function converting dataProvider records to Bryntum models and vice-versa: + +{% raw %} +```tsx +// in ./src/events/EventList.tsx +import { Scheduler } from '@react-admin/ra-scheduler'; +import '@bryntum/core-thin/core.material.css'; +import '@bryntum/grid-thin/grid.material.css'; +import '@bryntum/scheduler-thin/scheduler.material.css'; +import { startOfDay } from 'date-fns'; + +export const EventList = () => ( + ({ + id: record.id, + name: record.name, + resourceId: record.resource_id, + eventColor: record.color, + startDate: new Date(record.start_at), + endDate: new Date(record.end_at), + }); + toBryntumResource?: (record: RaRecord) => ({ + id: record.id, + name: record.name, + }), + toEvent?: (model: EventModel) => ({ + id: model.id, + name: model.name, + resource_id: model.resourceId, + start_at: model.startDate, + end_at: model.endDate, + color: record.eventColor, + }), + toResource?: (model: ResourceModel) => ({ + id: model.id, + name: model.name, + }), + }} + /> +); +``` +{% endraw %} + +## `CreateDialogProps` + +The props to pass to the [``](https://react-admin-ee.marmelab.com/documentation/ra-form-layout#createdialog-editdialog--showdialog) used to create new events: + +{% raw %} +```tsx +// in ./src/events/EventList.tsx +import { Scheduler } from '@react-admin/ra-scheduler'; +import '@bryntum/core-thin/core.material.css'; +import '@bryntum/grid-thin/grid.material.css'; +import '@bryntum/scheduler-thin/scheduler.material.css'; +import { startOfDay } from 'date-fns'; + +export const EventList = () => { + return ( + + ); +}; +``` +{% endraw %} + +## `EditDialogProps` + +The props to pass to the [``](https://react-admin-ee.marmelab.com/documentation/ra-form-layout#createdialog-editdialog--showdialog) used to create new events: + +{% raw %} +```tsx +// in ./src/events/EventList.tsx +import { Scheduler } from '@react-admin/ra-scheduler'; +import '@bryntum/core-thin/core.material.css'; +import '@bryntum/grid-thin/grid.material.css'; +import '@bryntum/scheduler-thin/scheduler.material.css'; +import { startOfDay } from 'date-fns'; + +export const EventList = () => { + return ( + + }} + /> + ); +}; + +const EventEditTitle = () => { + const record = useRecordContext(); + return record ? Edit {record?.name} : null; +}; +``` +{% endraw %} + +## `eventCreate` + +`` includes a default form for events creation and edition with the basic fields. You can provide a custom form component to create new events with the `eventCreate` prop: + +{% raw %} +```tsx +// in ./src/events/EventList.tsx +import { Scheduler } from '@react-admin/ra-scheduler'; +import '@bryntum/core-thin/core.material.css'; +import '@bryntum/grid-thin/grid.material.css'; +import '@bryntum/scheduler-thin/scheduler.material.css'; +import { startOfDay } from 'date-fns'; +import { + AutocompleteInput, + DateTimeInput, + ReferenceInput, + required, + SelectInput, + SimpleForm, + TextInput +} from 'react-admin'; + +export const EventList = () => ( + } + /> +); + +const CustomEventForm = () => ( + + + + + + + + + +); + +const colors = ['red', 'blue', 'green', 'yellow', 'purple']; +``` +{% endraw %} + +## `eventEdit` + +`` includes a default form for events creation and edition with the basic fields. You can provide a custom form component to edit existing events with the `eventEdit` prop: + +{% raw %} +```tsx +// in ./src/events/EventList.tsx +import { Scheduler } from '@react-admin/ra-scheduler'; +import '@bryntum/core-thin/core.material.css'; +import '@bryntum/grid-thin/grid.material.css'; +import '@bryntum/scheduler-thin/scheduler.material.css'; +import { startOfDay } from 'date-fns'; +import { + AutocompleteInput, + DateTimeInput, + ReferenceInput, + required, + SelectInput, + SimpleForm, + TextInput +} from 'react-admin'; + +export const EventList = () => ( + } + /> +); + +const CustomEventForm = () => ( + + + + + + + + + +); + +const colors = ['red', 'blue', 'green', 'yellow', 'purple']; +``` +{% endraw %} + + +## `mutationOptions` + +[Bryntum Scheduler](https://bryntum.com/products/scheduler/) allows users to modify events by resizing or drag/dropping them and resources by double clicking them. If you need to pass additional data for those updates, use the `mutationOptions` prop: + +{% raw %} +```tsx +// in ./src/events/EventList.tsx +import { Scheduler } from '@react-admin/ra-scheduler'; +import '@bryntum/core-thin/core.material.css'; +import '@bryntum/grid-thin/grid.material.css'; +import '@bryntum/scheduler-thin/scheduler.material.css'; +import { startOfDay } from 'date-fns'; + +export const EventList = () => ( + +); +``` +{% endraw %} + +## `resources` + +By default, `` uses: +- the resource from the current `ResourceContext` or "events" if no `ResourceContext` is available (for instance in a dashboard) as the default resource name for the scheduler _Events_ +- "resources" as the default resource name for the scheduler _Resources_ + +If you want to use another name, set the `resources` prop: + +{% raw %} +```tsx +// in ./src/events/EventList.tsx +import { Scheduler } from '@react-admin/ra-scheduler'; +import '@bryntum/core-thin/core.material.css'; +import '@bryntum/grid-thin/grid.material.css'; +import '@bryntum/scheduler-thin/scheduler.material.css'; +import { startOfDay } from 'date-fns'; + +export const EventList = () => ( + +); +``` +{% endraw %} + +## `queryOptions` + +The query options when fetching _Events_ or _Resources_: + +{% raw %} +```tsx +// in ./src/events/EventList.tsx +import { Scheduler } from '@react-admin/ra-scheduler'; +import '@bryntum/core-thin/core.material.css'; +import '@bryntum/grid-thin/grid.material.css'; +import '@bryntum/scheduler-thin/scheduler.material.css'; +import { startOfDay } from 'date-fns'; + +export const EventList = () => ( + +); +``` +{% endraw %} + +## `sx` + +The `sx` prop passed down to the wrapping `
` element: + +{% raw %} +```tsx +// in ./src/events/EventList.tsx +import { Scheduler } from '@react-admin/ra-scheduler'; +import '@bryntum/core-thin/core.material.css'; +import '@bryntum/grid-thin/grid.material.css'; +import '@bryntum/scheduler-thin/scheduler.material.css'; +import { startOfDay } from 'date-fns'; + +export const EventList = () => ( + +); +``` +{% endraw %} + +## `title` + +The title to display in the ``: + +{% raw %} +```tsx +// in ./src/events/EventList.tsx +import { Scheduler } from '@react-admin/ra-scheduler'; +import '@bryntum/core-thin/core.material.css'; +import '@bryntum/grid-thin/grid.material.css'; +import '@bryntum/scheduler-thin/scheduler.material.css'; +import { startOfDay } from 'date-fns'; + +export const EventList = () => ( + +); +``` +{% endraw %} + +## `` + +A component that displays navigation buttons to move through days in a `` that displays data day by day. + +{% raw %} +```tsx +// in ./src/events/EventList.tsx +import { Scheduler, SchedulerDaysNavigationButtons } from '@react-admin/ra-scheduler'; +import '@bryntum/core-thin/core.material.css'; +import '@bryntum/grid-thin/grid.material.css'; +import '@bryntum/scheduler-thin/scheduler.material.css'; +import { startOfDay } from 'date-fns'; + +const EventListActions = () => ( + + + +); + +export const EventList = () => ( + } + /> +); +``` +{% endraw %} + +## `` + +A component that displays navigation buttons to move through weeks in a `` that displays data week by week. + +{% raw %} +```tsx +// in ./src/events/EventList.tsx +import { Scheduler, SchedulerWeeksNavigationButtons } from '@react-admin/ra-scheduler'; +import '@bryntum/core-thin/core.material.css'; +import '@bryntum/grid-thin/grid.material.css'; +import '@bryntum/scheduler-thin/scheduler.material.css'; +import { startOfWeek } from 'date-fns'; + +const EventListActions = () => ( + + + +); + +export const EventList = () => ( + } + /> +); +``` +{% endraw %} + +## `` + +A component that displays navigation buttons to move through months in a `` that displays data month by month. + +{% raw %} +```tsx +// in ./src/events/EventList.tsx +import { Scheduler, SchedulerMonthsNavigationButtons } from '@react-admin/ra-scheduler'; +import '@bryntum/core-thin/core.material.css'; +import '@bryntum/grid-thin/grid.material.css'; +import '@bryntum/scheduler-thin/scheduler.material.css'; +import { startOfMonth } from 'date-fns'; + +const EventListActions = () => ( + + + +); + +export const EventList = () => ( + } + /> +); +``` +{% endraw %} diff --git a/docs/navigation.html b/docs/navigation.html index ef1c887f5d0..0bff2e6b209 100644 --- a/docs/navigation.html +++ b/docs/navigation.html @@ -96,6 +96,7 @@
  • <SingleFieldList>
  • <EditableDatagrid>
  • <Calendar>
    • +
  • <Scheduler>
  • <FilterButton>
  • <FilterList>
  • <FilterLiveForm>