Custom Event in WebForms Core 2

We at Elanat dare to say that WebForms Core 2 is one of the biggest software updates in history. With over 50 new features and capabilities, this version will significantly surpass front-end frameworks like React, Vue, and Angular, and will give web developers an experience beyond imagination on the server. We at Elanat will amaze the web world! WebForms Core 2 is not trying to be a front-end framework — it’s a full-stack reactive engine that gives you the power of modern web apps with the simplicity of server-driven logic.

Why WebForms Core is a revolution?

It’s not just a framework — it’s a new philosophy:

“Let the server drive the UI, but give the client intelligence.”

That’s revolutionary. It challenges the dominance of client-heavy frameworks and offers a simpler, faster, more secure alternative — especially for large-scale apps.

As promised, before presenting WebForms Core 2, we will describe its features in detail. One of the most powerful features of version 2 of WebForms Core technology is custom events.

Introduction

In modern web development, it’s often necessary to trigger an event automatically when specific changes occur in an HTML element — such as when its attributes, style, text content, child nodes, or input values are modified.

Browsers provide many built-in events like click, input, change, and mouseover, but they don’t always cover every use case.
Sometimes, we need custom events that are dispatched dynamically based on DOM mutations or specific conditions.

That’s exactly where the CreateCustomDOMEvent method comes in.

---

Purpose of CreateCustomDOMEvent

The CreateCustomDOMEvent method creates custom DOM events that are automatically triggered whenever certain conditions in an element’s state are met — for example, when an attribute changes, text updates, or a specific input value appears.

In other words, it acts as a smart observer that monitors an element for changes and dispatches an event only when your defined conditions become true — just like a user-triggered action.

---

Function Signature

Here’s the general function definition:

CreateCustomDOMEvent(
InputPlace,      // DOM element
EventName,    // name of the custom event
Watch,        // what to observe: 'attribute', 'style', 'text', 'children', 'value'
Key,          // the attribute or style key to check
Compare,      // comparison type: 'greater',  'less',  'equal',  'notequal',  'includes',  'startswith',  'endswith',  'matches',  'changed',  'inrange',  'lengthgreater',  'lengthless',  'lengthequal'
Value,        // reference value for comparison
Range,        // numeric range for 'inrange' comparisons
Immediate,    // whether to check immediately upon setup
Delay         // delay in milliseconds (for throttle/debounce)
)

---

Supported Observation Types (Watch)

The function can monitor several types of DOM changes:

watch	Description
'attribute'	Observes a specific attribute (e.g., src, data-id)
'style'	Observes computed style values (e.g., display, opacity)
'text'	Observes text content changes
'children'	Observes changes to child elements or DOM structure
'value'	Observes input, textarea, or select value changes

---

Comparison Modes (Compare)

You can control how the current value is compared to the expected one.

compare	Description
'equal'	Fires when current value equals the target
'notequal'	Fires when values differ
'changed'	Fires when the value changes from its last known state
'greater', 'less', 'inrange'	Numeric comparisons
'includes', 'startswith', 'endswith', 'matches'	String-based conditions
'lengthgreater', 'lengthless', 'lengthequal'	Compare string length or number of children

This makes the function incredibly flexible for many use cases — from simple equality checks to regex matches.

---

Built-in Throttle and Debounce

The Delay parameter adds throttle/debounce behavior internally.
That means even if the DOM changes very rapidly, the event is triggered at controlled intervals.

This significantly improves performance, especially when observing rapidly changing nodes or user input.

---

Control Methods: pause, resume, disconnect

In WebFormsJS, there is also a synchronized method of the same name that is very powerful.

The function returns a controller object, allowing full runtime control:

const watcher = cb_CreateCustomDOMEvent(...);

watcher.pause();      // temporarily stop observing
watcher.resume();     // resume observation
watcher.disconnect(); // completely stop observing

This is useful when you want to pause observation during heavy DOM updates or animations.

---

Example: Observing an Input Field

HTML

<input id="nameBox" type="text" placeholder="Type 'hello'">

Server Code

WebForms form = new WebForms();
form.CreateCustomDOMEvent("nameBox", "nameMatched", "value", "equal", "hello", 200)
form.SetGetEventListener("nameBox", "nameMatched", "/path-of-handling");
Write(form.Response());

In this example:

• When the user types the exact word "hello",
• The custom event nameMatched is dispatched,
• The corresponding handler is executed,
• And corresponding handler also requests the "/path-of-handling" path from the server.

Example: Observing on Tag Text

HTML

<div id="price">85</div>

Server Code

WebForms form = new WebForms();
form.CreateCustomDOMEvent("price", "priceHigh", "text", "greater", "100", 200)
form.SetGetEventListener("price", "priceHigh", "/path-of-handling2");
Write(form.Response());

In this example:

• When the text inside the tag exceeds 100,
• The custom event priceHigh is dispatched,
• The corresponding handler is executed,
• And corresponding handler also requests the "/path-of-handling2" path from the server.

---

Advantages of Custom DOM Event feature

1. 🧠 Smart DOM Change Detection
   No need to manually handle multiple MutationObservers — a single, simple function handles all logic.

2. ⚡ Powerful Conditional Logic
   You can define complex triggers using numeric, string, or regex comparisons.

3. 🕹️ Lightweight Control
   Easily pause, resume, or disconnect observers to save resources.

4. ⏳ Optimized Performance
   Built-in throttling/debouncing ensures efficient event dispatching.

5. 🧩 Works with All DOM Elements
   Attributes, styles, children, and form values — all supported.

6. 🪄 HTML Handler Support
   Just like native events, you can use inline handlers:
   

   <div id="box" oncolorChange="myHandler"></div>

---

Real-World Use Cases

• Detecting changes in element visibility or CSS styling
• Running animations or transitions when specific attributes change
• Monitoring user input dynamically without using traditional events
• Tracking DOM structure updates (added/removed children)
• Building reactive components from server without front-end frameworks like Vue or React

---

Summary

The CreateCustomDOMEvent function is a powerful utility for building lightweight reactive systems in plain JavaScript.
It bridges MutationObserver, Event API, and custom conditional logic, letting you define your own event triggers declaratively.

Simply put, it allows you to say:

“Whenever this element changes in this specific way — fire a custom event.”