# Configure Event Data

## Content

Bind Scheduler to application data by mapping the fields in each source item to the event fields that Scheduler uses. The source collection remains the data source of record; rendered event elements are only visual representations of those items.

## Define the event data

Each event must provide a start and end date. A subject is also recommended so users can identify the event.

```ts
interface Appointment {
  title: string;
  beginsAt: Date;
  endsAt: Date;
  notes?: string;
  roomId?: string;
}

const appointments: Appointment[] = [
  {
    title: 'Project planning',
    beginsAt: new Date(2026, 7, 24, 9, 0),
    endsAt: new Date(2026, 7, 24, 10, 30),
    notes: 'Review milestones and ownership.',
    roomId: 'room-a',
  },
];
```

Scheduler keeps the original objects in `itemsSource`. It does not require the application to rename its existing fields.

## Map application fields

Use `eventFields` to associate Scheduler event fields with properties in the source data.

```ts
import * as wjScheduler from '@mescius/wijmo.scheduler';

const eventFields: wjScheduler.SchedulerEventFields = {
  subject: 'title',
  start: 'beginsAt',
  end: 'endsAt',
  description: 'notes',
};

const scheduler = new wjScheduler.FlexScheduler('#scheduler', {
  itemsSource: appointments,
  eventFields,
  displayDate: new Date(2026, 7, 24),
});
```

The values assigned in `eventFields` are source property names, not event values. For example, `subject: 'title'` tells Scheduler to read the event subject from `item.title`.

| Event field | Purpose | Requirement |
| ----------- | ------- | ----------- |
| `start` | Start date and time | Required |
| `end` | End date and time | Required |
| `subject` | Text displayed for the event | Recommended |
| `description` | Additional event or editor content | Optional |

These are the event fields most applications map. `subject` is not required for rendering, but applications should provide it so users can identify events. If it is empty, Scheduler uses the localized default title. See the API Reference for the complete `SchedulerEventFields` definition and additional editor fields.
`subject` is not required for rendering, but applications should provide it so users can identify events. If it is empty, Scheduler uses the localized default title. See the API Reference for details about `SchedulerEventFields`.

>type=note
> When the source data already uses the default event property names, explicit mappings are not necessary for those properties.

### Understand fields added by the editor

When an event is saved through the built-in editor, Scheduler writes the editor fields back to the source item. If an optional mapped property, such as the subject or description, was not present on the original object, saving can add that property to the object.
When `eventFields` maps an editor field to an application property, Scheduler writes to that mapped property. For example, with `subject: 'title'`, the saved subject is stored in `item.title`. Account for these fields when the application validates objects, serializes changes, or sends partial updates to a service.

## Use valid date ranges

Assign JavaScript `Date` objects to the mapped start and end fields. The end value must be later than the start value.

```ts
const event = {
  title: 'Design review',
  beginsAt: new Date(2026, 7, 24, 13, 0),
  endsAt: new Date(2026, 7, 24, 14, 0),
};
```

JavaScript month values are zero-based, so `7` represents August. When dates come from a server, convert serialized values before assigning the collection:

```ts
const appointments = response.items.map(item => ({
  ...item,
  beginsAt: new Date(item.beginsAt),
  endsAt: new Date(item.endsAt),
}));
```

Use one consistent time-zone strategy for the entire collection. Do not mix values interpreted as local time with values representing UTC instants unless the application converts them explicitly.

## Bind events that span dates

An event can cross a day boundary. Store it as one source item with one continuous date range:

```ts
const overnightMaintenance = {
  title: 'System maintenance',
  beginsAt: new Date(2026, 7, 24, 22, 0),
  endsAt: new Date(2026, 7, 25, 2, 0),
};
```

Depending on the active view, Scheduler may render the event as more than one fragment. These fragments still refer to the same source item. Do not split a multi-day event into separate records solely for display.

## Add resource values to event items

Resource assignments are ordinary properties on the event object. The resource descriptor's `fieldExpr` identifies the corresponding source property.

```ts
const event = {
  title: 'Customer workshop',
  beginsAt: new Date(2026, 7, 25, 9, 0),
  endsAt: new Date(2026, 7, 25, 12, 0),
  roomId: 'room-a',
};
```

The resource descriptor's `fieldExpr` must match `roomId`. Use a scalar value for a single-value resource and an array for a descriptor that enables multiple values. Each event value should match an entry in the configured resource data source. Configure the descriptor in [Configure Resources](/wijmo/docs/Topics/scheduler/configure-resources).

## Use a CollectionView

Bind a `CollectionView` when the application needs collection notifications, sorting, filtering, or tracked edits.

```ts
import * as wjCore from '@mescius/wijmo';

const events = new wjCore.CollectionView(appointments);

scheduler.itemsSource = events;
scheduler.eventFields = eventFields;
```

Use the bound collection to observe and manage changes made by the Scheduler. Application code should also add, edit, and remove source items through the collection instead of manipulating event elements in the DOM.

## Validate data before binding

Validate data returned by a service before assigning it to `itemsSource`. At minimum, check that:

* every item contains the properties referenced by the required mappings;
* start and end values are valid `Date` objects;
* the end value is later than the start value;
* resource values match their configured resource data sources.

The following example shows one application-level way to exclude invalid records before creating the `CollectionView`:

```ts
const validAppointments = appointments.filter(item =>
  item.beginsAt instanceof Date &&
  !Number.isNaN(item.beginsAt.getTime()) &&
  item.endsAt instanceof Date &&
  !Number.isNaN(item.endsAt.getTime()) &&
  item.endsAt > item.beginsAt
);

const events = new wjCore.CollectionView(validAppointments);
scheduler.itemsSource = events;
```

Perform the same validation for newly created or edited events. Business validation and server-side validation remain the application's responsibility.