[Expand]General Information
[Expand]WinForms Controls
[Collapse]ASP.NET Controls and MVC Extensions
 [Expand]What's Installed
 [Expand]Common Concepts
 [Collapse]ASP.NET WebForms Controls
   Getting Started
  [Expand]Grid View
  [Expand]Tree List
  [Expand]Card View
  [Expand]Chart Control
  [Expand]Pivot Grid
  [Expand]Rich Text Editor
   [Expand]Product Information
    Getting Started
   [Expand]Scheduler Elements
   [Expand]Visual Elements
   [Expand]Design-Time Features
    [Expand]Data Binding
     [Collapse]Custom Forms and Custom Fields
       How to: Customize Appointment Appearance via Templates
       How to: Customize a Form Using Templates
       How to: Customize the Appointment Editing Form for Working with Custom Fields
       How to: Customize the Appointment Dialog using View Model API (simple customization)
       How to: Customize the Appointment Dialog using View Model API (working with custom fields)
    [Expand]Printing and Reporting
   [Expand]End-User Capabilities
   [Expand]Member Tables
  [Expand]Site Navigation and Layout
  [Expand]HTML Editor
  [Expand]Vertical Grid
  [Expand]Data Editors
  [Expand]Docking and Popups
  [Expand]File Management
  [Expand]Data and Image Navigation
  [Expand]Multi-Use Site Controls
  [Expand]Spell Checker
  [Expand]Query Builder
 [Expand]ASP.NET MVC Extensions
 [Expand]Redistribution and Deployment
  Get More Help
 [Expand]API Reference
[Expand]ASP.NET Bootstrap Controls
[Expand]ASP.NET Core Bootstrap Controls
[Expand]WPF Controls
[Expand]Xamarin Controls
[Expand]Windows 10 App Controls
[Expand]Office File API
[Expand]Report and Dashboard Server
[Expand]eXpressApp Framework
[Expand]eXpress Persistent Objects
[Expand]CodeRush Classic
[Expand]Cross-Platform Core Libraries
[Expand]Tools and Utilities
 End-User Documentation
View this topic on docs.devexpress.com (Learn more)

How to: Customize the Appointment Editing Form for Working with Custom Fields

This document provides a step-by-step tutorial for simple appointment form customization. You'll learn how to replace a text box used for editing an appointment's subject with a combo box and add an additional text box for editing an appointment's custom field.

To follow this tutorial, start with a sample project in which the ASPxScheduler control is bound to a collection of custom objects: How to: Bind ASPxScheduler Appointment to ObjectDataSource.

Show Me

A complete sample project is available in the DevExpress Code Examples database at http://www.devexpress.com/example=E2924.

Follow the steps below to customize the appointment edit form.

Expanded Step 1 - Update Data Source

Add a new field named "CustomInfo" to your data source. The CustomInfo field will contain text, thus, depending on your database and data provider, it could be of the string:NVARCHAR(MAX) type or one similar to it. Modify your select/insert/update queries to include those fields.

Expanded Step 2 – Specify Custom Field Mappings

Add custom field mapping for the previously created CustomInfo field. You can do this in the Visual Studio Designer, in the markup or using the property grid (ASPxScheduler control ->Storage->Appointments->CustomFieldMappings).

Depending on your requirements, you may need to add mappings at runtime instead. In this case, use the following code in the code-behind file for the page containing the ASPxScheduler control (Default.aspx.cs or Default.aspx.vb if you use Visual Basic.

Expanded Step 3 – Prepare a Custom Appointment Editing Form

Create a new folder named "CustomForms". Copy default ASPxScheduler forms and templates to your project site using the ASPxScheduler control's Smart Tag, as described in the Dialog Forms article. Locate the AppointmentForm.ascx form and the corresponding code-behind file AppointmentForm.ascx.cs (or AppointmentForm.ascx.vb if you use Visual Basic) and copy them to the newly created CustomForms folder.

Expanded Step 4 – Register the Custom Form

After copying default ASPxScheduler forms and templates into your project, the corresponding paths will be automatically registered using the OptionsForms and OptionsToolTips properties. Change the ASPxSchedulerOptionsForms.AppointmentFormTemplateUrl property value to the value corresponding to the new location of the form's template - ~/CustomForms/AppointmentForm.ascx. You can clear the other paths or keep them for further customization of default templates.

Expanded Step 5 - Add Custom Editors

In the form's markup, replace the predefined text box used for editing an appointment's subject with a combo box and add an additional text box for editing the CustomInfo field.


Note that the AssociatedControlID property of the lblSubject label points to the tbSubject text box, which has been removed from the form. This may cause unwanted re-creation of the form's controls hierarchy. As a result, the form editors will return empty values when you save an appointment. To prevent incorrect behavior, remove this property or change its value to the cbSubject combo box ID.

After you add custom editors to the form, you have to register them. Add IDs of the newly added editors to the array returned by the form's GetChildEditors method. This step ensures that the editors will be accessible by client-side scripts. After that, the method will look as follows.

Expanded Step 6 – Bind the Custom Editors to Data

In the DataBind method of the Edit Appointment form, you can provide values for the new editors based on the properties of the currently edited appointment. Since you use a combo box for editing an appointment's subject, you need to assign a corresponding data source to this combo box as shown below.

Expanded Step 7 – Save Editor Values

To save values of the new editors as corresponding appointment properties, override the default AppointmentFormSaveCallbackCommand. Create this command's descendant in the CustomForms folder or in the App_Code folder (for websites).

In the overridden AssignControllerValues method, assign the values of the new editors to the corresponding properties of the AppointmentFormController. Note that your custom code should be placed after you execute the base implementation of the AssignControllerValues method. Otherwise, changes made to standard appointment fields (for example, the Controller.Subject field) will be reset with the base implementation.

Make a note that the default FindControlByID method searches the editor located in the AppointmentFormTemplateContainer's controls collection without taking into account the complex hierarchy of the controls with multiple nesting levels. It is recommended that you also override this method as shown below.

Expanded Step 8 – Create a Custom Appointment Form Controller

In the previous step, the tbCustomInfo editor value is saved as an appointment's custom field using the Controller.CustomInfoField property. The default AppointmentFormController class does not contain such a property so you need to manually implement this property in a custom AppointmentFormController class descendant.

The code sample below demonstrates the implementation of a custom appointment form controller.

Expanded Step 9 – Execute the Custom Save Command

Your newly created CustomAppointmentSaveCallbackCommand should be executed instead of the default save command whenever a user issues the Save command. To accomplish this, handle the ASPxScheduler.BeforeExecuteCallbackCommand event as illustrated below.

Expanded Step 10 – Get the Result

Run the project. Check to see whether or not your custom form is shown when you open an appointment for editing. Fill in the custom fields and see whether or not new values can be saved when clicking OK, and then restored with the next opening of the form.

Expanded See Also

Is this topic helpful?​​​​​​​