4.4 SSE Events

Server-Sent Events (SSE) allows a server to continuously send events to a connected browser over a persistent HTTP connection. WebForms Core provides SSE Event methods that allow an HTML event to establish an SSE connection to a server endpoint and receive WebForms Core Action Controls from that connection.

In this model, the HTML event is defined by the server through the WebForms class, while WebFormsJS manages the SSE connection and executes the Action Controls received from the server.

The execution flow can be represented as:

HTML Event → WebFormsJS → SSE Connection → Backend → SSE Response → WebFormsJS → Action Controls

Important: WebForms Core is not dependent on any specific programming language, Backend, or web development ecosystem. SSE itself must therefore be implemented using the SSE capabilities provided by the Backend or server environment used by your application. In the following example, the server-side SSE endpoints are implemented with the CodeBehind Framework. WebForms Core only defines the client-side SSE event behavior and the format of the WebForms Core commands returned through the SSE connection.

4.4.1 SetSSEEvent

The SetSSEEvent method assigns an SSE connection to an HTML event. When the specified event occurs, WebFormsJS connects to the specified SSE endpoint.

form.SetSSEEvent("RandomButton", HtmlEvent.OnClick, "/sse/random");

The basic signature is:

public void SetSSEEvent(string InputPlace, string HtmlEvent, string Path, bool ShouldReconnect = true, int ReconnectTryTimeout = 3000)

Parameter	Description
InputPlace	The WPC expression identifying the HTML element on which the event is assigned.
HtmlEvent	The HTML event that starts the SSE connection.
Path	The Backend endpoint that provides the SSE response.
ShouldReconnect	Determines whether WebFormsJS should attempt to reconnect when the SSE connection is interrupted. The default value is true.
ReconnectTryTimeout	The interval in milliseconds used for a reconnection attempt. The default value is 3000.

For example, the following event starts an SSE connection when the button is clicked:

form.SetSSEEvent("RandomButton", HtmlEvent.OnClick, "/sse/random", true, 5000);

In this example, WebFormsJS attempts to reconnect after an interrupted connection using the configured reconnection interval.

4.4.2 SetSSEEvent with OutputPlace

An overload of SetSSEEvent accepts an OutputPlace. This allows the SSE response to be associated with a specific output location.

form.SetSSEEvent("RandomButton", HtmlEvent.OnClick, "/sse/random", "Random");

The signature is:

public void SetSSEEvent(string InputPlace, string HtmlEvent, string Path, string OutputPlace, bool ShouldReconnect = true, int ReconnectTryTimeout = 3000)

When an OutputPlace is specified, the received output can be directed to that location according to the WebForms Core response processing rules.

The reconnection options can also be specified:

form.SetSSEEvent("RandomButton", HtmlEvent.OnClick, "/sse/random", "Random", true, 5000);

4.4.3 SetSSEEventListener

SetSSEEventListener provides the EventListener form of SSE Event assignment.

form.SetSSEEventListener("TimeButton", HtmlEventListener.Click, "/sse/get-time");

The basic signature is:

public void SetSSEEventListener(string InputPlace, string HtmlEventListener, string Path, bool ShouldReconnect = true, int ReconnectTryTimeout = 3000)

The difference between SetSSEEvent and SetSSEEventListener is the event mechanism used to trigger the SSE connection. The first uses HtmlEvent, while the second uses HtmlEventListener.

4.4.4 SetSSEEventListener with OutputPlace

The listener-based method also supports an OutputPlace.

form.SetSSEEventListener("TimeButton", HtmlEventListener.Click, "/sse/get-time", "TimeResult");

The signature is:

public void SetSSEEventListener(string InputPlace, string HtmlEventListener, string Path, string OutputPlace, bool ShouldReconnect = true, int ReconnectTryTimeout = 3000)

For example:

form.SetSSEEventListener("TimeButton", HtmlEventListener.Click, "/sse/get-time", "TimeResult", true, 5000);

4.4.5 RemoveSSEEvent

The RemoveSSEEvent method removes an SSE event assigned with SetSSEEvent from the specified HTML element.

form.RemoveSSEEvent("RandomButton", HtmlEvent.OnClick);

The method signature is:

public void RemoveSSEEvent(string InputPlace, string HtmlEvent)

Parameter	Description
InputPlace	The WPC expression identifying the HTML element from which the SSE event is removed.
HtmlEvent	The HTML event associated with the SSE event.

For example, if an SSE connection was previously assigned to the click event of RandomButton, the following command removes that assignment:

form.RemoveSSEEvent("RandomButton", HtmlEvent.OnClick);

This method removes the event assignment. It does not define a new SSE endpoint or create another connection.

4.4.6 RemoveSSEEventListener

The RemoveSSEEventListener method removes an SSE event assigned through SetSSEEventListener.

form.RemoveSSEEventListener("TimeButton", HtmlEventListener.Click);

The method signature is:

public void RemoveSSEEventListener(string InputPlace, string HtmlEventListener)

Parameter	Description
InputPlace	The WPC expression identifying the HTML element from which the SSE listener is removed.
HtmlEventListener	The event listener associated with the SSE event.

For example:

form.RemoveSSEEventListener("TimeButton", HtmlEventListener.Click);

This removes the listener-based SSE event assignment from the selected element.

