DevExpress - Simplifying Server-to-Client Data Transfer with ASPxCallback JSProperties

When building interactive ASP.NET web applications with DevExpress controls, it is common to encounter scenarios where you need to transfer data from the server to the client dynamically. The "JSProperties" property of the "ASPxCallback" control provides an elegant solution for this requirement.

"JSProperties" is a DevExpress specific server-side property that allows you to define custom key-value pairs that are then sent to your client-side JavaScript code as part of the "ASPxCallback" control callback response. These properties can be accessed in JavaScript, enabling seamless communication between server-side logic and client-side functionality, which is very useful for updating UI elements, displaying messages, or handling dynamic interactions without requiring a full page reload.

Some Key Features "JSProperties"
Flexible Data Transfer: Enables passing custom data like strings, numbers, or even JSON objects between server and client.
Easy Integration: The data is accessible via the callback event argument on the client-side using JavaScript.
Customizable Keys: Keys must start with the "cp" prefix (e.g., cpMyProperty).

Practical Use Cases
Displaying Status Messages: Inform users of the result of a server-side operation.
Updating UI Components Dynamically: Pass calculated values or server-generated data to update client-side UI elements.
Passing Validation Results: Validate user input server-side and relay feedback to the client.

In this example code, I show how JSProperties works and provide a very basic example.

Using ASPxCallbackPanel with Custom Client-Server Interaction
In this example usage, an "ASPxCallbackPanel" hosts an "ASPxButton" (named clibtn_test) and an "ASPxTextBox" (named cli_MyTextBox) within its "PanelContent" collection. The callback mechanism is defined using the "OnCallback" server-side event handler "MyCallbackPanel_Callback" and the "EndCallback" client-side event handler "CliMyCallbackPanel_EndCallback."

Server-Side Callback Handling
During the server-side callback (MyCallbackPanel_Callback), custom properties are assigned to the JSProperties collection based on the operation's outcome:

Success Case
CaseInfo_CallbackPanel.JSProperties["cp_status"] = "success";
CaseInfo_CallbackPanel.JSProperties["cp_message"] = "success";
On success, these properties indicate a successful operation with appropriate status and message.

Error Case
CaseInfo_CallbackPanel.JSProperties["cp_status"] = "error";
CaseInfo_CallbackPanel.JSProperties["cp_message"] = $"{ex.Message}";
On failure, the properties convey the error status and detailed exception message.

Client-Side Interaction
The "CliMyCallbackPanel_EndCallback" client-side handler processes the callback response by:

1. Setting the text of cli_MyTextBox to the value of cp_message (retrieved from the server).
2. Clearing any existing value of s.cp_function to reset its state.

Key Benefits
This (very basic) sample highlights how "JSProperties" simplifies dynamic client-server communication in DevExpress "ASPxCallbackPanel". It allows passing detailed operational results, ensuring the UI updates responsively and informs the user of the operation's outcome.

Example Usage
Define the ASPxCallbackPanel in the ASP.NET Form
Define the "ASPxCallbackPanel" with an "ID", "ClientInstanceName", "OnCallback" server-side event, and both an "ASPxButton" with a "ClientSideEvents" definition and a client visible/client disabled "ASPxTextBox" in the panel collection content.

<dx:ASPxCallbackPanel
ID="CaseInfo_CallbackPanel"
ClientInstanceName="cliCaseInfo_CallbackPanel"
runat="server"
ClientVisible="true"
OnCallback="MyCallbackPanel_Callback">
<ClientSideEvents EndCallback="CliMyCallbackPanel_EndCallback" />
<PanelCollection>
  <dx:PanelContent ID="PanelContent2" runat="server">
      <table border="0">
      <tr>
      <td>
        <dx:ASPxButton
        ID="btn_test"
        ClientInstanceName="clibtn_test"
        ClientVisible="true"
        AutoPostBack="false"
        UseSubmitBehavior="false"
        runat="server"
        Text="click here">
        <ClientSideEvents Click="function(s, e){ DoClick('button_click'); }" />
        </dx:ASPxButton>
      </td>
      </tr>

      <tr>
      <td>
        <dx:ASPxTextBox
        ClientEnabled="false"
        ClientVisible="true"
        Width="200px"
        ID="MyTextBox"
        ClientInstanceName="cli_MyTextBox"
        runat="server"
        Text="">
        </dx:ASPxTextBox>
      </td>
      </tr>
      </table>
  </dx:PanelContent>
</PanelCollection>
</dx:ASPxCallbackPanel>

The Client-side JavaScript for the ASPxButton ClientSideEvents Click Event
This client-side JavaScript code is run when the user clicks on the "ASPxButton". If the "_user_option" variable equals 'button_click' then force a callback on the "cliCaseInfo_CallbackPanel" CallbackPanel, else do nothing.

function Do_Click(_user_option)
{
  if (_user_option === 'button_click')
  {
    // force a callback on the CallbackPanel
    cliCaseInfo_CallbackPanel.PerformCallback('button_click');
  }
}

Server-Side C# Code
This server-side code is run when the "ASPxCallbackPanel" does a callback when initiated by the "ASPxButton" and the "Do_Click" function. This server-side code is defined in the "OnCallback" property of the "ASPxCallbackPanel".

protected void MyCallbackPanel_Callback(object sender, DevExpress.Web.CallbackEventArgsBase e)
{
  if (Regex.IsMatch(e.Parameter, "button_click")) // sent here from javascript Do_Click function
  {
    try
    {

      // your server code here
      // do something here

      // assign "success" values to custom propertiesfor the client-side
      CaseInfo_CallbackPanel.JSProperties["cp_status"] = "success";
      CaseInfo_CallbackPanel.JSProperties["cp_message"] = "success";
    }
    catch (Exception ex)
    {
      // assign "error" values to custom propertiesfor the client-side
      CaseInfo_CallbackPanel.JSProperties["cp_status"] = "error";
      CaseInfo_CallbackPanel.JSProperties["cp_message"] = $"{ex.Message}";
    }
  }
  else
  {
    // assign "nothing to process" values to custom propertiesfor the client-side
    // this not required but is here as a just in case
    CaseInfo_CallbackPanel.JSProperties["cp_status"] = "nothing to process";
    CaseInfo_CallbackPanel.JSProperties["cp_message"] = "nothing to process";
  }

  return;
}

The Client-side JavaScript for the cliCaseInfo_CallbackPanel ClientSideEvents EndCallback Event
This client-side JavaScript is run after the "ASPxCallbackPanel" callback completes. You could interact with other client controls here, such as setting a text box value, checking a checkbox, etc. Here I am setting the "Text" value of the "cli_MyTextBox" "ASPxTextBox" and then deleting the "s.cp_function" value.

function CliMyCallbackPanel_EndCallback(s, e)
{
  var message = s.cpMessage;
  var status = s.cpStatus;

  if (status === "Success" || status === "nothing to process")
  {
    // set text box to the value of message (s.cpMessage)
    cli_MyTextBox.SetText(message);
  }
  else
  {
    console.error("Callback failed");
  }

  // just doing a little clean up here
  delete (s.cp_function);
}

Conclusion
The "JSProperties" feature of the "ASPxCallback" control is an easy method to bridge the gap between server-side logic and client-side interactions. Using the transfer of custom key-value pairs during callbacks helps with dynamic, user friendly, and responsive user interfaces without the overhead of full-page postbacks.

The "JSProperties" feature is handy with displaying server-side validation results, updating UI components dynamically, or passing custom messages to the client with its straightforward key-value structure.