Client-Side Functionality
- 3 minutes to read
Client-side API
ASPxScheduler, as well as other DevExpress ASP.NET controls, offer an advanced client-side API, in addition to the comprehensive server-side object model. This enables web applications based on DevExpress web controls to work more efficiently, using a combination of server-side and client-side processing.
The client-side API is implemented in the JavaScript file. This file is sent to the client browser when a web application that uses the web control is run. The filename is the same as the name of the control. The client API becomes available if the ASPxScheduler.ClientInstanceName property is specified or any client-side event is handled.
Do not confuse the properties and methods of server and client-side controls. Often they have identical or similar names, but this is not always the case. To identify a ASPxScheduler control in the server code, you should use the Name of this control. To get access to the ASPxClientScheduler using JavaScript, you should specify its ClientInstanceName.
Appointments on the client side are represented by the ASPxClientAppointment class objects. They differ from server-side appointments in IDs and in the set of properties available. Use the client-side method ASPxClientScheduler.GetAppointmentById to get the client-side appointment by its ID or the server-side method ASPxScheduler.LookupAppointmentByIdString to get the server-side appointment by its client ID.
Often, you’ll find it useful that client appointments always possess certain properties taken from the list of defined mappings, with values retrieved from the corresponding properties of the server-side appointments. The ASPxScheduler.InitClientAppointment event is helpful in this case. Handle this event to specify appointment properties available at the client side. This event fires for each visible appointment before it is sent to the client for display, so you can vary the properties and custom fields. You can also create a specific property to send arbitrary data to the client side.
When it is necessary to obtain server information on the client side, use the JavaScript Custom Properties mechanism. The ASPxScheduler.CustomJSProperties event enables you to declare temporary client properties to store the necessary information. Once declared, a property can be accessed on the client, using common syntax.
Note
Although the entire client API is available on the client side, it’s strongly recommended that only the documented public client-side API are used to realize any custom client functionality.
Client-Side Rendering
By default, for all end-user actions that do not require re-rendering of the Scheduler’s layout, the client Scheduler receives the required data in JSON and updates its view accordingly. The client-side rendering greatly reduces the amount of markup that should be produced on the server, which significantly improves a web application’s overall performance. The value of the ASPxScheduler.EnableClientRender property determines whether or not client-side rendering is used.
The following end-user actions trigger client-side rendering of appointments and view elements.
- Switching displayed dates.
- Switching displayed resources in a grouped view.
Keep in mind that certain customization scenarios require appointments and view elements to be rendered on the server-side. When such customizations are performed, client-side rendering of corresponding elements is automatically turned off, which can affect your web application’s performance.
Using the following customization scenarios automatically disables client-side rendering of view elements.
- Subscribing to the ASPxScheduler.CustomizeElementStyle event.
- Subscribing to the ASPxScheduler.HtmlTimeCellPrepared event.
- Using templates to customize view elements.
- Using templates to customize toolbar elements.
Using templates to customize the presentation of appointments disables client-side rendering of both appointments and views.