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 ofCanContinueExecute
method, and if it istrue
, calls theExecuteCore
method. TheFinalizeExecute
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>|<comma delimited parameters>
Refer to the following table which lists generally used commands, their identifiers and parameters:
Command identifier | Scheduler |
Description | Parameters |
---|---|---|---|
APTCANCEL |
Appointment |
Close the appointment editing form. | - |
APTDATA |
Appointment |
Retrieves the specified appointment properties. | The client appointment id and a list of appointment properties to retrieve. |
APTDATAEX |
Appointment |
Performs a callback to retrieve appointment properties and, after that, executes a specified procedure. | A refresh action id, the client appointment id and a list of properties to retrieve. |
APTDEL |
Appointment |
Delete the appointment edited in the appointment editing form. | - |
APTSAVE |
Appointment |
Save the appointment edited in the appointment editing form. | - |
DLTAPT |
Client |
Deletes the selected appointment. | - |
EDTFRMSHOW |
Appointment |
Show appointment editing form for the appointment with the specified client id. | Appointment client identifier (ASPx |
EDTFRMSHOWSID |
Show |
Show appointment editing form for the appointment with the specified server id. | Appointment identifier (ASPx |
GOTODATE |
Goto |
Set the ASPx |
The number of seconds since 01/01/1970. |
GOTODATEFORM |
Goto |
Invoke the Goto |
- |
GOTODAY |
Goto |
Set the ASPx |
- |
INPLACEFORM |
Inplace |
Invoke the appointment editing form for the appointment currently edited via the inplace editing form. | - |
INPLACESAVE |
Inplace |
Save the appointment edited via the inplace editing form. | - |
INPLACESHOW |
Inplace |
Invoke the inplace editor for the currently selected appointment. | - |
INSRTAPT |
Client |
Inserts an appointment into a storage collection. | A list of property-value pairs for the new appointment. |
REFRESH |
Refresh | Perform an empty callback to reload a page. | - |
SAVT |
Switch |
Switch the View. | Scheduler |
SVGT |
Switch |
Switch the group type. | Scheduler |
TZI |
Change |
Set the ASPx |
A string, the time zone identifier which is valid for the System. property. |
UPDTAPT |
Client |
Updates selected appointment property values. | A list of property-value pairs. |
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.
<dx:ASPxButton runat="server" ID="btnOk" Text="OK" UseSubmitBehavior="False" AutoPostBack="False"
EnableViewState="False" Width="91px" >
<ClientSideEvents Click="function(s, e) {Thanks(s, e);}" />
</dx:ASPxButton>
function Thanks(s, e){
alert('Thanks for saving!');
scheduler.RaiseCallback('APTSAVE|');
scheduler.RaiseCallback('APTCANCEL|');
}
#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 BeforeExecuteCallbackCommand event to intercept a callback command. You can then analyze the 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);
}