4.5 WebSocket Events

WebSocket Events allow WebForms Core to establish a WebSocket connection in response to an HTML event. The server defines the WebSocket event through the WebForms class, and WebFormsJS establishes the connection when the specified browser event occurs.

The basic execution flow is:

Important: WebForms Core is independent of any programming language, Backend, or web development ecosystem. Therefore, WebSocket communication on the server must be implemented using the WebSocket capabilities provided by the Backend or server environment used by your application. The WebForms Core WebSocket Event methods only define how WebFormsJS establishes and manages the client-side connection. The server-side WebSocket implementation is the responsibility of the Backend.

In the following examples, the WebSocket server-side functionality is implemented with the CodeBehind Framework. CodeBehind provides the WebSocket connection management and broadcasting capabilities used by the example.

4.5.1 SetWebSocketEvent

The SetWebSocketEvent method assigns a WebSocket connection to an HTML event. When the specified event occurs, WebFormsJS establishes a WebSocket connection to the specified path.

The method signature is:

For example:

When the selected button is clicked, WebFormsJS uses the specified path to establish the WebSocket connection.

4.5.2 SetWebSocketEventListener

SetWebSocketEventListener provides the EventListener form of WebSocket Event assignment.

The method signature is:

The main difference between SetWebSocketEvent and SetWebSocketEventListener is the event mechanism used by WebFormsJS. The first receives an HtmlEvent, while the second receives an HtmlEventListener.

4.5.3 WebSocket Connection on User Interaction

A WebSocket Event does not necessarily establish the connection when the page is initially loaded. In the following example, the WebSocket Event is first assigned to a button. The connection is established when the user clicks the button.

In this example, the WebSocket capability is already enabled on the server-side controller path. However, the WebFormsJS WebSocket connection is established after the user performs the specified event, which is the button click.

The listener-based form can therefore be used to make the WebSocket connection event-driven rather than establishing the client connection immediately when the page is loaded.

4.5.4 WebSocket Event with HtmlEvent

The following example uses the regular HTML Event mechanism:

Here, SetWebSocketEvent assigns the WebSocket connection to the click event. After the user clicks the button, WebFormsJS establishes the WebSocket connection.

The two forms can therefore be summarized as:

4.5.5 Removing a WebSocket Event

The RemoveWebSocketEvent method removes a WebSocket Event assigned through SetWebSocketEvent.

The method signature is:

The method identifies the target element and the HTML event from which the WebSocket Event should be removed.

4.5.6 Removing a WebSocket Event Listener

The RemoveWebSocketEventListener method removes a WebSocket Event Listener assigned through SetWebSocketEventListener.

The method signature is:

The removal methods do not require the WebSocket Path. They identify the existing assignment through the selected element and event definition.

4.5.7 Set and Remove WebSocket Events

The WebSocket Event API provides a corresponding removal method for each assignment mechanism:

For example:

Similarly, a listener-based assignment can be removed with:

4.5.8 Server-Side WebSocket Broadcasting

Once the WebSocket connection has been established, the Backend can send data or WebForms Core Action Controls through the connection.

For example, the CodeBehind Framework can broadcast a WebForms Core response to all active WebSocket connections:

The same response can also be sent to a specific WebSocket connection when the Backend provides connection identification:

In this example, Broadcast sends the response to active WebSocket connections, while BroadcastForWebSocketId targets a specific connection identified by websocket1.

These broadcasting methods are part of the CodeBehind server-side WebSocket implementation in this example. They are not WebForms Core WebSocket Event methods.

4.5.9 WebSocket Responses as WebForms Core Commands

A significant feature of using WebSockets with WebForms Core is that the server can send WebForms Core Action Controls through the connection.

For example:

The server does not need to send a complete HTML document or a separate JSON representation of the UI state. It can send WebForms Core commands, and WebFormsJS executes those commands in the browser.

This preserves the WebForms Core command-oriented communication model even when WebSocket is used as the transport.

4.5.10 WebSocket Events and the Backend

WebForms Core does not provide a replacement for the WebSocket implementation of the Backend. Instead, it provides a standardized client-side event mechanism through WebFormsJS.

The responsibilities can therefore be separated as follows:

This separation allows WebForms Core to remain independent of the technology used to implement WebSocket communication on the server.

4.5.11 WebSocket Capabilities Beyond WebSocket Events

WebSocket support in WebForms Core is broader than the two event-assignment methods described in this section. The technology provides additional WebSocket methods and capabilities for managing WebSocket communication, connections, requests, broadcasting, and other operations.

Those capabilities are intentionally not covered in this section. They will be documented separately in a complete WebSocket section.

4.5.12 Summary

• SetWebSocketEvent assigns a WebSocket connection to an HtmlEvent.
• SetWebSocketEventListener assigns a WebSocket connection to an HtmlEventListener.
• The WebFormsJS WebSocket connection is established when the assigned browser event occurs.
• RemoveWebSocketEvent removes an event assigned through SetWebSocketEvent.
• RemoveWebSocketEventListener removes an event listener assigned through SetWebSocketEventListener.
• The WebSocket server and connection management must be provided by the application's Backend.
• WebForms Core can use WebSocket as a transport for WebForms Core Action Controls.
• WebSocket support in WebForms Core includes additional capabilities that are documented separately.