Callback Commands

  • 6 min 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>

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);
}
See Also