Custom Fields

• Jul 26, 2023
• 3 minutes to read

You can define any number of mappings to data source fields that are not used by the Scheduler itself. The content of these fields is available via the PersistentObject.CustomFields property of the Appointment, Resource, and Label objects.

To bind a data field (“CustomField1”) to the appointment custom field (“MyNote”), use the following code:

C#

this.schedulerDataStorage1.Appointments.CustomFieldMappings.Add(new AppointmentCustomFieldMapping("MyNote", "CustomField1")); 

VB.NET

Me.schedulerDataStorage1.Appointments.CustomFieldMappings.Add(New AppointmentCustomFieldMapping("MyNote", "CustomField1"))

Important

Names of data fields mapped to the resource or appointment properties must be unique.

You can also use the Mappings Wizards to create custom field mappings.

To access “MyNote” data for the selected appointment, use the following code:

C#

object note = schedulerControl1.SelectedAppointments[0].CustomFields["MyNote"];

VB.NET

Dim note As Object = schedulerControl1.SelectedAppointments(0).CustomFields("MyNote")

Custom Field Mappings should not use names from the list of the standard object properties (for instance, “StartDate” for appointments) if the Scheduler operates in unbound mode. For example, the following mapping may result in incorrect appointment processing:

C#

AppointmentCustomFieldMapping customNameMapping = new AppointmentCustomFieldMapping("MyCustomIdField", "Id");
schedulerDataStorage.Appointments.CustomFieldMappings.Add(customNameMapping);

VB.NET

Dim customNameMapping As New AppointmentCustomFieldMapping("MyCustomIdField", "Id")
schedulerDataStorage.Appointments.CustomFieldMappings.Add(customNameMapping)

because “Id” is the name of the standard appointment property.

Create Appointments with Custom Fields

The code sample below illustrates how to create an appointment with a custom field and use this field in the SchedulerDataStorage.FilterAppointment event to hide appointments which meet certain criteria.

To define a custom field, create a new custom field mapping and add it to the collection of custom mappings using the CustomFieldMappingCollectionBase<T>.Add method. If the Scheduler is not bound to a data source, specify any non-empty string as the data field name.

Create an appointment using the SchedulerDataStorage.CreateAppointment method (so the newly created custom field mappings will be preserved for a new appointment). Set the value for the custom field and add the appointment to the SchedulerDataStorage.Appointments collection.

In the SchedulerDataStorage.FilterAppointment event handler, check the value of the custom field to set e.Cancel to true and hide this appointment.

AppointmentExamples.cs

    scheduler.Storage.Appointments.Clear();
    // Handle the FilterAppointment event to display appointments by some criteria.
    scheduler.Storage.FilterAppointment += Storage_FilterAppointment;
    scheduler.DayView.TopRowTime = TimeSpan.FromHours(DateTime.Now.Hour);

    // Add mapping to create a custom field. 
    // If Scheduler is bound to data, the string "DataFieldOne" should match the field name in the data source.
    // For unbound Scheduler, the data field name is required but not used.
    scheduler.Storage.Appointments.CustomFieldMappings.Add(new
       AppointmentCustomFieldMapping("PropertyOne", "DataFieldOne"));
    Appointment apt1 = scheduler.Storage.CreateAppointment(AppointmentType.Normal,
        DateTime.Now, new TimeSpan(1, 0, 0), "Visible Appointment");
    apt1.CustomFields["PropertyOne"] = "Visible";
    scheduler.Storage.Appointments.Add(apt1);
    Appointment apt2 = scheduler.Storage.CreateAppointment(AppointmentType.Normal,
        DateTime.Now.AddHours(2), new TimeSpan(0, 30, 0), "Hidden Appointment");
    apt2.CustomFields["PropertyOne"] = "Hidden";
    scheduler.Storage.Appointments.Add(apt2);
static void Storage_FilterAppointment(object sender, PersistentObjectCancelEventArgs e) {
    e.Cancel = ((Appointment)e.Object).CustomFields["PropertyOne"].ToString() == "Hidden";
}

AppointmentExamples.vb

    scheduler.Storage.Appointments.Clear()
    ' Handle the FilterAppointment event to display appointments by some criteria.
    AddHandler scheduler.Storage.FilterAppointment, AddressOf Storage_FilterAppointment
    scheduler.DayView.TopRowTime = TimeSpan.FromHours(Date.Now.Hour)

    ' Add mapping to create a custom field. 
    ' If Scheduler is bound to data, the string "DataFieldOne" should match the field name in the data source.
    ' For unbound Scheduler, the data field name is required but not used.
    scheduler.Storage.Appointments.CustomFieldMappings.Add(New AppointmentCustomFieldMapping("PropertyOne", "DataFieldOne"))
    Dim apt1 As Appointment = scheduler.Storage.CreateAppointment(AppointmentType.Normal, Date.Now, New TimeSpan(1, 0, 0), "Visible Appointment")
    apt1.CustomFields("PropertyOne") = "Visible"
    scheduler.Storage.Appointments.Add(apt1)
    Dim apt2 As Appointment = scheduler.Storage.CreateAppointment(AppointmentType.Normal, Date.Now.AddHours(2), New TimeSpan(0, 30, 0), "Hidden Appointment")
    apt2.CustomFields("PropertyOne") = "Hidden"
    scheduler.Storage.Appointments.Add(apt2)
Private Shared Sub Storage_FilterAppointment(ByVal sender As Object, ByVal e As PersistentObjectCancelEventArgs)
    e.Cancel = CType(e.Object, Appointment).CustomFields("PropertyOne").ToString() = "Hidden"
End Sub