Configure Event Data

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.

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.

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.

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.

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.

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:

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:

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.

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.

Use a CollectionView

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

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:

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.