4.7 Front Events

Front Events allow a standard HTML event to invoke a JavaScript module directly in the browser. Instead of sending the event to the server, a Front Event loads the specified JavaScript module and invokes its exported event function on the client side.

This provides a direct bridge between the WebForms Class and JavaScript modules. The server defines which HTML event should invoke which front-end module, while WebFormsJS performs the client-side execution.

Front Events are particularly useful when an interaction does not require a server request. The event can execute JavaScript locally, manipulate the DOM through the WebForms class available in the module, and optionally return a result to an OutputPlace.

4.7.1 SetFrontEvent

The SetFrontEvent method assigns a JavaScript module to an HTML event. When the specified event occurs, WebFormsJS invokes the module's exported event function.

A basic example assigns front1.js to the click event of Button1:

When Button1 is clicked, WebFormsJS executes the JavaScript module associated with the event.

4.7.2 JavaScript Front Event Module

The module specified by ModulePath is an ES module. The event function is exported from that module and receives the browser event as its first argument.

In this example, the exported PageLoad function receives the event object through evt. It can then create a client-side WebForms instance and generate WebForms Core commands.

The returned value can also contain HTML. In the example, the module returns both an HTML fragment and the result generated by form.exportToHtmlComment().

Note: A Front Event executes in the browser. It does not require a request to the server merely to execute the assigned JavaScript module.

4.7.3 Passing Arguments

SetFrontEvent can receive an optional Args array. These values are passed to the exported module function after the event object.

The corresponding JavaScript function can receive these values after evt:

The event function therefore has the following argument structure:

The event object is supplied by the browser event, while arg1 and arg2 originate from the Args array defined by SetFrontEvent.

The Args parameter uses an object[] on the server side. This allows the caller to provide different types of values according to the requirements of the JavaScript module.

4.7.4 OutputPlace

The optional OutputPlace parameter defines the destination for the value returned by the front-end module.

In this case, the module result is directed to the element identified by Result.

This makes it possible to use a Front Event not only for direct DOM operations inside the module, but also for returning a value to a specific location in the current document.

4.7.5 SetFrontEventListener

SetFrontEventListener provides the EventListener form of Front Events. It uses an HtmlEventListener value instead of an HtmlEvent value.

For example:

The JavaScript module can use the same event-function structure:

The primary distinction is the event definition used by the WebForms class:

4.7.6 Removing Front Events

Existing Front Events can be removed with RemoveFrontEvent and RemoveFrontEventListener.

RemoveFrontEvent removes the Front Event associated with the specified HTML event:

RemoveFrontEventListener removes the EventListener form:

4.7.7 Complete Example

The following example demonstrates both forms of Front Event and passes arguments to a JavaScript module:

The corresponding front1.js module can manipulate the DOM directly through the client-side WebForms class:

The front2.js module demonstrates arguments:

4.7.8 Front Event Architecture

A Front Event follows the WebForms Core Commander-Executor model, but the execution remains entirely on the client side after the event definition has been delivered.

The process can be summarized as:

1. The server-side WebForms class defines the Front Event.
2. The event definition is exported as a WebForms Core Action Control.
3. WebFormsJS reads the Action Control and associates the event with the specified HTML element.
4. When the event occurs, WebFormsJS loads or invokes the specified JavaScript module.
5. The module receives the event and optional arguments.
6. The module can manipulate the DOM through the client-side WebForms class.
7. The module can return a result, which can optionally be directed to an OutputPlace.

This creates a useful division of responsibility. The server can define the behavior of the page without writing the client-side event registration manually, while the actual front-end logic remains in a normal JavaScript module.

4.7.9 Front Events and WebForms Core

Front Events extend the WebForms Core command model to client-side JavaScript execution. They are different from server events such as GET, POST, SSE, or WebSocket events because the event itself does not need to communicate with the server.

A Front Event can therefore be used when the required operation is entirely local to the browser. The JavaScript module can perform calculations, manipulate the DOM, generate WebForms Core commands, or return HTML without requiring a server round trip.

This also makes Front Events complementary to server-side events. An application can use server-side WebForms commands for operations that require server logic and Front Events for operations that can be completed locally.

Note: Front Events do not replace the WebFormsJS runtime. They use WebFormsJS as the browser-side executor that interprets the event definition and manages execution of the assigned module.

4.7.10 Summary

Front Events provide a server-defined mechanism for connecting HTML events to JavaScript modules running in the browser.

With these methods, WebForms Core can define front-end event behavior from the WebForms class while leaving the actual JavaScript implementation in modular client-side code.