Callback Commands
- 6 minutes to read
The Scheduler callback command is the basic object which provides interaction between a Web client instance of the ASPxScheduler and its server part. When a specific task should be accomplished, the client control performs a callback to the server. A command, which forms the essential part of the callback, is then executed on the server and in the final stage of a callback, the client control is updated.
SchedulerCallbackCommand Class
There are numerous classes implemented to represent commands which serve to accomplish different tasks. They all have a common ancestor - the SchedulerCallbackCommand abstract class. It defines the following essential properties and methods:
- string Id property - gets or sets a string which uniquely identifies a command.
- bool RequiresControlHierarchy property - set it to true if a call to EnsureChildControls() method is required to ask the engine to populate the controls collection first before processing.
- void Execute(string parameters) method - executes a command. It processes the parameter information via the call to ParseParameters method, then checks the result of CanContinueExecute method, and if it is true, calls the ExecuteCore method. The FinalizeExecute method completes the execution. All mentioned methods are defined as virtual, so you can override them when necessary in command class descendants.
Usage
In JavaScript, you should use the control.RaiseCallback() method to invoke a callback command. The method’s argument specifies the command and passed parameters. It is a DevExpress.Web.ASPxScheduler.Internal.CallbackCommandInfo object which is represented by a string in the following format :
<command identifier><VERTICAL LINE><comma delimited parameters>
Refer to the following table which lists generally used commands, their identifiers and parameters:
| Description | Id | Identifier | Parameters |
|---|---|---|---|
| Switch the View | SchedulerCallbackCommandId.SwitchView | SAVT | SchedulerViewType |
| Switch the group type | SchedulerCallbackCommandId.SwitchGroupType | SVGT | SchedulerGroupType |
| Show appointment editing form for the appointment with the specified client id | SchedulerCallbackCommandId.AppointmentFormShow | EDTFRMSHOW | Appointment client identifier (ASPxClientScheduler.GetSelectedAppointmentIds) |
| Show appointment editing form for the appointment with the specified server id | SchedulerCallbackCommandId.ShowAppointmentFormByServerId | EDTFRMSHOWSID | Appointment identifier (ASPxSchedulerStorage.GetAppointmentId) |
| Save the appointment edited in the appointment editing form | SchedulerCallbackCommandId.AppointmentSave | APTSAVE | - |
| Close the appointment editing form | SchedulerCallbackCommandId.AppointmentCancel | APTCANCEL | - |
| Delete the appointment edited in the appointment editing form | SchedulerCallbackCommandId.AppointmentDelete | APTDEL | - |
| Invoke the inplace editor for the currently selected appointment | SchedulerCallbackCommandId.InplaceEditorShow | INPLACESHOW | - |
| Save the appointment edited via the inplace editing form | SchedulerCallbackCommandId.InplaceEditorSave | INPLACESAVE | - |
| Invoke the appointment editing form for the appointment currently edited via the inplace editing form | SchedulerCallbackCommandId.InplaceEditorEditForm | INPLACEFORM | - |
| Invoke the GotoDate form | SchedulerCallbackCommandId.GotoDateForm | GOTODATEFORM | - |
| Set the ASPxScheduler.Start property of the control to the specified datetime | SchedulerCallbackCommandId.GotoDate | GOTODATE | The number of seconds since 01/01/1970 |
| Set the ASPxScheduler.Start property of the control to the current client date | SchedulerCallbackCommandId.GotoToday | GOTODAY | - |
| Set the ASPxScheduler client time zone | SchedulerCallbackCommandId.ChangeTimeZone | TZI | A string, the time zone identifier which is valid for the System.TimeZoneInfo.Id property. |
| Perform an empty callback to reload a page | SchedulerCallbackCommandId.Refresh | REFRESH | - |
| Retrieves the specified appointment properties | SchedulerCallbackCommandId.AppointmentData | APTDATA | The client appointment id and a list of appointment properties to retrieve. |
| Updates selected appointment property values | SchedulerCallbackCommandId.ClientSideUpdateAppointment | UPDTAPT | A list of property-value pairs. |
| Inserts an appointment into a storage collection | SchedulerCallbackCommandId.ClientSideInsertAppointment | INSRTAPT | A list of property-value pairs for the new appointment. |
| Deletes the selected appointment | SchedulerCallbackCommandId.ClientSideDeleteAppointment | DLTAPT | - |
| Performs a callback to retrieve appointment properties and, after that, executes a specified procedure | SchedulerCallbackCommandId.AppointmentDataEx | APTDATAEX | A refresh action id, the client appointment id and a list of properties to retrieve. |
When customizing the appointment editing form, you can insert your own JavaScript to perform specific tasks. The following code snippet illustrates the use of a client’s button click event to display a custom message, save appointment information and close the form.
Note
Use dxss_ prefix to include your custom script located in a web template into the resulting page.
<dxe:ASPxButton runat="server" ID="btnOk" Text="OK"
UseSubmitBehavior="False" AutoPostBack="False"
EnableViewState="False" Width="91px" >
<ClientSideEvents Click="function(s, e) {Thanks(s, e);}" />
</dxe:ASPxButton>
<script id="dxss_scriptMyAppointmentForm" type="text/javascript">
function Thanks(s, e){
alert('Thanks for saving!');
scheduler.RaiseCallback('APTSAVE|');
scheduler.RaiseCallback('APTCANCEL|');
}
</script>
Menu
A callback command may originate from a popup menu invoked from the scheduler’s View area or an appointment’s area. The menu to which a command belongs is indicated by a special prefix - “MNUVIEW“ or “MNUAPT“ respectively. This prefix is appended before the command identifier. You can send callback commands corresponding to menu items by specifying a proper prefix and a command’s name, equal to the SchedulerMenuItemId member.
To show a new appointment form, you can call the clientScheduler.RaiseCallback(“MNUVIEW|NewAppointment”)method. In order to edit an existing appointment, use the clientScheduler.RaiseCallback(“MNUAPT|OpenAppointment”) method.
When implementing your own menu commands, you should inherit them from the MenuAppointmentCallbackCommand base class instead of the SchedulerCallbackCommand class, as illustrated in the following code snippet:
// CustomMenuAppointmentCallbackCommand
public class CustomMenuAppointmentCallbackCommand : MenuAppointmentCallbackCommand {
string menuItemId = String.Empty;
public CustomMenuAppointmentCallbackCommand(ASPxScheduler control) : base(control) { }
public override string Id { get { return "USRAPTMENU"; } }
public string MenuItemId { get { return menuItemId; } }
protected override void ParseParameters(string parameters) {
this.menuItemId = parameters;
base.ParseParameters(parameters);
}
protected override void ExecuteCore() {
Appointment apt = Control.SelectedAppointments[0];
if (MenuItemId == "DeleteAppointment") {
apt.Delete();
return;
}
else if (MenuItemId == "BringMeCoffee") {
// TODO: Add Code here
return;
}
base.ExecuteCore();
}
}
Callback Interception
Use the ASPxScheduler.BeforeExecuteCallbackCommand event to intercept a callback command. You can then analyze the SchedulerCallbackCommandEventArgs.CommandId parameter, and substitute a command if necessary.
The following code sample enables you to use your custom save procedure for the custom appointment editing form, and processes a custom callback command identifier, so it results in a proper command being executed.
protected void ASPxScheduler1_BeforeExecuteCallbackCommand(object sender,
SchedulerCallbackCommandEventArgs e) {
if (e.CommandId == SchedulerCallbackCommandId.AppointmentSave)
e.Command = new MyAppointmentSaveCallbackCommand((ASPxScheduler)sender);
else if (e.CommandId == "CREATVSPECAPT")
e.Command = new CreateVerySpecialAppointmentCallbackCommand(
(ASPxScheduler)sender);
else if (e.CommandId == "MNUVIEW")
e.Command = new CustomMenuViewCallbackCommand((ASPxScheduler)sender);
else if (e.CommandId == "MNUAPT")
e.Command = new CustomMenuAppointmentCallbackCommand((ASPxScheduler)sender);
}