4.4.7 Set and Remove SSE Events

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

Set Method	Remove Method
SetSSEEvent	RemoveSSEEvent
SetSSEEventListener	RemoveSSEEventListener

For example, an SSE event can first be assigned to a button and later removed:

form.SetSSEEvent("RandomButton", HtmlEvent.OnClick, "/sse/random"); form.RemoveSSEEvent("RandomButton", HtmlEvent.OnClick);

Similarly, a listener-based SSE event can be assigned and removed:

form.SetSSEEventListener("TimeButton", HtmlEventListener.Click, "/sse/get-time"); form.RemoveSSEEventListener("TimeButton", HtmlEventListener.Click);

The removal methods identify the existing event assignment by the selected element and its event type. They do not require the SSE Path because the purpose of the removal command is to remove the event assignment itself.

4.4.8 Receiving WebForms Core Commands Through SSE

The SSE endpoint can return WebForms Core Action Controls instead of sending application-specific data that must then be interpreted by custom JavaScript.

For example, the server can create a WebForms instance and generate a DOM update:

var form = new WebForms(); form.SetText("Random", new Random().Next(100000, 99999999).ToString()); BroadcastSSE(context, form.ExportToLineBreak());

Here, SetText creates a WebForms Core Action Control. The Action Control is then converted to the line-based representation required for an SSE response.

ExportToLineBreak() is specifically provided for SSE responses. It converts the WebForms Core response into a single-line representation compatible with the SSE transmission format.

4.4.9 CodeBehind SSE Endpoint

The following example shows a complete SSE endpoint implemented using CodeBehind. The Backend opens the SSE response and periodically sends WebForms Core commands to the connected browser.

using CodeBehind; public partial class RandomSSEController : CodeBehindController { public void PageLoad(HttpContext context) { EnableSSE(); Task.Run(async () => { while (true) { await Task.Delay(5000); var form = new WebForms(); form.SetText("Random", new Random().Next(100000, 99999999).ToString()); BroadcastSSE(context, form.ExportToLineBreak()); } }); } }

The important point is that EnableSSE() and BroadcastSSE() belong to the Backend implementation in this example. They are not WebForms Core methods. They are used by CodeBehind to establish and maintain the server-side SSE response.

WebForms Core only needs the resulting SSE response to contain the appropriate WebForms Core command format. The browser-side WebFormsJS runtime receives the response and executes the commands.

4.4.10 Continuous Server Updates

SSE is particularly useful when the server needs to continuously send updates without requiring a new request for every update.

For example, the following endpoint sends the current server time every five seconds:

using CodeBehind; public partial class GetTimeSSEController : CodeBehindController { public void PageLoad(HttpContext context) { EnableSSE(); Task.Run(async () => { while (true) { await Task.Delay(5000); var form = new WebForms(); string serverTime = DateTime.Now.ToString("HH:mm:ss"); form.SetText("TimeResult", $"Current Server Time: {serverTime}"); BroadcastSSE(context, form.ExportToLineBreak()); } }); } }

The browser does not need to repeatedly request the server for the time. After the SSE connection has been established, the server can continuously send new WebForms Core commands through the connection.

4.4.11 Complete Client-Side Example

The following example assigns three SSE connections to three different HTML events. The first two use HtmlEvent, while the third uses HtmlEventListener.

using CodeBehind; public partial class SSEController : CodeBehindController { public void PageLoad(HttpContext context) { WebForms form = new WebForms(); form.SetSSEEvent("RandomButton", HtmlEvent.OnClick, "/sse/random"); form.SetSSEEvent("ChangeColorButton", HtmlEvent.OnClick, "/sse/change-color"); form.SetSSEEventListener("TimeButton", HtmlEventListener.Click, "/sse/get-time"); Write(form.ExportToHtmlComment()); } }

The resulting Action Controls are returned to the browser as an HTML comment. WebFormsJS reads the commands and assigns the SSE behavior to the specified elements.

4.4.12 SSE and WebForms Core Architecture

SSE does not change the fundamental WebForms Core execution model. It changes the transport used for delivering commands from the server to the browser.

Instead of a conventional request followed by a single response, the server can keep an SSE connection open and send multiple WebForms Core command responses over time.

Server ↓ WebForms ↓ WebForms Core Action Controls ↓ SSE Response ↓ WebFormsJS ↓ HTML DOM

This allows the same WebForms Core command protocol to be used for both immediate server responses and continuous server-to-browser updates.

4.4.13 Summary

• SetSSEEvent assigns an SSE connection to an HTML event.
• SetSSEEventListener provides the listener-based form.
• Both methods support automatic reconnection.
• ReconnectTryTimeout specifies the reconnection interval in milliseconds.
• Both methods provide overloads with OutputPlace.
• SSE endpoints are implemented by the Backend and are not tied to WebForms Core.
• The server can send WebForms Core Action Controls through an SSE connection.
• ExportToLineBreak() produces the WebForms Core response representation intended for SSE transmission.

Because WebForms Core is independent of the Backend ecosystem, the same SSE Event mechanism can be used with any server environment capable of providing SSE. The Backend is responsible for maintaining the SSE connection and producing the stream, while WebFormsJS is responsible for receiving and executing the WebForms Core commands.